وقتی سفری را دنبال می‌کنید، برنامه‌ی مصرف‌کننده‌ی شما موقعیت مکانی وسیله‌ی نقلیه‌ی مناسب را به مصرف‌کننده نمایش می‌دهد. برای انجام این کار، برنامه‌ی شما باید شروع به دنبال کردن سفر کند، پیشرفت سفر را در طول سفر به‌روزرسانی کند و پس از اتمام سفر، دنبال کردن آن را متوقف کند.
این سند مراحل کلیدی زیر را در این فرآیند پوشش می‌دهد:
- نقشه تنظیم کنید
- یک نقشه را مقداردهی اولیه کنید و سفر مشترک را نمایش دهید
- به‌روزرسانی و پیگیری پیشرفت سفر
- دنبال کردن یک سفر را متوقف کنید
- خطاهای تریپ را مدیریت کنید
نقشه تنظیم کنید
برای دنبال کردن یک محموله در اپلیکیشن وب خود، باید یک نقشه بارگذاری کنید و Consumer SDK را نمونه‌سازی کنید تا بتوانید مسیر خود را ردیابی کنید. می‌توانید یک نقشه جدید بارگذاری کنید یا از یک نقشه موجود استفاده کنید. سپس از تابع مقداردهی اولیه برای نمونه‌سازی Consumer SDK استفاده می‌کنید تا نمای نقشه با موقعیت مکانی کالای مورد نظر مطابقت داشته باشد.
بارگذاری نقشه جدید با استفاده از API جاوا اسکریپت نقشه‌های گوگل
برای ایجاد یک نقشه جدید، API جاوا اسکریپت Google Maps را در برنامه وب خود بارگذاری کنید. مثال زیر نحوه بارگذاری API جاوا اسکریپت Google Maps، فعال کردن SDK و شروع بررسی مقداردهی اولیه را نشان می‌دهد.
- پارامتر
callbackتابعinitMapرا پس از بارگذاری API اجرا می‌کند. - ویژگی
deferبه مرورگر اجازه می‌دهد تا در حین بارگذاری API، به رندر کردن بقیه صفحه شما ادامه دهد.
از تابع initMap برای نمونه‌سازی Consumer SDK استفاده کنید. برای مثال:
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>
بارگذاری نقشه موجود
همچنین می‌توانید یک نقشه موجود که توسط API جاوا اسکریپت Google Maps ایجاد شده است، مانند نقشه‌ای که قبلاً از آن استفاده کرده‌اید، را بارگذاری کنید.
برای مثال، فرض کنید یک صفحه وب با موجودیت استاندارد 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()مقداردهی اولیه کنید. این نما شامل نقشه است.سفارشی‌سازی خود را برای مقداردهی اولیه نمای نقشه به تابع فراخوانی منتقل کنید.
کتابخانه مکان را به بارگذار API اضافه کنید.
مثال زیر تغییراتی را که باید اعمال شود نشان می‌دهد. اگر سفری را با شناسه مشخص شده در نزدیکی اولورو انجام دهید، اکنون روی نقشه نمایش داده می‌شود:
<!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>
مقداردهی اولیه نقشه و نمایش پیشرفت سفر
وقتی سفری شروع می‌شود، برنامه شما باید یک ارائه‌دهنده مکان سفر را نمونه‌سازی کند و سپس یک نقشه را برای شروع اشتراک‌گذاری پیشرفت سفر مقداردهی اولیه کند. برای مثال‌ها به بخش‌های بعدی مراجعه کنید.
یک ارائه دهنده مکان سفر را نمونه‌سازی کنید
کیت توسعه نرم‌افزار جاوااسکریپت (SSDK) یک ارائه‌دهنده موقعیت مکانی از پیش تعریف‌شده برای API اشتراک‌گذاری خودرو Fleet Engine دارد. برای نمونه‌سازی آن از شناسه پروژه و ارجاع به کارخانه توکن خود استفاده کنید.
جاوا اسکریپت
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',
});
تایپ اسکریپت
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 جاوا اسکریپت، نمای نقشه را مقداردهی اولیه کرده و آن را به صفحه HTML اضافه کنید. صفحه شما باید حاوی یک عنصر <div> باشد که نمای نقشه را در خود جای می‌دهد. عنصر <div> در مثال زیر map_canvas نام دارد.
جاوا اسکریپت
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);
تایپ اسکریپت
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);
به‌روزرسانی و پیگیری پیشرفت سفر
برنامه شما باید به رویدادها گوش دهد و پیشرفت سفر را با پیشرفت سفر به‌روزرسانی کند. می‌توانید با استفاده از ارائه‌دهنده موقعیت مکانی، اطلاعات متا در مورد یک سفر را از شیء وظیفه بازیابی کنید. اطلاعات متا شامل ETA و مسافت باقی‌مانده قبل از سوار یا پیاده شدن است. تغییرات در اطلاعات متا باعث ایجاد یک رویداد به‌روزرسانی می‌شود. مثال زیر نحوه گوش دادن به این رویدادهای تغییر را نشان می‌دهد.
جاوا اسکریپت
locationProvider.addListener('update', e => {
// e.trip contains data that may be useful
// to the rest of the UI.
console.log(e.trip.dropOffTime);
});
تایپ اسکریپت
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);
});
دنبال کردن یک سفر را متوقف کنید
وقتی سفر تمام شد، باید جلوی ردیابی سفر توسط ارائه‌دهنده‌ی موقعیت مکانی را بگیرید. برای انجام این کار، شناسه‌ی سفر و ارائه‌دهنده‌ی موقعیت مکانی را حذف می‌کنید. برای مثال‌ها به بخش‌های بعدی مراجعه کنید.
شناسه سفر را از ارائه دهنده مکان حذف کنید
مثال زیر نحوه حذف شناسه سفر از ارائه دهنده مکان را نشان می‌دهد.
جاوا اسکریپت
locationProvider.tripId = '';
تایپ اسکریپت
locationProvider.tripId = '';
ارائه دهنده موقعیت مکانی را از نمای نقشه حذف کنید
مثال زیر نحوه حذف یک ارائه دهنده موقعیت مکانی از نمای نقشه را نشان می‌دهد.
جاوا اسکریپت
mapView.removeLocationProvider(locationProvider);
تایپ اسکریپت
mapView.removeLocationProvider(locationProvider);
خطاهای تریپ را مدیریت کنید
خطاهایی که به صورت غیرهمزمان از درخواست اطلاعات سفر ایجاد می‌شوند، رویدادهای خطا را فعال می‌کنند. مثال زیر نحوه گوش دادن به این رویدادها برای مدیریت خطاها را نشان می‌دهد.
جاوا اسکریپت
locationProvider.addListener('error', e => {
// e.error contains the error that triggered the
// event
console.error(e.error);
});
تایپ اسکریپت
locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
// e.error contains the error that triggered the
// event
console.error(e.error);
});