تمت ترجمة هذه الصفحة بواسطة 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
  }
}

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

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

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

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

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

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

بدء استخدام مكتبة مشاركة رحلة 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 مسبقًا موفِّر الموقع الجغرافي. في 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> باسم <div>.

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

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 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'
  }
  // 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` لمركبة أو علامة موقع جغرافي