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

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

تتبُّع أسطولك باستخدام مكتبة JavaScript FleetTracking

هذا المنتج أو هذه الميزة في مرحلة المعاينة (ما قبل التوفّر للجمهور العام). قد يتوفّر دعم محدود للمنتجات والميزات المتوفّرة في مرحلة ما قبل التوفّر للجمهور العام، وقد لا تتوافق التغييرات في المنتجات والميزات المتوفّرة في مرحلة ما قبل التوفّر للجمهور العام مع الإصدارات الأخرى المتاحة في مرحلة ما قبل التوفّر للجمهور العام. تخضع "عروض مرحلة ما قبل التوفّر للجمهور العام" للأحكام الخاصة بخدمة "منصة خرائط Google". لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مرحلة الإطلاق.

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

المكوّنات

توفر مكتبة JavaScript Fleet Tracking Library مكونات لعرض المركبات ونقاط طريق الرحلة، بالإضافة إلى خلاصات البيانات الأولية للوقت المقدر للوصول أو المسافة المتبقية قبل الرحلة.

عرض خريطة تتبُّع الأسطول

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

مثال على عرض خريطة
لتتبع الأسطول

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

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

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

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

مزوِّد الموقع الجغرافي لمجموعة المركبات

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

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

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

مركبات

تكون المركبة مرئية فور إنشائها في Fleet Engine، وتكون مرئية عندما تكون حالة السيارة هي Online. هذا يعني أنه يمكن أن تكون المركبة مرئية حتى في حالة عدم وجود رحلة حالية مخصصة للمركبة.

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

تشير علامة موقع نقطة الطريق إلى النقاط على طول رحلة المركبة بدءًا من نقطة الانطلاق وتنتهي بالوجهة النهائية. ويمكن تعريف علامات موقع النقطة الطريق على النحو التالي:

نقطة الانطلاق - تشير إلى موقع بدء رحلة المركبة
متوسط - يشير إلى محطات التوقف لرحلة المركبة
الوجهة - للإشارة إلى الموقع النهائي لرحلة المركبة

يتم عرض نقاط طريق المركبة المخطط لها على الخريطة كعلامات أصل ووسيط ووجهة.

بدء استخدام مكتبة JavaScript Fleet Tracking Library

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

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

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

لإنشاء حمولة JWT، أضِف مطالبة إضافية في قسم التفويض باستخدام المفتاحَين tripid وvehicleid واضبط السمة value لكل مفتاح على *. يجب إنشاء الرمز المميّز باستخدام دور المستخدم المميّز لخدمة Fleet Engine في Cloud IAM. يُرجى العِلم أنّ هذا الإجراء يتيح إمكانية الوصول الواسع النطاق لإنشاء كيانات Fleet Engine وقراءتها وتعديلها، ويجب مشاركته مع المستخدمين الموثوق بهم فقط.

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

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

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

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

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

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

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

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

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

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

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/driver/VEHICLE_ID
- https://SERVER_URL/token/consumer/TRIP_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&v=beta" defer></script>

متابعة مركبة

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

إنشاء نسخة من موفّر الموقع الجغرافي للمركبة

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

JavaScript

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

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

TypeScript

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

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

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

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

JavaScript

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

// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.vehicleId
                        = 'your-vehicle-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('Times Square, New York, NY');
mapView.map.setZoom(14);

TypeScript

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

// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.vehicleId = 'your-vehicle-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('Times Square, New York, NY');
mapView.map.setZoom(14);

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

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

JavaScript

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

TypeScript

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

الاستماع إلى الأخطاء

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

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

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

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

JavaScript

locationProvider.vehicleId = '';

TypeScript

locationProvider.vehicleId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

عرض مجموعة مركبات

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

إنشاء مثيل لموقع أسطول المركبات

تحدد مكتبة JavaScript Fleet Tracking Library مسبقًا موفّر موقع جغرافي يجلب مركبات متعددة من واجهة برمجة التطبيقات On Demand Rides and Deliveries API. استخدِم معرّف المشروع بالإضافة إلى مرجع إلى أداة جلب الرموز المميّزة لإنشاء مثيل لها.

JavaScript

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

          // Optionally, specify location bounds to
          // limit which vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which vehicles are retrieved.
          vehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

TypeScript

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

          // Optionally, specify location bounds to
          // limit which vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which vehicles are retrieved.
          vehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

تحدّد السمة vehicleFilter طلب بحث يتم استخدامه لفلترة المركبات المعروضة على الخريطة. يتم تمرير هذا الفلتر مباشرةً إلى Fleet Engine. راجِع ListVehiclesRequest للاطّلاع على التنسيقات المتوافقة.

تحدّد ميزة locationRestriction المنطقة التي يمكن فيها عرض المركبات على الخريطة. وتتحكّم أيضًا في ما إذا كان تتبُّع الموقع الجغرافي نشطًا أم لا. لن تبدأ عملية تتبّع الموقع الجغرافي حتى يتم ضبط هذا الإعداد

بعد إنشاء موفِّر الموقع الجغرافي، عليك إعداد عرض الخريطة.

ضبط تقييد الموقع الجغرافي باستخدام إطار عرض الخريطة

يمكن ضبط حدود locationRestriction لمطابقة المنطقة المرئية في عرض الخريطة.

JavaScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location tracking will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

TypeScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location tracking will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

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

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

JavaScript

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

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineFleetLocationProviderUpdateEvent) => {
  // e.vehicles contains data that may be useful to the rest of the UI.
  if (e.vehicles) {
    for (vehicle of e.vehicles) {
      console.log(vehicle.navigationStatus);
    }
  }
});

الاستماع إلى الأخطاء

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

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

لمنع مقدم خدمة الموقع من تتبع الأسطول، اضبط حدود موفّر الموقع على "خالٍ".

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

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

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

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

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

JavaScript

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

TypeScript

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

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

هناك طريقة أخرى لتخصيص تصميم الخريطة، وهي ضبط 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 Fleet Tracking Library، يمكنك تخصيص شكل ومظهر العلامات التي تمت إضافتها إلى الخريطة. يمكنك القيام بذلك عن طريق تحديد تخصيصات العلامات، التي تطبقها مكتبة Fleet Tracking Library قبل إضافة علامات إلى الخريطة ومع كل تحديث للعلامة.

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

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

بالإضافة إلى ذلك، يمكنك استخدام وظائف التخصيص لفلترة إذن الوصول إلى العلامات. لإجراء ذلك، عليك استدعاء setVisible(false) في محدّد الموقع.

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

توفِّر مكتبة "تتبُّع الأسطول" مَعلمات التخصيص التالية:

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

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

JavaScript

vehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

vehicleMarkerCustomization = {
  cursor: 'grab'
};

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

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

JavaScript

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

TypeScript

vehicleMarkerCustomization =
  (params: VehicleMarkerCustomizationFunctionParams) => {
    var remainingWaypoints = params.vehicle.waypoints.length;
    params.marker.setLabel(`${remainingWaypoints}`);
  };

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

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

JavaScript

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

TypeScript

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

فلترة العلامات المرئية

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

JavaScript

vehicleMarkerCustomization =
  (params) => {
    var remainingWaypoints = params.vehicle.remainingWaypoints.length;
      if (remainingWaypoints > 10) {
        params.marker.setVisible(false);
      }
  };

TypeScript

vehicleMarkerCustomization =
  (params: VehicleMarkerCustomizationFunctionParams) => {
    var remainingWaypoints = params.vehicle.remainingWaypoints.length;
    if (remainingWaypoints > 10) {
      params.marker.setVisible(false);
    }
  };

استخدام تخصيص الخطوط المتعددة عند متابعة مركبة

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

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

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

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

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.vehicle.waypoints[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: VehiclePolylineCustomizationFunctionParams) => {
    const distance = params.vehicle.waypoints[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 =
  FleetEngineVehicleLocationProvider.
      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) => {
    FleetEngineVehicleLocationProvider.
        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 =
  FleetEngineVehicleLocationProvider.
      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: VehiclePolylineCustomizationFunctionParams) => {
    FleetEngineVehicleLocationProvider.
        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});

// (Assumes a vehicle location provider.)
locationProvider.addListener('update', e => {
  if (e.vehicle) {
    const distance =
          e.vehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next drop-off point.`);

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

// (Assumes a vehicle location provider.)
locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineVehicleLocationProviderUpdateEvent) => {
  if (e.vehicle) {
    const distance =
          e.vehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next drop-off.`);
    // 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,
  ...
});

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

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

على سبيل المثال، لنفترض أنّ لديك صفحة ويب تتضمّن كيان 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 Oracle Park Stadium
        var oraclePark = { lat: 37.780087547237365, lng: -122.38948437884427 };,
        // 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 Oracle Park
        var marker = new google.maps.Marker({ position: oraclePark, 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 Journey Share، والتي تتضمّن ميزة "تتبُّع الأسطول":

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

      mapView.addListener('ready', () => {
        locationProvider.vehicleId = VEHICLE_ID;

          // (4) Add customizations like before.

          // The location of Oracle Park
          var oraclePark = {lat: 37.77995187146094, lng: -122.38957020952795};
          // 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 Oracle Park
          var marker = new google.maps.Marker({position: oraclePark, 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, which includes Fleet Tracking functionality.
    -->
    <script
      defer
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing&v=beta"
    ></script>
  </body>
</html>

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

تتبُّع أسطولك باستخدام مكتبة JavaScript FleetTracking

المكوّنات

عرض خريطة تتبُّع الأسطول

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

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

مزوِّد الموقع الجغرافي لمجموعة المركبات

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

مركبات

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

بدء استخدام مكتبة JavaScript Fleet Tracking Library

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

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

JavaScript

TypeScript

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

متابعة مركبة

إنشاء نسخة من موفّر الموقع الجغرافي للمركبة

JavaScript

TypeScript

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

JavaScript

TypeScript

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

JavaScript

TypeScript

الاستماع إلى الأخطاء

JavaScript

TypeScript

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

JavaScript

TypeScript

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

JavaScript

TypeScript

عرض مجموعة مركبات

إنشاء مثيل لموقع أسطول المركبات

JavaScript

TypeScript

ضبط تقييد الموقع الجغرافي باستخدام إطار عرض الخريطة

JavaScript

TypeScript

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

JavaScript

TypeScript

الاستماع إلى الأخطاء

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

JavaScript

TypeScript

فلترة العلامات المرئية

JavaScript

TypeScript

استخدام تخصيص الخطوط المتعددة عند متابعة مركبة

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

JavaScript

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

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

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

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

عرض عناصر "`Polyline`" المتوافقة مع حركة المرور

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