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

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

تتبّع الشحنات باستخدام مكتبة تتبّع شحن JavaScript

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

المكوّنات

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

عرض الخريطة لتتبُّع الشحن

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

مقدّم الموقع الجغرافي للشحن

يقوم مزود موقع الشحن بتزويد معلومات الموقع للعناصر التي يتم تتبعها في خريطة تتبع الشحنة لتتبع شحنة الميل الأول والأخير.

يمكنك الاستعانة بمقدِّم الموقع الجغرافي للشحن لتتبُّع ما يلي:

الموقع الجغرافي لاستلام الشحنة أو تسليمها.
تمثّل هذه السمة الموقع الجغرافي لمركبة التسليم ومسارها.

عناصر المواقع الجغرافية التي تم تتبُّعها

يتتبع موفر المواقع موقع الأشياء مثل المركبات والوجهات.

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

موقع الوجهة هو الموقع الذي تنتهي فيه الرحلة. بالنسبة لتتبع الشحن، هو موقع المهمة المخطط له.

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

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

استرجاع الرمز المميّز للمصادقة

للتحكّم في الوصول إلى بيانات الموقع الجغرافي المخزَّنة في Fleet Engine، يجب تنفيذ خدمة إزالة الرمز المميّز JSON للويب (JWT) من أجل Fleet Engine على خادمك. بعد ذلك، نفِّذ أداة جلب رموز المصادقة المميّزة كجزء من تطبيق الويب، باستخدام مكتبة مشاركة رحلة JavaScript لمصادقة الوصول إلى بيانات الموقع الجغرافي.

خيارات التصميم

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

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

يصف هذا القسم عناصر التحكم في مستوى الرؤية للعناصر التي يتم تتبعها على الخريطة. تنطبق هذه القواعد على فئتَين من العناصر:

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

إذن الوصول إلى علامة الموقع الجغرافي

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

إذن الوصول إلى بيانات المهمّة

يصف هذا القسم القواعد التلقائية لمستوى الرؤية التي تنطبق على بيانات المهمة، مثل الموقع الجغرافي للمركبة والمسار المتبقي. يمكنك تخصيص العديد من المهام ولكن ليس كلها:

مهام عدم التوفّر: لا يمكنك تخصيص مستوى الرؤية لهذه المهام.
مهام المركبة النشطة -- يمكنك تخصيص هذا النوع من المهام.
مهام المركبة غير النشطة: لا يمكنك تخصيص إذن الوصول لهذه المهام.

مهام عدم التوفّر

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

المهام النشطة الخاصة بالمركبات

يوفّر عنصر TaskTrackingInfo عددًا من عناصر البيانات التي يمكن إظهارها في مكتبة تتبّع الشحن. تظهر هذه الحقول تلقائيًا عند تعيين المهمة للمركبة وعندما تكون المركبة ضمن 5 محطات للمهمة. تنتهي إمكانية الظهور عند اكتمال المهمة أو إلغاؤها. تكون الحقول على النحو التالي:

الخطوط المتعددة في المسار
الوقت المقدَّر للوصول
الوقت المقدَّر لإكمال المهمة
المسافة المتبقية بالسيارة للوصول إلى المهمة
عدد المحطات المتبقية
الموقع الجغرافي للمركبة

يمكنك تخصيص إعدادات إذن الوصول لكل مهمة من خلال ضبط TaskTrackingViewConfig على مهمة عند إنشاء المهمة أو تعديلها في Fleet Engine. ينشئ هذا قواعد لوقت توفر عناصر البيانات الفردية والتي يمكن أن تستند إلى المعايير التالية (يشار إليها باسم خيار مستوى الرؤية أدناه):

عدد المحطات المتبقية
المدة حتى وقت الوصول المقدّر
المسافة المقطوعة أثناء القيادة
مرئية دائمًا
غير مرئية مطلقًا

تجدر الإشارة إلى أنّه يمكن ربط كل عنصر بيانات بخيار واحد فقط لمستوى الرؤية. لا يمكن دمج المعايير باستخدام OR أو AND.

وفي ما يلي مثال على التخصيص. قواعد هذا التخصيص هي:

اعرض الخطوط المتعددة للمسار إذا كانت المركبة في نطاق 3 محطات.
اعرض الوقت المقدّر للوصول إذا كانت مسافة القيادة المتبقية أقصر من 5000 متر.
عدم عرض عدد المحطات المتبقية مطلقًا
يحتفظ كل حقل آخر بمستوى الرؤية التلقائي للظهور عندما تكون المركبة ضمن 5 محطات للمهمة.

"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

يمكنك أيضًا تخصيص الإعدادات التلقائية لمستوى الرؤية لمشروعك من خلال التواصل مع فريق الدعم.

الخطوط المتعددة للمسار وقواعد رؤية الموقع الجغرافي للمركبة:

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

يجب اتّباع هذه القواعد لتوفير مجموعة صالحة من الخطوط المتعددة للمسار / الموقع الجغرافي للمركبة:

عندما يكون للخطوط المتعددة للمسار والموقع الجغرافي للمركبة نفس خيار مستوى الرؤية:
- إذا كان خيار مستوى الرؤية هو إبقاء عدد محطات التوقف أو المدة حتى الوصول المقدر للوصول أو المسافة المتبقية بالسيارة، يجب أن توفر الخطوط المتعددة للمسار قيمة أقل من أو تساوي القيمة المحددة لخيار مستوى الرؤية هذا للموقع الخاص بالمركبة. في ما يلي مثال على ذلك:
```
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "vehicleLocationVisibility": {
    "remainingStopCountThreshold": 5
  },
}
```
- إذا كانت الخطوط المتعددة للمسار تتضمن خيار ظهور مرئي دائمًا، يجب أن توفّر خدمة الموقع الجغرافي للمركبة أيضًا خيار ظهور مرئي دائمًا.
- إذا كان الموقع الجغرافي للمركبة يتضمّن خيار ظهور لا يظهر أبدًا، يجب أن توفّر الخطوط المتعددة للمسار أيضًا خيار ظهور لا يظهر أبدًا.
عندما يكون للخطوط المتعددة للمسار والموقع الجغرافي للمركبة أنواع خيارات مختلفة لمستوى الرؤية، لن يظهر الموقع الجغرافي للمركبة إلا عند استيفاء كلا خيارَي الرؤية.

في ما يلي مثال على ذلك:
```
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "vehicleLocationVisibility": {
    "remainingDrivingDistanceMetersThreshold": 3000
  },
}
```
في هذا المثال، لا يظهر الموقع الجغرافي للمركبة إلّا إذا كان عدد المحطات المتبقية 3 على الأقل والمسافة المقطوعة للمركبة المتبقية تبلغ 3, 000 متر على الأقل.

بدء استخدام مكتبة مشاركة رحلة JavaScript

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

لتتبُّع عملية تسليم، عليك أولاً إنشاء مطالبة بشأن رقم تعريف التتبُّع.

إنشاء مطالبة بشأن رقم تعريف التتبُّع

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

لإنشاء حمولة JWT، أضِف مطالبة أخرى في قسم التفويض باستخدام المفتاح trackingid. اضبط قيمته على رقم تعريف تتبّع الشحن.

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

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

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

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

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

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

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

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

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

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

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 لمتابعة عملية استلام الشحنة أو تسليمها. تأكّد من تحميل المكتبة من دالة الاستدعاء المحدّدة في علامة النص البرمجي قبل تشغيل الرمز.

إنشاء نسخة من مزوِّد موقع الشحن

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

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

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

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

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

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

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

لتجنّب شروط السباق، اضبط رقم تعريف التتبّع لموفّر الموقع الجغرافي في الردّ الذي تم استدعاؤه بعد إعداد الخريطة.

JavaScript

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

// If you did not specify a tracking ID in the location
// provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.trackingId = 'your-tracking-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({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);

TypeScript

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

// If you did not specify a tracking ID in the location
// provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.trackingId = 'your-tracking-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({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);

الرقم التعريفي للتتبع

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

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

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

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

JavaScript

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

TypeScript

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

التعامل مع الأخطاء

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

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);
});

ملاحظة: يُرجى التأكّد من إحاطة استدعاءات المكتبة في مجموعات try...catch بمعالجة الأخطاء غير المتوقعة.

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

لمنع موفر الموقع من تتبع الشحنة، عليك إزالة معرّف التتبع من موفر الموقع.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

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

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

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'
  }
  // Any other styling options.
});

TypeScript

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

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

هناك طريقة أخرى لتخصيص تصميم الخريطة، وهي ضبط 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 وتصميم العلامة بناءً على تلك المعلومات.

توفّر مكتبة "تتبُّع الشحن" مَعلمات التخصيص التالية في FleetEngineShipmentLocationProviderOptions:

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

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

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

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

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

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    const stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

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

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

JavaScript

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

TypeScript

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

استخدام تخصيصات الخطوط المتعددة

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

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

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

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

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.taskTrackingInfo.remainingDrivingDistanceMeters;
    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: ShipmentPolylineCustomizationFunctionParams) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    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});

locationProvider.addListener('update', e => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 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});

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 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

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

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 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 لاستبدال خريطة حالية تتضمّن علامات أو تخصيصات أخرى بدون فقدان تلك التخصيصات.

على سبيل المثال، لنفترض أنّ لديك صفحة ويب تتضمّن كيان 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":

أضف رمزًا لمصنع الرموز المميزة للمصادقة.
إعداد موفّر موقع جغرافي في الدالة 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.
  locationProvider = new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
    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
  });

  locationProvider.trackingId = TRACKING_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.
    -->
    <script defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
    </script>
  </body>
</html>

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

تتبّع الشحنات باستخدام مكتبة تتبّع شحن JavaScript

المكوّنات

عرض الخريطة لتتبُّع الشحن

مقدّم الموقع الجغرافي للشحن

عناصر المواقع الجغرافية التي تم تتبُّعها

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

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

استرجاع الرمز المميّز للمصادقة

خيارات التصميم

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

إذن الوصول إلى علامة الموقع الجغرافي

إذن الوصول إلى بيانات المهمّة

مهام عدم التوفّر

المهام النشطة الخاصة بالمركبات

الخطوط المتعددة للمسار وقواعد رؤية الموقع الجغرافي للمركبة:

بدء استخدام مكتبة مشاركة رحلة JavaScript

إنشاء مطالبة بشأن رقم تعريف التتبُّع

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

JavaScript

TypeScript

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

متابعة شحنة

إنشاء نسخة من مزوِّد موقع الشحن

JavaScript

TypeScript

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

JavaScript

TypeScript

الرقم التعريفي للتتبع

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

JavaScript

TypeScript

التعامل مع الأخطاء

JavaScript

TypeScript

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

JavaScript

TypeScript

استخدام تخصيصات الخطوط المتعددة

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

JavaScript

TypeScript

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

JavaScript

TypeScript

التحكّم في مستوى رؤية عناصر Polyline

JavaScript

TypeScript

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

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

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

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

التحكّم في مستوى رؤية عناصر `Polyline`

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