وقتی سفری را به اشتراک می گذارید، برنامه مصرف کننده شما مکان وسیله نقلیه مناسب را به مصرف کننده نشان می دهد. برای انجام این کار، برنامه شما باید شروع به اشتراک گذاری سفر کند، پیشرفت سفر را در طول سفر به روز کند، و پس از اتمام سفر، اشتراک گذاری سفر را متوقف کند.
این سند مراحل کلیدی زیر را در این فرآیند پوشش می دهد:
- یک نقشه تنظیم کنید
- نقشه را راه اندازی کنید و سفر مشترک را نمایش دهید
- به روز رسانی و پیگیری پیشرفت سفر
- اشتراک گذاری سفر را متوقف کنید
- خطاهای اشتراک گذاری سفر را مدیریت کنید
یک نقشه تنظیم کنید
برای پیگیری تحویل محموله یا تحویل در برنامه وب خود، باید یک نقشه بارگیری کنید و SDK مصرف کننده را برای شروع ردیابی سفر خود به صورت نمونه بردارید. می توانید یک نقشه جدید بارگیری کنید یا از یک نقشه موجود استفاده کنید. سپس از تابع مقداردهی اولیه برای نمونه سازی Consumer SDK استفاده می کنید تا نمای نقشه با مکان مورد ردیابی مطابقت داشته باشد.
با استفاده از Google Maps JavaScript API یک نقشه جدید بارگیری کنید
برای ایجاد یک نقشه جدید، Google Maps JavaScript API را در برنامه وب خود بارگیری کنید. مثال زیر نحوه بارگیری Google Maps JavaScript API، فعال کردن 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>
یک نقشه موجود را بارگیری کنید
همچنین می توانید نقشه موجود ایجاد شده توسط 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()راه اندازی کنید. نمای شامل نقشه است.سفارشی سازی خود را به تابع callback برای مقداردهی اولیه نمای نقشه منتقل کنید.
کتابخانه مکان را به بارگذار API اضافه کنید.
مثال زیر تغییراتی را که باید انجام شود را نشان می دهد. اگر سفری را با شناسه مشخص شده در نزدیکی Uluru انجام دهید، اکنون روی نقشه نشان داده می شود:
<!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>
نقشه را راه اندازی کنید و سفر مشترک را نمایش دهید
وقتی یک سفر شروع می‌شود، برنامه شما باید یک ارائه‌دهنده مکان سفر را نمونه‌سازی کند و سپس یک نقشه را برای شروع اشتراک‌گذاری سفر راه‌اندازی کند. برای نمونه به بخش های زیر مراجعه کنید.
ارائه‌دهنده مکان سفر را معرفی کنید
JavaScript SDK یک ارائه دهنده مکان از پیش تعریف شده برای Fleet Engine Ridesharing API دارد. از شناسه پروژه خود و یک مرجع به کارخانه توکن خود برای نمونه سازی آن استفاده کنید.
جاوا اسکریپت
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، نمای نقشه را مقداردهی اولیه کنید و آن را به صفحه 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);
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);
به روز رسانی و پیگیری پیشرفت سفر
برنامه شما باید به رویدادها گوش دهد و با پیشرفت سفر، پیشرفت سفر را به‌روزرسانی کند. می توانید اطلاعات متا در مورد یک سفر را از شیء وظیفه با استفاده از ارائه دهنده مکان بازیابی کنید. اطلاعات متا شامل ETA و فاصله باقیمانده قبل از تحویل یا رها شدن است. تغییرات در اطلاعات متا باعث یک رویداد به‌روزرسانی می‌شود. مثال زیر نحوه گوش دادن به این رویدادهای تغییر را نشان می دهد.
جاوا اسکریپت
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);
});
اشتراک گذاری سفر را متوقف کنید
هنگامی که سفر به پایان می رسد، باید از ردیابی سفر توسط ارائه دهنده مکان جلوگیری کنید. برای انجام این کار، شناسه سفر و ارائه‌دهنده موقعیت مکانی را حذف می‌کنید. برای نمونه به بخش های زیر مراجعه کنید.
شناسه سفر را از ارائه‌دهنده موقعیت مکانی حذف کنید
مثال زیر نحوه حذف شناسه سفر را از ارائه دهنده موقعیت مکانی نشان می دهد.
جاوا اسکریپت
locationProvider.tripId = '';
TypeScript
locationProvider.tripId = '';
ارائه دهنده موقعیت مکانی را از نمای نقشه حذف کنید
مثال زیر نحوه حذف ارائه دهنده موقعیت مکانی را از نمای نقشه نشان می دهد.
جاوا اسکریپت
mapView.removeLocationProvider(locationProvider);
TypeScript
mapView.removeLocationProvider(locationProvider);
خطاهای اشتراک گذاری سفر را مدیریت کنید
خطاهایی که به طور ناهمزمان از درخواست اطلاعات سفر به وجود می آیند، رویدادهای خطا را راه اندازی می کنند. مثال زیر نحوه گوش دادن به این رویدادها را برای رسیدگی به خطاها نشان می دهد.
جاوا اسکریپت
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);
});