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

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

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

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

تحدِّد حزمة JavaScript SDK مسبقًا موفِّر الموقع الجغرافي لواجهة برمجة التطبيقات 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);

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

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

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

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

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

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