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

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

بدء استخدام حزمة تطوير البرامج (SDK) للمستهلك بشأن JavaScript

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

المكوّنات

توفر حزمة تطوير البرامج (SDK) لJavaScript مكونات لعرض بيانات المركبات ونقاط الطرق، بالإضافة إلى خلاصات البيانات الأولية حول الوقت المقدّر للوصول للسائق أو المسافة المتبقية للقيادة.

عرض خريطة مستوى التقدُّم في الرحلة والطلبات

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

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

تتضمّن حزمة JavaScript SDK موفّر خدمة للموقع الجغرافي للرحلة، ويزوِّد معلومات الموقع الجغرافي للعناصر التي يتم تتبُّعها في خريطة مستوى التقدّم في الرحلة والطلبات.

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

موقع استلام الرحلة أو تسليمها
الموقع الجغرافي ومسار المركبة المخصّصة للرحلة.

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

يتتبّع موفر الموقع موقع عناصر مثل نقاط الطرق والمركبات.

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

الموقع الجغرافي لنقطة الانطلاق هو الموقع الجغرافي الذي تبدأ منه الرحلة. إنه يحدد موقع الاستلام.

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

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

الموقع الجغرافي الخاص بالنقطة الوسيطة

موقع النقطة الوسيطة هو أي موقع على طول مسار الرحلة التي يتم تتبعها. فعلى سبيل المثال، كل محطة على مسار الحافلات هي موقع نقطة وسيطة.

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

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

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

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

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

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

التحكم في إمكانية رؤية المواقع التي يتم تتبّعها

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

مركبات

تكون مركبة مشاركة الرحلات مرئية من الوقت المخصص لها في الرحلة إلى وقت النزول. إذا تم إلغاء الرحلة، تصبح المركبة مرئية.

جميع علامات الموقع الأخرى

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

بدء استخدام حزمة تطوير البرامج (SDK) لJavaScript

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

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

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

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

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

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

{
  "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": {
     "tripid": "tid_12345",
   }
}

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

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

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

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

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

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

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

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

JavaScript

async 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.jwt,
    expiresInSeconds: data.expirationTimestamp - Date.now(),
  };
}

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

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

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

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

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

بعد رحلة

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

إنشاء مثيل لمزوّد موقع الرحلة

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

JavaScript

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

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

TypeScript

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

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

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

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

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

JavaScript

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

// If you did not specify a trip ID in the location
// provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.tripId = 'your-trip-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({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  // Styling customizations; see below.
  vehicleMarkerCustomization: vehicleMarkerCustomization,
  activePolylineCustomization: activePolylineCustomization,
  // Any undefined styling options will use defaults.
});

// If you did not specify a trip ID in the location
// provider constructor, you may do so here.
locationProvider.tripId = 'your-trip-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.trip contains data that may be useful
  // to the rest of the UI.  
  console.log(e.trip.dropOffTime);
});

TypeScript

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

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

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

JavaScript

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

TypeScript

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

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

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

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

JavaScript

locationProvider.tripId = '';

TypeScript

locationProvider.tripId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

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

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

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

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

JavaScript

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

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
  // and 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، يمكنك تخصيص شكل ومظهر العلامات التي تتمّ إضافتها إلى الخريطة. يمكنك فعل ذلك عن طريق تحديد تخصيصات العلامة، والتي تطبقها حزمة تطوير البرامج (SDK) لـ JavaScript بعد ذلك قبل إضافة علامات إلى الخريطة ومع كل تحديث للعلامة.

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

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

توفِّر حزمة تطوير البرامج (SDK) لJavaScript مَعلمات التخصيص التالية في FleetEngineTripLocationProviderOptions:

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

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

JavaScript

vehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

vehicleMarkerCustomization = {
  cursor: 'grab'
};

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

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

JavaScript

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

TypeScript

vehicleMarkerCustomization =
  (params: TripMarkerCustomizationFunctionParams) => {
    const distance = params.trip.remainingWaypoints.length;
    params.marker.setLabel(`${distance}`);
};

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

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

JavaScript

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

TypeScript

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

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

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

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

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

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

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.trip.remainingWaypoints[0].distanceMeters;
    if (distance < 1000) {

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

TypeScript

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

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

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

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

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

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

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

JavaScript

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

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

TypeScript

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

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

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

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

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

JavaScript

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

locationProvider.addListener('update', e => {
  const stopsCount = e.trip.remainingWaypoints.length;
  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.FleetEngineTripLocationProviderUpdateEvent) => {
  const stopsCount = e.trip.remainingWaypoints.length;
  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

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

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

يمكنك استخدام حزمة تطوير برامج (SDK) 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, centered at Uluru
  var map = new google.maps.Map(document.getElementById('map'));
  map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});

  // The marker, 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>

لإضافة حزمة تطوير البرامج (SDK) ل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
async 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.FleetEngineTripLocationProvider({
    projectId: "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.tripId = TRIP_ID;

    // (4) Add customizations like before.

    // The location of Uluru
    var uluru = {lat: -25.344, lng: 131.036};
    // The map, centered at Uluru
    var map = mapView.map;
    map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});
    // The marker, 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 SDK 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>

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

بدء استخدام حزمة تطوير البرامج (SDK) للمستهلك بشأن JavaScript

المكوّنات

عرض خريطة مستوى التقدُّم في الرحلة والطلبات

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

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

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

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

الموقع الجغرافي الخاص بالنقطة الوسيطة

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

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

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

التحكم في إمكانية رؤية المواقع التي يتم تتبّعها

مركبات

جميع علامات الموقع الأخرى

بدء استخدام حزمة تطوير البرامج (SDK) ل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

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

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

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

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

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

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

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