يتوفّر 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، تأكَّد من أنّك على عِلم بـ 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 Shipment Tracking Library (مكتبة تتبُّع الشحنات في JavaScript) مسبقًا موفّر الموقع الجغرافي لواجهة برمجة تطبيقات Fleet Engine Deliveries. استخدِم رقم تعريف مشروعك ومرجعًا لمصنع الرموز المميّزة لإنشاء مثيل له.

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

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

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

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

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

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

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

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

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

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، بدون الحاجة إلى إجراء أي تغييرات على الرموز البرمجية. يتم حفظ أنماط الخرائط كمعرّفات خرائط في مشروعك على 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` لمركبة أو علامة موقع جغرافي