الحلّ ورحلات التوصيل عند الطلب متاح حاليًا لشركاء محدّدين فقط. يمكنك التواصل مع فريق المبيعات لمعرفة المزيد من المعلومات.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تتبُّع أسطولك باستخدام مكتبة JavaScript FleetTracking

تتوفّر هذه الميزة أو المنتج في مرحلة المعاينة (مرحلة ما قبل التوفّر للجمهور العام). قد يكون دعم المنتجات والميزات المتوفرة في مرحلة ما قبل التوفّر للجمهور العام محدودًا، وقد لا تتوافق التغييرات التي يتم إجراؤها على منتجات وميزات ما قبل التوفّر للجمهور العام مع الإصدارات الأخرى المتوفّرة للجمهور العام. تغطي "عروض مرحلة ما قبل التوفّر للجمهور العام" الأحكام الخاصة بخدمة "منصة خرائط Google". لمزيد من المعلومات، يمكنك الاطّلاع على أوصاف مرحلة الإطلاق.

تسمح لك مكتبة JavaScript Fleet Tracking Library (مكتبة تتبُّع أساطيل JavaScript) بعرض مواقع المركبات في أساطيلك في الوقت الفعلي تقريبًا. تستخدم المكتبة واجهة برمجة التطبيقات للرحلات والتسليمات عند الطلب للسماح بالتصوير المرئي للمركبات والرحلات. تحتوي "مكتبة تتبُّع مجموعة JavaScript" على مكوِّن خريطة JavaScript يحلّ محلّ عنصر google.maps.Map عادي ومكوّنات البيانات التي يمكن ربطها مع Fleet Engine.

المكوّنات

توفّر مكتبة JavaScript Fleet Tracking Library (مكتبة تتبُّع أسطول JavaScript) مكوّنات لعرض المركبات ونقاط الطريق، بالإضافة إلى خلاصات البيانات الأولية لالوقت المقدّر للوصول أو المسافة المتبقية إلى الرحلة.

عرض الخريطة الخاصة بتتبع الأسطول

يتصور عنصر عرض الخريطة "تتبع الأسطول" موقع المركبات ونقاط الطريق. إذا كان مسار المركبة معروفًا، يحرّك مكون عرض الخريطة تلك المركبة أثناء تحرّكها على طول المسار المتوقع.

مثال على عرض الخريطة
لتتبع الأسطول

مقدمو خدمة المواقع الجغرافية

يعمل مقدمو المواقع الجغرافية باستخدام المعلومات المخزنة في Fleet Engine لإرسال معلومات الموقع الخاصة بالكائنات التي يتم تتبعها إلى خريطة مشاركة الرحلة.

مقدِّم خدمة الموقع الجغرافي للمركبة

يعرض مزوِّد خدمة الموقع الجغرافي للمركبة معلومات الموقع الجغرافي لمركبة واحدة. ويحتوي على معلومات عن موقع المركبة والرحلة الحالية المحددة للمركبة.

مقدِّم خدمة الموقع الجغرافي لمجموعة الأجهزة

يعرض مقدّم خدمة الموقع الجغرافي لمجموعة مركبات معلومات الموقع الجغرافي لمركبات متعددة. يمكنك فلترة البيانات لعرض مركبة معيّنة وموقعها الجغرافي أو يمكنك عرض المواقع الجغرافية للمركبات بأكملها.

التحكم في مستوى رؤية المواقع التي يتم تتبعها

تحدد قواعد الرؤية متى يكون عنصر الموقع الذي تم تتبعه مرئيًا على الخريطة لمزوّد الموقع Fleet Engine. ملاحظة: قد يؤدي استخدام موفّر موقع جغرافي مخصّص أو مشتق إلى تغيير قواعد مستوى الظهور.

مركبات

تظهر مركبة فور إنشائها في Fleet Engine، وتكون مرئية عندما تكون قيمة المَعلمة_state هي Online. هذا يعني أن المركبة يمكن أن تكون مرئية حتى في حال عدم وجود رحلة حالية مخصصة للمركبة.

علامات المواقع الجغرافية لنقاط الطريق

تشير علامة موقع نقطة الطريق إلى نقاط على طول رحلة المركبة بدءًا من نقطة الانطلاق وتنتهي بالوجهة النهائية. يمكن تحديد علامات موقع نقطة الطريق كما يلي:

نقطة الانطلاق: تشير إلى موقع انطلاق رحلة المركبة.
متوسّط: يشير إلى محطات التوقف لرحلة المركبة.
الوجهة - تشير إلى الموقع النهائي لرحلة المركبة

يتم عرض نقاط الطريق المخططة للمركبات على الخريطة كعلامات أصل ووسيط ووجهة.

بدء استخدام مكتبة JavaScript Fleet Tracking Library (مكتبة تتبُّع مجموعة JavaScript)

قبل استخدام مكتبة JavaScript Fleet Tracking Library (مكتبة تتبُّع مجموعة JavaScript)، تأكّد من أنّك على عِلم بمحرّك Fleet Engine ومن توفّر مفتاح واجهة برمجة تطبيقات (API) فيه. بعد ذلك، يمكنك إنشاء مطالبة بمعرّف الرحلة ومعرّف المركبة.

إنشاء مطالبة بمعرّف الرحلة ومعرّف المركبة

لتتبُّع المركبات باستخدام موفِّر الموقع الجغرافي للمركبة، يمكنك إنشاء رمز JSON المميّز للويب (JWT) مع المطالبة بمعرّف الرحلة ومعرّف المركبة.

لإنشاء حمولة بيانات JWT، عليك إضافة مطالبة أخرى في قسم التفويض باستخدام المفتاحَين tripid وvehicleid وضبط value لكل مفتاح على *. يجب إنشاء الرمز المميّز باستخدام دور "إدارة الهوية وإمكانية الوصول" في السحابة الإلكترونية للمستخدم في خدمة Fleet Engine. تجدر الإشارة إلى أنّ هذا الإجراء يمنح إمكانية وصول واسع النطاق لإنشاء كيانات Fleet Engine وقراءتها وتعديلها، ويجب عدم مشاركتها إلا مع مستخدمين موثوق بهم.

يوضح المثال التالي كيفية إنشاء رمز مميز للتتبع حسب المركبة والمهمة:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
  "sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "scope": "https://www.googleapis.com/auth/xapi",
  "authorization": {
    "tripid": "*",
    "vehicleid": "*",
  }
}

إنشاء أداة استرجاع الرمز المميّز للمصادقة

وتطلب مكتبة تتبُّع مجموعة JavaScript رمزًا مميزًا باستخدام استرجاع الرمز المميّز للمصادقة عندما يكون أيٌّ ممّا يلي صحيحًا:

لا يتضمن رمزًا مميزًا، على سبيل المثال عندما لا يستدعي الجلب عند تحميل صفحة جديدة، أو عندما لا يستدعي الجلب رمزًا مميزًا.
انتهت صلاحية الرمز المميّز الذي تم استرجاعه سابقًا.
ويكون الرمز المميّز الذي تم استرجاعه سابقًا في غضون دقيقة واحدة من انتهاء صلاحيته.

بخلاف ذلك، تستخدم المكتبة الرمز المميّز الذي تم إصداره مسبقًا، ولا يزال صالحًا، ولا تستدعي الجلب.

يمكنك إنشاء استرجاع رمز مميّز للمصادقة لاسترداد رمز مميّز تم إنشاؤه باستخدام المطالبات المناسبة على خوادمك باستخدام شهادة حساب خدمة لمشروعك. من المهم إنشاء رموز مميزة على خوادمك فقط وعدم مشاركة شهاداتك مع أي عملاء مطلقًا. خلاف ذلك، قد تعرّض أمان نظامك للخطر.

يجب أن يعرض الجلب بنية بيانات بحقلين، ملتفين بوعد:

سلسلة token.
رقم expiresInSeconds تنتهي صلاحية الرمز المميز في هذه المدة الزمنية بعد الجلب.

يوضّح المثال التالي كيفية إنشاء أداة استرجاع الرمز المميّز للمصادقة:

JavaScript

function authTokenFetcher(options) {
  // options is a record containing two keys called
  // serviceType and context. The developer should
  // generate the correct SERVER_TOKEN_URL and request
  // based on the values of these fields.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.Token,
    expiresInSeconds: data.ExpiresInSeconds
  };
}

TypeScript

function authTokenFetcher(options: {
  serviceType: google.maps.journeySharing.FleetEngineServiceType,
  context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
  // The developer should generate the correct
  // SERVER_TOKEN_URL based on options.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.token,
    expiresInSeconds: data.expiration_timestamp_ms - Date.now(),
  };
}

عند تنفيذ نقطة النهاية من جهة الخادم لاستخراج الرموز المميزة، ضع ما يلي في الاعتبار:

يجب أن تعرض نقطة النهاية وقت انتهاء صلاحية الرمز المميّز. في المثال أعلاه، يتم تحديده على أنّه data.ExpiresInSeconds.
يجب أن يمرر استرجاع الرمز المميّز للمصادقة وقت انتهاء الصلاحية (بالثواني، من وقت الجلب) إلى المكتبة، كما هو موضَّح في المثال.
يعتمد SERVER_TOKEN_URL على تنفيذ الواجهة في الخلفية، وفي ما يلي أمثلة على عناوين URL:
- https://SERVER_URL/token/driver/VEHICLE_ID
- https://SERVER_URL/token/consumer/TRIP_ID
- https://SERVER_URL/token/fleet_reader

تحميل خريطة من HTML

يوضح المثال التالي كيفية تحميل مكتبة "مشاركة رحلة JavaScript" من عنوان URL محدّد. تنفذ المعلمة callback الدالة initMap بعد تحميل واجهة برمجة التطبيقات. السمة defer تتيح للمتصفح مواصلة عرض باقي صفحتك أثناء تحميل واجهة برمجة التطبيقات.

 <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing&v=beta" defer></script>

متابعة مركبة

يوضّح هذا القسم كيفية استخدام مكتبة JavaScript Fleet Tracking Library (مكتبة تتبُّع مجموعة JavaScript) لمتابعة إحدى المركبات. تأكّد من تحميل المكتبة من دالة الاستدعاء المحدّدة في علامة النص البرمجي قبل تشغيل الرمز.

إنشاء مثيل لمقدِّم الموقع الجغرافي للمركبة

تحدّد مكتبة JavaScript Fleet Tracking Library مسبقًا موفّر الموقع الجغرافي لواجهة برمجة التطبيقات On Demand Rides and Deliveries API. استخدم معرف المشروع ومرجعًا إلى مصنع الرموز المميزة لإنشاء مثيل له.

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineVehicleLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, you may specify
          // vehicleId to immediately start
          // tracking.
          vehicleId: 'your-vehicle-id',
});

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineVehicleLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, you may specify
          // vehicleId to immediately start
          // tracking.
          vehicleId: 'your-vehicle-id',
});

إعداد عرض الخريطة

بعد تحميل مكتبة مشاركة رحلة JavaScript، قم بتهيئة عرض الخريطة وإضافته إلى صفحة HTML. يجب أن تحتوي صفحتك على عنصر <div> يحمل عرض الخريطة. تمت تسمية العنصر <div> map_canvas في المثال أدناه.

JavaScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  // Styling customizations; see below.
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // Any undefined styling options will use defaults.
});

// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.vehicleId
                        = 'your-vehicle-id';

// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may
// not fire. The user also has access to the mapView
// object to customize as they wish.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

TypeScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  // Styling customizations; see below.
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // Any undefined styling options will use defaults.
});

// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.vehicleId = 'your-vehicle-id';

// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may
// not fire. The user also has access to the mapView
// object to customize as they wish.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

الاستماع إلى أحداث تغيير الأحداث

يمكنك استرداد معلومات وصفية حول مركبة من الكائن vehicle باستخدام موفّر الموقع الجغرافي. تتضمن المعلومات الوصفية الوقت المقدّر للوصول والمسافة المتبقية قبل موعد استلام المركبة أو تسليمها. تؤدي التغييرات التي تطرأ على المعلومات التعريفية إلى تشغيل حدث تحديث. يوضح المثال التالي كيفية الاستماع إلى أحداث التغيير هذه.

JavaScript

locationProvider.addListener('update', e => {
  // e.vehicle contains data that may be
  // useful to the rest of the UI.
  if (e.vehicle) {
    console.log(e.vehicle.vehicleState);
  }
});

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineVehicleLocationProviderUpdateEvent) => {
  // e.vehicle contains data that may be useful to the rest of the UI.
  if (e.vehicle) {
    console.log(e.vehicle.vehicleState);
  }
});

الاستماع إلى الأخطاء

تؤدي الأخطاء التي تنشأ بشكل غير متزامن عن طلب معلومات المركبة إلى ظهور أحداث خطأ. يوضح المثال التالي كيفية الاستماع إلى هذه الأحداث من أجل معالجة الأخطاء.

JavaScript

locationProvider.addListener('error', e => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

TypeScript

locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

إيقاف التتبُّع

لمنع موفِّر الموقع الجغرافي من تتبُّع المركبة، عليك إزالة رقم تعريفها من موفِّر الموقع الجغرافي.

JavaScript

locationProvider.vehicleId = '';

TypeScript

locationProvider.vehicleId = '';

إزالة مقدم الموقع من عرض الخريطة

يوضح المثال التالي كيفية إزالة مزوِّد خدمة موقع من عرض الخريطة.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

الاطّلاع على مجموعة مركبات

يوضّح هذا القسم كيفية استخدام مكتبة JavaScript "مشاركة الرحلة" لعرض أسطول المركبات. تأكّد من تحميل المكتبة من دالة معاودة الاتصال المحددة في علامة النص البرمجي قبل تشغيل الرمز.

إنشاء مثيل لمزوّد موقع أسطول مركبات

تحدّد مكتبة JavaScript Fleet Tracking Library مسبقًا موفّر الموقع الجغرافي الذي يجلب عدة مركبات من خلال On Demand Rides and Deliveries API. استخدِم رقم تعريف مشروعك بالإضافة إلى مرجع إلى أداة استرجاع الرموز المميّزة لإنشاء مثيل له.

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which vehicles are retrieved.
          vehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which vehicles are retrieved.
          vehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

تحدّد السمة vehicleFilter طلب بحث يتم استخدامه لفلترة المركبات المعروضة على الخريطة. يتم تمرير هذا الفلتر مباشرةً إلى Fleet Engine. راجع ListVehiclesRequest للحصول على التنسيقات المتوافقة.

تفرض ميزة "locationRestriction" قيودًا على المساحة التي يمكن عرض المركبات فيها على الخريطة. كما أنها تتحكم في ما إذا كان تتبع الموقع الجغرافي نشطًا أم لا. لن يبدأ تتبع الموقع حتى يتم تعيين ذلك.

بمجرد إنشاء موفِّر الموقع، قم بتهيئة عرض الخريطة.

تعيين تقييد الموقع باستخدام إطار عرض الخريطة

يمكن إعداد حدود locationRestriction لتتطابق مع المنطقة المرئية في عرض الخريطة.

JavaScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location tracking will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

TypeScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location tracking will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

الاستماع إلى أحداث تغيير الأحداث

يمكنك استرداد معلومات وصفية حول مجموعة الأجهزة من عنصر vehicles باستخدام موفّر الموقع الجغرافي. وتشمل المعلومات الوصفية خصائص المركبة، مثل حالة التنقّل والمسافة إلى نقطة الطريق التالية والسمات المخصّصة. يمكنك الاطّلاع على المستندات المرجعية لمزيد من التفاصيل. يؤدي التغيير في معلومات التعريف إلى تشغيل حدث تحديث. يوضح المثال التالي كيفية الاستماع إلى أحداث التغيير هذه.

JavaScript

locationProvider.addListener('update', e => {
  // e.vehicles contains data that may be
  // useful to the rest of the UI.
  if (e.vehicles) {
    for (vehicle of e.vehicles) {
      console.log(vehicle.navigationStatus);
    }
  }
});

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineFleetLocationProviderUpdateEvent) => {
  // e.vehicles contains data that may be useful to the rest of the UI.
  if (e.vehicles) {
    for (vehicle of e.vehicles) {
      console.log(vehicle.navigationStatus);
    }
  }
});

الاستماع إلى الأخطاء

الأخطاء التي تنشأ بشكل غير متزامن من طلب أحداث الخطأ المتعلقة بمشغل معلومات أسطول المركبات للاطّلاع على أمثلة تعرض كيفية الاستماع إلى هذه الأحداث، راجِع المقالة الاستماع إلى الأخطاء.

إيقاف التتبُّع

لمنع مقدم الموقع من تتبع الأسطول، اضبط حدود مقدم الموقع على قيمة فارغة.

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

إزالة مقدم الموقع من عرض الخريطة

يوضح المثال التالي كيفية إزالة مزوِّد خدمة موقع من عرض الخريطة.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

تخصيص شكل ومظهر الخريطة الأساسية

لتخصيص مظهر عنصر الخرائط ومظهره، يمكنك تصميم الخريطة باستخدام أدوات مستندة إلى السحابة أو من خلال تعيين الخيارات مباشرةً في الرمز.

استخدام تصميم الخرائط المستند إلى السحابة الإلكترونية

يتيح لك تصميم الخرائط المستند إلى السحابة الإلكترونية إنشاء أنماط الخرائط وتعديلها لأيّ من تطبيقاتك التي تستخدم "خرائط Google" من وحدة التحكّم في Google Cloud بدون الحاجة إلى إجراء أي تغييرات على الرموز البرمجية. يتم حفظ أنماط الخريطة كمعرّفات خرائط في مشروعك على السحابة الإلكترونية. لتطبيق نمط على خريطة تتبُّع مجموعة JavaScript، حدِّد mapId عند إنشاء JourneySharingMapView. لا يمكن تغيير الحقل mapId أو إضافته بعد إنشاء مثيل JourneySharingMapView. يوضح المثال التالي كيفية تفعيل نمط خريطة تم إنشاؤه مسبقًا باستخدام معرّف خريطة.

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
});

استخدام تصميم الخريطة المستند إلى الرمز

هناك طريقة أخرى لتخصيص نمط الخريطة، وهي ضبط mapOptions عند إنشاء JourneySharingMapView.

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

استخدام عمليات تخصيص العلامات

باستخدام مكتبة تتبع مجموعة JavaScript، يمكنك تخصيص شكل ومظهر العلامات التي تمت إضافتها إلى الخريطة. يمكنك إجراء ذلك عن طريق تحديد تخصيصات العلامات، التي تطبقها مكتبة تتبع الأسطول بعد ذلك قبل إضافة علامات إلى الخريطة ومع كل تحديث للعلامة.

يمكنك إنشاء عملية تخصيص بسيطة من خلال تحديد عنصر MarkerOptions لتطبيقه على جميع العلامات من النوع نفسه. يتم تطبيق التغييرات المحددة في الكائن بعد إنشاء كل علامة، مما يؤدي إلى استبدال أي خيارات افتراضية.

كخيار أكثر تقدمًا، يمكنك تحديد دالة تخصيص. تتيح دوال التخصيص تصميم العلامات استنادًا إلى البيانات، فضلاً عن إضافة التفاعل إلى العلامات، مثل معالجة النقر. على وجه التحديد، يعمل تتبع الأسطول على تمرير البيانات إلى وظيفة التخصيص المتعلقة بنوع الكائن الذي تمثله العلامة: مركبة أو محطة توقف أو مهمة. يتيح ذلك بعد ذلك تغيير نمط العلامة بناءً على الحالة الحالية لعنصر العلامة نفسه، على سبيل المثال، عدد محطات التوقف أو نوع المهمة المتبقية. يمكنك حتى الانضمام إلى البيانات من مصادر خارج Fleet Engine وتصميم العلامة بناءً على تلك المعلومات.

بالإضافة إلى ذلك، يمكنك استخدام وظائف التخصيص لتصفية مستوى رؤية العلامة. للقيام بذلك، يجب استدعاء setVisible(false) على محدّد الموقع.

وفي المقابل، لأسباب تتعلّق بالأداء، ننصحك بالفلترة باستخدام الفلترة الأصلية في مزوِّد خدمة الموقع الجغرافي، مثل FleetEngineFleetLocationProvider.vehicleFilter. ومع ذلك، عندما تحتاج إلى وظيفة تصفية إضافية، يمكنك تطبيق التصفية باستخدام دالة التخصيص.

توفّر مكتبة "تتبُّع مجموعة الأجهزة" مَعلمات التخصيص التالية:

تغيير تصميم العلامات باستخدام `MarkerOptions`

يعرض المثال التالي كيفية ضبط تصميم علامة مركبة باستخدام عنصر MarkerOptions. اتبع هذا النمط لتخصيص تصميم أي علامة باستخدام أي من معلمات تخصيص العلامة المدرجة أعلاه.

JavaScript

vehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

vehicleMarkerCustomization = {
  cursor: 'grab'
};

تغيير تصميم العلامات باستخدام وظائف التخصيص

يعرض المثال التالي كيفية ضبط تصميم علامة المركبة. اتبع هذا النمط لتخصيص تصميم أي علامة باستخدام أي من معلمات تخصيص العلامة المدرجة أعلاه.

JavaScript

vehicleMarkerCustomization =
  (params) => {
    var remainingWaypoints = params.vehicle.waypoints.length;
    params.marker.setLabel(`${remainingWaypoints}`);
  };

TypeScript

vehicleMarkerCustomization =
  (params: VehicleMarkerCustomizationFunctionParams) => {
    var remainingWaypoints = params.vehicle.waypoints.length;
    params.marker.setLabel(`${remainingWaypoints}`);
  };

إضافة معالجة النقر إلى العلامات

يوضّح المثال التالي كيفية إضافة معالجة النقر إلى علامة مركبة. اتّبع هذا النمط لإضافة معالجة النقرات إلى أي علامة باستخدام أيٍّ من معلمات تخصيص العلامة الواردة أعلاه.

JavaScript

vehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

TypeScript

vehicleMarkerCustomization =
  (params: VehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

فلترة العلامات المرئية

يعرض المثال التالي كيفية فلترة علامات المركبات الظاهرة. اتبع هذا النمط لتصفية أي علامات باستخدام أي من معلمات تخصيص العلامة المذكورة أعلاه.

JavaScript

vehicleMarkerCustomization =
  (params) => {
    var remainingWaypoints = params.vehicle.remainingWaypoints.length;
      if (remainingWaypoints > 10) {
        params.marker.setVisible(false);
      }
  };

TypeScript

vehicleMarkerCustomization =
  (params: VehicleMarkerCustomizationFunctionParams) => {
    var remainingWaypoints = params.vehicle.remainingWaypoints.length;
    if (remainingWaypoints > 10) {
      params.marker.setVisible(false);
    }
  };

استخدام عمليات تخصيص الخطوط المتعددة عند متابعة مركبة

باستخدام مكتبة تتبع الأسطول، يمكنك أيضًا تخصيص مظهر ومظهر مسار المركبة الذي تتبعه على الخريطة. تنشئ المكتبة عنصر google.maps.Polyline لكل زوج من الإحداثيات في مسار المسار النشط أو المتبقي للمركبة. يمكنك تصميم عناصر Polyline من خلال تحديد عمليات تخصيص الخطوط المتعددة. تطبق المكتبة بعد ذلك هذه التخصيصات في حالتين: قبل إضافة الكائنات إلى الخريطة، وعندما تتغير البيانات المستخدمة للكائنات.

على غرار تخصيص العلامة، يمكنك تحديد مجموعة من PolylineOptions ليتم تطبيقها على جميع كائنات Polyline المطابقة عند إنشائها أو تعديلها.

وبالمثل، يمكنك تحديد دالة تخصيص. تتيح دوال التخصيص التصميم الفردي للكائنات بناءً على البيانات المرسلة بواسطة Fleet Engine. ويمكن أن تؤدي هذه الوظيفة إلى تغيير تصميم كل عنصر استنادًا إلى الحالة الحالية للمركبة، على سبيل المثال، تلوين العنصر Polyline بدرجة أعمق أو زيادة سماكته عندما تكون المركبة أبطأ. يمكنك أيضًا الانضمام من مصادر خارج Fleet Engine وتصميم عنصر Polyline بناءً على هذه المعلومات.

يمكنك تحديد عمليات التخصيص باستخدام المَعلمات المقدَّمة في FleetEngineVehicleLocationProviderOptions. ويمكنك ضبط عمليات تخصيص لحالات المسار المختلفة في رحلة المركبة، سواء أثناء السفر أو السفر النشط أو الذي لم تسافر بعد. وتكون المعلمات على النحو التالي:

takenPolylineCustomization، بالنسبة إلى مسار تم قطعه بالفعل؛
activePolylineCustomization، بالنسبة إلى مسار السفر النشط
remainingPolylineCustomization، لمسار لم يتم قطعه بعد.

تغيير تصميم عناصر `Polyline` باستخدام `PolylineOptions`

يوضّح المثال التالي كيفية ضبط تصميم عنصر Polyline باستخدام السمة PolylineOptions. اتّبِع هذا النمط لتخصيص تصميم أي عنصر Polyline باستخدام أي من عمليات تخصيص الخطوط المتعددة المذكورة سابقًا.

JavaScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

TypeScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

تغيير تصميم عناصر `Polyline` باستخدام وظائف التخصيص

يعرض المثال التالي كيفية ضبط نمط عنصر Polyline نشط. اتّبِع هذا النمط لتخصيص تصميم أي عنصر Polyline باستخدام أي من مَعلمات تخصيص الخطوط المتعددة المذكورة سابقًا.

JavaScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params) => {
    const distance = params.vehicle.waypoints[0].distanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

TypeScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params: VehiclePolylineCustomizationFunctionParams) => {
    const distance = params.vehicle.waypoints[0].distanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

التحكّم في إذن الوصول إلى عناصر `Polyline`

بشكل تلقائي، تكون جميع عناصر Polyline مرئية. لجعل عنصر Polyline غير مرئي، اضبط خاصية visible الخاصة به:

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

عرض عناصر `Polyline` المخصصة لرصد الزيارات

يعرض Fleet Engine بيانات سرعة حركة المرور للمسارات النشطة والمتبقية للمركبة التي يتم تتبّعها. يمكنك استخدام هذه المعلومات لتصميم عناصر Polyline وفقًا لسرعات الزيارات:

JavaScript

// Color the Polyline objects according to their real-time traffic levels
// using '#05f' for normal, '#fa0' for slow, and '#f33' for traffic jam.
activePolylineCustomization =
  FleetEngineVehicleLocationProvider.
      TRAFFIC_AWARE_ACTIVE_POLYLINE_CUSTOMIZATION_FUNCTION;

// Or alter the objects further after the customization function has been
// run -- in this example, change the blue for normal to green:
activePolylineCustomization =
  (params) => {
    FleetEngineVehicleLocationProvider.
        TRAFFIC_AWARE_ACTIVE_POLYLINE_CUSTOMIZATION_FUNCTION(params);
    for (const polylineObject of params.polylines) {
      if (polylineObject.get('strokeColor') === '#05f') {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

TypeScript

// Color the Polyline objects according to their real-time traffic levels
// using '#05f' for normal, '#fa0' for slow, and '#f33' for traffic jam.
activePolylineCustomization =
  FleetEngineVehicleLocationProvider.
      TRAFFIC_AWARE_ACTIVE_POLYLINE_CUSTOMIZATION_FUNCTION;

// Or alter the objects further after the customization function has been
// run -- in this example, change the blue for normal to green:
activePolylineCustomization =
  (params: VehiclePolylineCustomizationFunctionParams) => {
    FleetEngineVehicleLocationProvider.
        TRAFFIC_AWARE_ACTIVE_POLYLINE_CUSTOMIZATION_FUNCTION(params);
    for (const polylineObject of params.polylines) {
      if (polylineObject.get('strokeColor') === '#05f') {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

عرض `InfoWindow` لمركبة أو علامة موقع جغرافي

يمكنك استخدام InfoWindow لعرض معلومات إضافية عن مركبة أو علامة موقع جغرافي.

يوضّح المثال التالي كيفية إنشاء InfoWindow وإرفاقه بعلامة المركبة.

JavaScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

// (Assumes a vehicle location provider.)
locationProvider.addListener('update', e => {
  if (e.vehicle) {
    const distance =
          e.vehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next drop-off point.`);

    // 2. Attach the info window to a vehicle marker.
    // This property can return multiple markers.
    const marker = mapView.vehicleMarkers[0];
    infoWindow.open(mapView.map, marker);
  }
});

// 3. Close the info window.
infoWindow.close();

TypeScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

// (Assumes a vehicle location provider.)
locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineVehicleLocationProviderUpdateEvent) => {
  if (e.vehicle) {
    const distance =
          e.vehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next drop-off.`);
    // 2. Attach the info window to a vehicle marker.
    // This property can return multiple markers.
    const marker = mapView.vehicleMarkers[0];
    infoWindow.open(mapView.map, marker);
  }
});

// 3. Close the info window.
infoWindow.close();

إيقاف الاحتواء التلقائي

يمكنك إيقاف ملاءمة إطار العرض تلقائيًا للمركبة والمسار المتوقَّع للخريطة من خلال إيقاف ميزة "الضبط التلقائي". يوضح المثال التالي كيفية إيقاف الضبط التلقائي عند ضبط عرض الخريطة لمشاركة الرحلة.

JavaScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  automaticViewportMode:
      google.maps.journeySharing
          .AutomaticViewportMode.NONE,
  ...
});

TypeScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  automaticViewportMode:
      google.maps.journeySharing
          .AutomaticViewportMode.NONE,
  ...
});

استبدال خريطة حالية

يمكنك استبدال خريطة موجودة تتضمن علامات أو تخصيصات أخرى دون فقدان تلك التخصيصات.

على سبيل المثال، لنفترض أنّ لديك صفحة ويب بها كيان google.maps.Map عادي تظهر عليه علامة:

<!DOCTYPE html>
<html>
  <head>
    <style>
      /* Set the size of the div element that contains the map */
      #map {
        height: 400px; /* The height is 400 pixels */
        width: 100%; /* The width is the width of the web page */
      }
    </style>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <div id="map"></div>
    <script>
      // Initialize and add the map
      function initMap() {
        // The location of Oracle Park Stadium
        var oraclePark = { lat: 37.780087547237365, lng: -122.38948437884427 };,
        // The map, initially centered at Mountain View, CA.
        var map = new google.maps.Map(document.getElementById("map"));
        map.setOptions({ center: { lat: 37.424069, lng: -122.0916944 }, zoom: 14 });

        // The marker, now positioned at Oracle Park
        var marker = new google.maps.Marker({ position: oraclePark, map: map });
      }
    </script>
    <!-- Load the API from the specified URL.
      * The async attribute allows the browser to render the page while the API loads.
      * The key parameter will contain your own API key (which is not needed for this tutorial).
      * The callback parameter executes the initMap() function.
    -->
    <script
      defer
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    ></script>
  </body>
</html>

لإضافة مكتبة "مشاركة رحلة JavaScript" التي تتضمّن "تتبُّع الأسطول":

أضِف رمزًا إلى المصنع.
إعداد موفِّر الموقع الجغرافي في دالة initMap().
تهيئة عرض الخريطة في دالة initMap(). تحتوي طريقة العرض على الخريطة.
انقل التخصيص إلى دالة رد الاتصال لإعداد عرض الخريطة.
أضف مكتبة المواقع إلى برنامج تحميل واجهة برمجة التطبيقات.

يوضح المثال التالي التغييرات التي سيتم إجراؤها:

<!DOCTYPE html>
<html>
  <head>
    <style>
      /* Set the size of the div element that contains the map */
      #map {
        height: 400px; /* The height is 400 pixels */
        width: 100%; /* The width is the width of the web page */
      }
    </style>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <div id="map"></div>
    <script>
      let locationProvider;

      // (1) Authentication Token Fetcher
      function authTokenFetcher(options) {
        // options is a record containing two keys called
        // serviceType and context. The developer should
        // generate the correct SERVER_TOKEN_URL and request
        // based on the values of these fields.
        const response = await fetch(SERVER_TOKEN_URL);
            if (!response.ok) {
              throw new Error(response.statusText);
            }
            const data = await response.json();
            return {
              token: data.Token,
              expiresInSeconds: data.ExpiresInSeconds
            };
      }

      // Initialize and add the map
      function initMap() {
        // (2) Initialize location provider. Use FleetEngineVehicleLocationProvider
        // as appropriate.
        locationProvider = new google.maps.journeySharing.FleetEngineVehicleLocationProvider({
          YOUR_PROVIDER_ID,
          authTokenFetcher,
        });

        // (3) Initialize map view (which contains the map).
        const mapView = new google.maps.journeySharing.JourneySharingMapView({
          element: document.getElementById('map'),
          locationProviders: [locationProvider],
          // any styling options
        });

      mapView.addListener('ready', () => {
        locationProvider.vehicleId = VEHICLE_ID;

          // (4) Add customizations like before.

          // The location of Oracle Park
          var oraclePark = {lat: 37.77995187146094, lng: -122.38957020952795};
          // The map, initially centered at Mountain View, CA.
          var map = mapView.map;
          map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});
          // The marker, now positioned at Oracle Park
          var marker = new google.maps.Marker({position: oraclePark, map: map});
        };
      }
    </script>
    <!-- Load the API from the specified URL
      * The async attribute allows the browser to render the page while the API loads
      * The key parameter will contain your own API key (which is not needed for this tutorial)
      * The callback parameter executes the initMap() function
      *
      * (5) Add the journey sharing library to the API loader, which includes Fleet Tracking functionality.
    -->
    <script
      defer
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing&v=beta"
    ></script>
  </body>
</html>

إذا كنت تقود مركبة برقم التعريف المحدد بالقرب من Oracle Park، سيتم عرضها على الخريطة.

تتبُّع أسطولك باستخدام مكتبة JavaScript FleetTracking

المكوّنات

عرض الخريطة الخاصة بتتبع الأسطول

مقدمو خدمة المواقع الجغرافية

مقدِّم خدمة الموقع الجغرافي للمركبة

مقدِّم خدمة الموقع الجغرافي لمجموعة الأجهزة

التحكم في مستوى رؤية المواقع التي يتم تتبعها

مركبات

علامات المواقع الجغرافية لنقاط الطريق

بدء استخدام مكتبة JavaScript Fleet Tracking Library (مكتبة تتبُّع مجموعة JavaScript)

إنشاء مطالبة بمعرّف الرحلة ومعرّف المركبة

إنشاء أداة استرجاع الرمز المميّز للمصادقة

JavaScript

TypeScript

تحميل خريطة من HTML

متابعة مركبة

إنشاء مثيل لمقدِّم الموقع الجغرافي للمركبة

JavaScript

TypeScript

إعداد عرض الخريطة

JavaScript

TypeScript

الاستماع إلى أحداث تغيير الأحداث

JavaScript

TypeScript

الاستماع إلى الأخطاء

JavaScript

TypeScript

إيقاف التتبُّع

JavaScript

TypeScript

إزالة مقدم الموقع من عرض الخريطة

JavaScript

TypeScript

الاطّلاع على مجموعة مركبات

إنشاء مثيل لمزوّد موقع أسطول مركبات

JavaScript

TypeScript

تعيين تقييد الموقع باستخدام إطار عرض الخريطة

JavaScript

TypeScript

الاستماع إلى أحداث تغيير الأحداث

JavaScript

TypeScript

الاستماع إلى الأخطاء

إيقاف التتبُّع

JavaScript

TypeScript

إزالة مقدم الموقع من عرض الخريطة

JavaScript

TypeScript

تخصيص شكل ومظهر الخريطة الأساسية

استخدام تصميم الخرائط المستند إلى السحابة الإلكترونية

JavaScript

TypeScript

استخدام تصميم الخريطة المستند إلى الرمز

JavaScript

TypeScript

استخدام عمليات تخصيص العلامات

تغيير تصميم العلامات باستخدام MarkerOptions

JavaScript

TypeScript

تغيير تصميم العلامات باستخدام وظائف التخصيص

JavaScript

TypeScript

إضافة معالجة النقر إلى العلامات

JavaScript

TypeScript

فلترة العلامات المرئية

JavaScript

TypeScript

استخدام عمليات تخصيص الخطوط المتعددة عند متابعة مركبة

تغيير تصميم عناصر Polyline باستخدام PolylineOptions

JavaScript

TypeScript

تغيير تصميم عناصر Polyline باستخدام وظائف التخصيص

JavaScript

TypeScript

التحكّم في إذن الوصول إلى عناصر Polyline

JavaScript

تغيير تصميم العلامات باستخدام `MarkerOptions`

تغيير تصميم عناصر `Polyline` باستخدام `PolylineOptions`

تغيير تصميم عناصر `Polyline` باستخدام وظائف التخصيص

التحكّم في إذن الوصول إلى عناصر `Polyline`

عرض عناصر `Polyline` المخصصة لرصد الزيارات

عرض `InfoWindow` لمركبة أو علامة موقع جغرافي