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

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

المكونات

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

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

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

موفِّرو المواقع الجغرافية

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

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

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

مقدّم موقع أسطول التسليم

يعرض مقدم خدمة أسطول التسليم العديد من الْمَوْقِعِ الْجُغْرَافِي المعلومات. يمكنك الفلترة للعثور على مركبات أو مواقع جغرافية معيّنة، أو يمكنك عرض الأسطول بأكمله.

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

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

مركبات توصيل الطلبات

تظهر مركبة التوصيل بمجرد إنشائها في Fleet Engine، ويظهر في جميع أنحاء المسار بغض النظر عن المهام.

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

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

يتم عرض موقع نتائج المهمة مع علامات نتائج المهمة. يتم عرض المهام التي لها نتيجة SUCCEEDED مع علامات المهام الناجحة، بينما يتم عرض جميع المهام الأخرى بعلامات مهام غير ناجحة.

بدء استخدام مكتبة JavaScript Fleet Tracking Library

قبل استخدام مكتبة JavaScript Fleet Tracking Library، تأكَّد من على دراية بأداة Fleet Engine ومن خلال الحصول على مفتاح واجهة برمجة التطبيقات. بعد ذلك، أنشِئ معرّف المهمة ومطالبة بمعرّف مركبة التسليم.

إنشاء معرّف المهمة ومطالبة معرّف مركبة التسليم

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

لإنشاء حمولة JWT، أضِف مطالبة أخرى في قسم التفويض. باستخدام المفتاحين taskid وdeliveryvehicleid وتعيين قيمة من كل مفتاح إلى *. يجب إنشاء الرمز المميّز باستخدام Fleet Engine. دور مستخدم متميز في الخدمة Cloud IAM. تجدر الإشارة إلى أنّ هذا الإجراء يمنح إمكانية الوصول الواسع النطاق إنشاء كيانات Fleet Engine وقراءتها وتعديلها، ويجب مشاركتها فقط مع مستخدمين موثوق بهم.

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

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "scope": "https://www.googleapis.com/auth/xapi",
  "authorization": {
     "taskid": "*",
     "deliveryvehicleid": "*",
   }
}

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

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

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

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

تطلب مكتبة JavaScript Fleet Tracking Library رمزًا مميزًا من خلال المصادقة لجلب الرموز المميزة عندما يكون أي مما يلي صحيحًا:

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

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

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

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/delivery_driver/DELIVERY_VEHICLE_ID
  • https://SERVER_URL/token/delivery_consumer/TRACKING_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" defer></script>

متابعة مركبة توصيل

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

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

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

JavaScript

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

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

TypeScript

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

          // Optionally, you may specify
          // deliveryVehicleId to immediately start
          // tracking.
          deliveryVehicleId: 'your-delivery-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 delivery vehicle ID in the 
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.deliveryVehicleId 
                        = 'your-delivery-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.
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // Any undefined styling options will use defaults.
});

// If you did not specify a delivery vehicle ID in the 
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.deliveryVehicleId 
                        = 'your-delivery-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);

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

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

JavaScript

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

TypeScript

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

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

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

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.deliveryVehicleId = '';

TypeScript

locationProvider.deliveryVehicleId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

عرض مجموعة مركبات توصيل

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

إنشاء مثيل لموقع أسطول التسليم

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

JavaScript

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

          // Optionally, specify location bounds to
          // limit which delivery 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 delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

TypeScript

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

          // Optionally, specify location bounds to
          // limit which delivery 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 delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

تحدّد السمة deliveryVehicleFilter طلب بحث يُستخدَم لفلترة المركبات المعروضة على الخريطة. يتم تمرير هذا الفلتر مباشرةً إلى Fleet Engine. عرض ListDeliveryVehiclesRequest.filter للاطّلاع على التنسيقات المتوافقة

تحدّد ميزة 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;
    }
  });

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

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

JavaScript

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

TypeScript

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

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

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

إيقاف التتبع

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

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

تتبَّع مركبة توصيل أثناء عرض أسطول التسليم

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

JavaScript

deliveryFleetLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery 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 delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

deliveryVehicleLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher
        });

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [
    deliveryFleetLocationProvider,
    deliveryVehicleLocationProvider,
  ],
  // Any other options
});

TypeScript

deliveryFleetLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery 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 delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

deliveryVehicleLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher
        });

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [
    deliveryFleetLocationProvider,
    deliveryVehicleLocationProvider,
  ],
  // Any other options
});

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

JavaScript

// Specify the customization function either separately, or as a field in
// the options for the delivery fleet location provider constructor.
deliveryFleetLocationProvider.deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // params.vehicle.name follows the format
        // "providers/{provider}/deliveryVehicles/{vehicleId}".
        // Only the vehicleId portion is used for the delivery vehicle
        // location provider.
        deliveryVehicleLocationProvider.deliveryVehicleId =
            params.vehicle.name.split('/').pop();
      });
    }
  };

TypeScript

// Specify the customization function either separately, or as a field in
// the options for the delivery fleet location provider constructor.
deliveryFleetLocationProvider.deliveryVehicleMarkerCustomization =
  (params: google.maps.journeySharing.DeliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // params.vehicle.name follows the format
        // "providers/{provider}/deliveryVehicles/{vehicleId}".
        // Only the vehicleId portion is used for the delivery vehicle
        // location provider.
        deliveryVehicleLocationProvider.deliveryVehicleId =
            params.vehicle.name.split('/').pop();
      });
    }
  };

إخفاء العلامة من مقدِّم الموقع الجغرافي لمركبة التسليم لمنع العرض علامتان للمركبة نفسها:

JavaScript

// Specify the customization function either separately, or as a field in 
// the options for the delivery vehicle location provider constructor.
deliveryVehicleLocationProvider.deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.setVisible(false);
    }
  };

TypeScript

// Specify the customization function either separately, or as a field in
// the options for the delivery vehicle location provider constructor.
deliveryVehicleLocationProvider.deliveryVehicleMarkerCustomization =
  (params: deliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.setVisible(false);
    }
  };

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

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

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

تصميم الخرائط المستندة إلى السحابة الإلكترونية يسمح لك بإنشاء أنماط الخريطة وتعديلها لأي من تطبيقاتك التي تستخدم خرائط Google من Google Cloud Console بدون الحاجة إلى إجراء أي تغييرات على الرمز. يتم حفظ أنماط الخريطة كمعرّفات خرائط في مشروعك على السحابة الإلكترونية. إلى تطبيق نمط على خريطة تتبع مجموعة 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 Fleet Tracking Library، يمكنك تخصيص الشكل والمظهر من العلامات التي تمت إضافتها إلى الخريطة. يمكنك فعل ذلك عن طريق تحديد تخصيصات العلامة، الذي تطبقه مكتبة تتبع الأسطول قبل إضافة علامات إلى الخريطة ومع كل تحديث محدد للموقع.

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

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

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

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

توفِّر مكتبة "تتبُّع الأسطول" مَعلمات التخصيص التالية:

• FleetEngineDeliveryVehicleLocationProviderOptions
  • deliveryVehicleMarkerCustomization
  • plannedStopMarkerCustomization
  • taskMarkerCustomization
  • taskOutcomeMarkerCustomization
• FleetEngineDeliveryFleetLocationProviderOptions
  • deliveryVehicleMarkerCustomization

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

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

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

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

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

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    params.marker.setLabel(`${stopsLeft}`);
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    params.marker.setLabel(`${stopsLeft}`);
  };

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

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

JavaScript

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

TypeScript

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

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

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

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    if (stopsLeft > 10) {
      params.marker.setVisible(false);
    }
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    if (stopsLeft > 10) {
      params.marker.setVisible(false);
    }
  };

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

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

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

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

ويمكنك تحديد عمليات التخصيص باستخدام المَعلمات الواردة في FleetEngineDeliveryVehicleLocationProviderOptions يمكنك ضبط إعدادات مخصّصة لحالات المسارات المختلفة في المركبة. السفر - سواء سافرت بالفعل أو سافرت بشكل نشط أو لم يسافر عليها بعد. تشير رسالة الأشكال البيانية المعلمات هي كما يلي:

• takenPolylineCustomization، لمسار سبق الانتقال إليه
• activePolylineCustomization، لمسار متنقّل بشكل نشط
• remainingPolylineCustomization، لمسار لم يتم التنقل فيه بعد.

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

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

JavaScript

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

TypeScript

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

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

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

JavaScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params) => {
    const distance = params.deliveryVehicle.remainingDistanceMeters;
    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: DeliveryVehiclePolylineCustomizationFunctionParams) => {
    const distance = params.deliveryVehicle.remainingDistanceMeters;
    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};

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

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

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

JavaScript

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

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

    // 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 delivery vehicle location provider.)
locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProviderUpdateEvent) => {
  if (e.deliveryVehicle) {
    const distance = 
           e.deliveryVehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next task.`);

    // 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 Uluru
  var uluru = {lat: -25.344, lng: 131.036};
  // 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 Uluru
  var marker = new google.maps.Marker({position: uluru, 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 Journey Share، والتي تتضمّن ميزة "تتبُّع الأسطول":

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

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

<!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 FleetEngineDeliveryVehicleLocationProvider
  // as appropriate.
  locationProvider = new google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProvider({
    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.deliveryVehicleId = DELIVERY_VEHICLE_ID;

    // (4) Add customizations like before.

    // The location of Uluru
    var uluru = {lat: -25.344, lng: 131.036};
    // 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 Uluru
    var marker = new google.maps.Marker({position: uluru, 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">
    </script>
  </body>
</html>

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