عند متابعة رحلة، يعرض تطبيق المستهلك الموقع الجغرافي للمركبة المناسبة للمستهلك. ولإجراء ذلك، يجب أن يبدأ تطبيقك في تتبُّع الرحلة، وأن يعدّل مستوى تقدّم الرحلة أثناءها، وأن يتوقف عن تتبُّعها عند اكتمالها.
يتناول هذا المستند الخطوات الرئيسية التالية في هذه العملية:
- إعداد خريطة
- تهيئة خريطة وعرض الرحلة المشترَكة
- تعديل رحلة ومتابعة تقدّمها
- إيقاف متابعة رحلة
- التعامل مع أخطاء الرحلات
إعداد خريطة
لتتبُّع عملية استلام شحنة أو تسليمها في تطبيق الويب، عليك تحميل خريطة وإنشاء مثيل من Consumer SDK لبدء تتبُّع رحلتك. يمكنك تحميل خريطة جديدة أو استخدام خريطة حالية. بعد ذلك، يمكنك استخدام دالة التهيئة لإنشاء مثيل من Consumer SDK حتى يتطابق عرض الخريطة مع الموقع الجغرافي للعنصر الذي يتم تتبُّعه.
تحميل خريطة جديدة باستخدام Google Maps JavaScript API
لإنشاء خريطة جديدة، حمِّل Google Maps JavaScript API في تطبيق الويب. يوضّح المثال التالي كيفية تحميل Google Maps JavaScript API وتفعيل حزمة SDK وتشغيل عملية التحقّق من الإعداد.
- تنفِّذ المَعلمة
callbackالدالةinitMapبعد تحميل واجهة برمجة التطبيقات. - تتيح السمة
deferللمتصفّح مواصلة عرض بقية صفحتك أثناء تحميل واجهة برمجة التطبيقات.
استخدِم الدالة initMap لإنشاء مثيل لحزمة تطوير البرامج (SDK) الخاصة بالمستهلك. على سبيل المثال:
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>
تحميل خريطة حالية
يمكنك أيضًا تحميل خريطة حالية تم إنشاؤها باستخدام Google Maps JavaScript API، مثل خريطة تستخدمها حاليًا.
على سبيل المثال، لنفترض أنّ لديك صفحة ويب تتضمّن عنصر google.maps.Map
عاديًا يتم عرض علامة عليه كما هو محدّد في رمز HTML التالي. يعرض هذا الرمز خريطتك باستخدام الدالة 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>
// Initialize and add the map
function initMap() {
// The location of Pier 39 in San Francisco
var pier39 = {lat: 37.809326, lng: -122.409981};
// 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 Pier 39
var marker = new google.maps.Marker({position: pier39, map: map});
}
</script>
<!-- Load the API from the specified URL.
* The defer attribute allows the browser to render the page while the API loads.
* The key parameter contains your own API key.
* 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>
استبدال خريطة حالية
يمكنك استبدال خريطة حالية تتضمّن علامات أو تخصيصات أخرى بدون فقدان هذه التخصيصات.
على سبيل المثال، إذا كانت لديك صفحة ويب تتضمّن عنصر google.maps.Map عاديًا يتم عرض علامة عليه، يمكنك استبدال الخريطة والإبقاء على العلامة. يوضّح هذا القسم الخطوات اللازمة لإجراء ذلك.
لاستبدال الخريطة والاحتفاظ بالتخصيصات، أضِف ميزة "مشاركة الرحلة" إلى صفحة HTML باتّباع الخطوات التالية، والتي تم ترقيمها أيضًا في المثال أدناه:
أضِف رمزًا لإنشاء الرمز المميز للمصادقة.
إعداد موفّر خدمة الموقع الجغرافي في الدالة
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 Pier 39 in San Francisco
var pier39 = {lat: 37.809326, lng: -122.409981};
// 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 Pier 39
var marker = new google.maps.Marker({position: pier39, 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 على موفِّر موقع جغرافي محدّد مسبقًا لواجهة برمجة التطبيقات 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: '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',
});
تهيئة عرض الخريطة
بعد تحميل حزمة تطوير البرامج (SDK) في 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 trip ID in the location
// provider constructor, you may do so here.
// Location tracking starts 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 choose.
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.
vehicleMarkerSetup: vehicleMarkerSetup,
anticipatedRoutePolylineSetup:
anticipatedRoutePolylineSetup,
// 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 starts 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 choose.
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.tripId = '';
TypeScript
locationProvider.tripId = '';
إزالة مقدّم خدمة الموقع الجغرافي من عرض الخريطة
يوضّح المثال التالي كيفية إزالة مقدّم خدمة تحديد الموقع الجغرافي من عرض الخريطة.
JavaScript
mapView.removeLocationProvider(locationProvider);
TypeScript
mapView.removeLocationProvider(locationProvider);
التعامل مع أخطاء الرحلات
تؤدي الأخطاء التي تحدث بشكل غير متزامن عند طلب معلومات الرحلة إلى تشغيل أحداث الأخطاء. يوضّح المثال التالي كيفية الاستماع إلى هذه الأحداث للتعامل مع الأخطاء.
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);
});