وقتی سفری را دنبال میکنید، برنامه مصرفکننده شما مکان خودرو مناسب را به مصرفکننده نمایش میدهد. برای انجام این کار، برنامه شما باید سفر را دنبال کند، پیشرفت سفر را درطول سفر بهروز کند، و پساز تکمیل سفر، دنبال کردن آن را متوقف کند.
این سند مراحل کلیدی زیر را در این فرایند پوشش میدهد:
- راهاندازی نقشه
- مقداردهی اولیه نقشه و نمایش سفر همرسانیشده
- بهروزرسانی و دنبال کردن پیشرفت سفر
- توقف دنبال کردن سفر
- رسیدگی به خطاهای سفر
راهاندازی نقشه
برای دنبال کردن تحویل یا دریافت محموله در برنامه وب، باید نقشهای را بار کنید و «کیت توسعه نرمافزار مصرفکننده» را نمونهسازی کنید تا ردیابی سفرتان شروع شود. میتوانید نقشه جدیدی بار کنید یا از نقشه موجود استفاده کنید. سپس از تابع مقداردهی اولیه برای نمونهسازی Consumer SDK استفاده میکنید تا نمای نقشه با مکان موردی که ردیابی میشود مطابقت داشته باشد.
بار کردن نقشه جدید بااستفاده از Google Maps JavaScript API
برای ایجاد نقشه جدید، Google Maps JavaScript API را در برنامه وب خود بار کنید. مثال زیر نحوه بار کردن Google Maps JavaScript API، فعال کردن SDK، و راهاندازی بررسی مقداردهی اولیه را نشان میدهد.
- پارامتر
callbackتابعinitMapرا پساز بار شدن API اجرا میکند. - مشخصه
deferبه مرورگر اجازه میدهد تا درحین بار شدن میانای برنامهسازی کاربردی، به رندر کردن بقیه صفحه ادامه دهد.
از تابع initMap برای نمونهسازی «کیت توسعه نرمافزار مصرفکننده» استفاده کنید. برای مثال:
<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>
مقداردهی اولیه نقشه و نمایش پیشرفت سفر
وقتی سفری شروع میشود، برنامهتان باید ارائهدهنده مکان سفر را نمونهسازی کند و سپس نقشهای را برای شروع همرسانی پیشرفت سفر مقداردهی اولیه کند. برای مشاهده مثالها، بخشهای زیر را ببینید.
نمونهسازی ارائهدهنده مکان سفر
کیت توسعه نرمافزار جاوا اسکریپت ارائهدهنده مکان ازپیش تعریفشدهای برای 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',
});
مقداردهی اولیه نمای نقشه
پساز بار کردن کیت توسعه نرمافزار جاوا اسکریپت، نمای نقشه را مقداردهی اولیه کنید و آن را به صفحه 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);
});