ردیابی محموله ها با کتابخانه ردیابی حمل و نقل جاوا اسکریپت، ردیابی محموله ها با کتابخانه ردیابی حمل و نقل جاوا اسکریپت

کتابخانه ردیابی حمل و نقل جاوا اسکریپت به شما امکان می دهد مکان وسایل نقلیه و مکان های مورد علاقه ردیابی شده در Fleet Engine را تجسم کنید. این کتابخانه حاوی یک جزء نقشه جاوا اسکریپت است که جایگزینی برای یک موجودیت استاندارد google.maps.Map و اجزای داده برای اتصال با Fleet Engine است. با استفاده از کتابخانه ردیابی حمل و نقل جاوا اسکریپت، می توانید یک تجربه ردیابی محموله قابل تنظیم و متحرک از برنامه وب خود ارائه دهید.

اجزاء

کتابخانه ردیابی حمل و نقل جاوا اسکریپت اجزایی را برای تجسم وسیله نقلیه و مسیری که به سمت مقصد پیش می‌رود، و همچنین داده‌های خام برای ETA راننده یا مسافت باقی‌مانده برای رانندگی فراهم می‌کند.

نمای نقشه ردیابی حمل و نقل

جزء نمای نقشه مکان وسایل نقلیه و مقاصد را تجسم می کند. اگر مسیر یک وسیله نقلیه مشخص باشد، مؤلفه نمای نقشه آن وسیله نقلیه را در حالی که در مسیر پیش بینی شده خود حرکت می کند، متحرک می کند.

ارائه دهنده محل حمل و نقل

یک ارائه‌دهنده موقعیت حمل و نقل، اطلاعات موقعیت مکانی اشیاء ردیابی شده را در نقشه ردیابی محموله برای ردیابی اولین و آخرین مایل محموله تغذیه می‌کند.

برای ردیابی می توانید از ارائه دهنده موقعیت حمل و نقل استفاده کنید:

  • محل تحویل یا تحویل یک محموله.
  • محل و مسیر وسیله نقلیه تحویل.

اشیاء مکان ردیابی شده

ارائه دهنده موقعیت مکانی اشیاء مانند وسایل نقلیه و مقصد را ردیابی می کند.

مکان مقصد

مکان مقصد مکانی است که یک سفر در آن به پایان می رسد. برای ردیابی محموله، محل کار برنامه ریزی شده است.

مکان وسیله نقلیه

مکان وسیله نقلیه، مکان ردیابی شده یک وسیله نقلیه است. ممکن است به صورت اختیاری مسیری برای وسیله نقلیه داشته باشد.

واکشی نشانه احراز هویت

برای کنترل دسترسی به داده‌های مکان ذخیره شده در Fleet Engine، باید یک سرویس JSON Web Token (JWT) برای Fleet Engine بر روی سرور خود پیاده‌سازی کنید. سپس با استفاده از کتابخانه به اشتراک گذاری سفر جاوا اسکریپت برای احراز هویت دسترسی به داده های مکان، یک واکشی توکن احراز هویت را به عنوان بخشی از برنامه وب خود پیاده سازی کنید .

گزینه های یک ظاهر طراحی شده

استایل های نشانگر و چند خطی ظاهر و احساس اشیاء مکان ردیابی شده را روی نقشه تعیین می کنند. می‌توانید از گزینه‌های استایل سفارشی برای تغییر استایل پیش‌فرض برای مطابقت با استایل برنامه وب خود استفاده کنید.

قابلیت مشاهده مکان های ردیابی شده را کنترل کنید

این بخش کنترل های دید برای اشیاء ردیابی شده روی نقشه را توضیح می دهد. این قوانین برای دو دسته از اشیاء اعمال می شود:

  • نشانگر مکان
  • داده های وظیفه

نمایان بودن نشانگر مکان

همه نشانگرهای مکان برای مبدا و مقصد همیشه روی نقشه نشان داده می شوند. به عنوان مثال، بدون توجه به وضعیت تحویل، محل تحویل محموله همیشه روی نقشه نشان داده می شود.

قابلیت مشاهده داده های وظیفه

این بخش قوانین دید پیش‌فرض را که برای داده‌های کار اعمال می‌شود، مانند مکان خودرو و مسیر باقی‌مانده، توضیح می‌دهد. شما می توانید بسیاری از کارها را سفارشی کنید اما نه همه:

  • وظایف در دسترس نبودن -- نمی توانید دید را برای این کارها سفارشی کنید.
  • وظایف وسیله نقلیه فعال -- می توانید این نوع کارها را سفارشی کنید.
  • وظایف وسیله نقلیه غیرفعال -- نمی توانید دید را برای این کارها سفارشی کنید.

وظایف در دسترس نبودن

اگر حداقل یک کار غیرقابل دسترس (مثلاً اگر راننده در حال استراحت باشد یا وسیله نقلیه در حال سوخت گیری باشد) در مسیر تا وظیفه ردیابی وجود داشته باشد، وسیله نقلیه قابل مشاهده نیست. زمان تخمینی رسیدن و زمان تخمینی تکمیل کار هنوز در دسترس است.

وظایف وسیله نقلیه فعال

شی TaskTrackingInfo تعدادی از عناصر داده را ارائه می دهد که می توانند در کتابخانه ردیابی حمل و نقل قابل مشاهده باشند. به‌طور پیش‌فرض، این فیلدها زمانی که وظیفه به وسیله نقلیه محول می‌شود و زمانی که خودرو در فاصله 5 ایستگاهی از کار قرار دارد، قابل مشاهده است. هنگامی که کار تکمیل یا لغو شد، نمایان شدن به پایان می رسد. فیلدها به شرح زیر است:

  • چند خطوط مسیریابی
  • زمان تخمینی برای رسیدن
  • زمان تخمینی تکمیل کار
  • فاصله رانندگی تا کار باقی مانده است
  • تعداد توقف های باقی مانده
  • مکان وسیله نقلیه

هنگام ایجاد یا به‌روزرسانی کار در Fleet Engine، می‌توانید با تنظیم TaskTrackingViewConfig بر روی یک کار، پیکربندی دید را بر اساس هر کار سفارشی کنید. این قوانینی را ایجاد می کند که چه زمانی عناصر داده فردی در دسترس هستند که می تواند بر اساس معیارهای زیر باشد (به عنوان گزینه قابل مشاهده در زیر اشاره می شود):

  • تعداد توقف های باقی مانده
  • مدت زمان تا زمان تخمینی رسیدن
  • فاصله رانندگی باقی مانده
  • همیشه قابل مشاهده است
  • هرگز قابل مشاهده نیست

توجه داشته باشید که هر عنصر داده فقط می تواند با یک گزینه قابل مشاهده مرتبط باشد. ترکیب معیارها با استفاده از OR یا AND امکان پذیر نیست.

نمونه ای از سفارشی سازی به شرح زیر است. قوانین آن سفارشی سازی عبارتند از:

  • اگر وسیله نقلیه در 3 ایستگاه است، چند خطوط مسیر را نشان دهید.
  • اگر مسافت رانندگی باقیمانده کمتر از 5000 متر باشد، ETA را نشان دهید.
  • هرگز تعداد توقف باقیمانده را نشان ندهید.
  • هر یک از فیلدهای دیگر دید پیش فرض را حفظ می کند که وقتی وسیله نقلیه در فاصله 5 ایست از کار قرار دارد نشان داده می شود.
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

همچنین می توانید با تماس با تیم پشتیبانی، پیکربندی نمای پیش فرض را برای پروژه خود سفارشی کنید.

چند خطوط مسیر و قوانین دید مکان خودرو:

هنگامی که چند خطوط مسیر قابل مشاهده هستند، مکان وسیله نقلیه نیز باید قابل مشاهده باشد، در غیر این صورت مکان وسیله نقلیه را می توان با انتهای چند خطوط نشان داد. این بدان معناست که چند خطوط مسیر نمی توانند گزینه دید کمتر محدودتری داشته باشند.

این قوانین باید رعایت شود تا ترکیبی از چند خط مسیر / دید مکان وسیله نقلیه معتبر ارائه شود:

  • وقتی چند خطوط مسیر و مکان وسیله نقلیه دارای یک نوع گزینه دید هستند:

    • اگر گزینه دید باقیمانده تعداد توقف، مدت زمان تا ETA یا مسافت رانندگی باقیمانده باشد، چند خطوط مسیر باید مقداری را ارائه دهند که کمتر یا مساوی مقدار تنظیم شده برای این گزینه دید برای مکان وسیله نقلیه باشد. یک مثال به شرح زیر است:
    "taskTrackingViewConfig": {
      "routePolylinePointsVisibility": {
        "remainingStopCountThreshold": 3
      },
      "vehicleLocationVisibility": {
        "remainingStopCountThreshold": 5
      },
    }
    
    • اگر چند خط مسیر دارای گزینه دید همیشه قابل مشاهده باشد، مکان وسیله نقلیه باید گزینه دید همیشه قابل مشاهده را نیز ارائه دهد.
    • اگر مکان وسیله نقلیه دارای گزینه دید هرگز قابل مشاهده نباشد، چند خطوط مسیر نیز باید گزینه دید هرگز قابل مشاهده نباشد.
  • وقتی چند خطوط مسیر و مکان وسیله نقلیه انواع گزینه های دید متفاوتی دارند، مکان وسیله نقلیه تنها زمانی قابل مشاهده است که هر دو گزینه دید آنها راضی باشند.

    یک مثال به شرح زیر است:

    "taskTrackingViewConfig": {
      "routePolylinePointsVisibility": {
        "remainingStopCountThreshold": 3
      },
      "vehicleLocationVisibility": {
        "remainingDrivingDistanceMetersThreshold": 3000
      },
    }
    

    در این مثال، مکان وسیله نقلیه تنها زمانی قابل مشاهده است که تعداد توقف باقیمانده حداقل 3 و مسافت باقیمانده رانندگی حداقل 3000 متر باشد.

با کتابخانه اشتراک گذاری سفر جاوا اسکریپت شروع کنید

قبل از استفاده از کتابخانه اشتراک‌گذاری سفر جاوا اسکریپت، مطمئن شوید که با Fleet Engine و دریافت کلید API آشنا هستید.

برای پیگیری تحویل، ابتدا یک ادعای شناسه ردیابی ایجاد کنید.

یک ادعای شناسه ردیابی ایجاد کنید

برای ردیابی یک محموله با استفاده از ارائه‌دهنده مکان ارسال ، یک رمز وب JSON (JWT) با ادعای شناسه ردیابی ایجاد کنید.

برای ایجاد بار JWT، یک ادعای اضافی در بخش مجوز با کلید trackingid اضافه کنید. مقدار آن را روی شناسه رهگیری محموله تنظیم کنید.

مثال زیر نحوه ایجاد توکن برای ردیابی با شناسه ردیابی را نشان می دهد:

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

یک واکشی نشانه احراز هویت ایجاد کنید

می‌توانید یک واکشی توکن احراز هویت ایجاد کنید تا با استفاده از یک گواهی حساب سرویس برای پروژه خود ، توکنی را که با ادعاهای مناسب بر روی سرورهای خود ضرب شده است، بازیابی کنید. مهم است که فقط توکن ها را در سرورهای خود برش دهید و هرگز گواهی های خود را در هیچ کلاینت به اشتراک نگذارید. در غیر این صورت، امنیت سیستم خود را به خطر خواهید انداخت.

واکشی باید یک ساختار داده با دو فیلد را که در یک Promise پیچیده شده است برگرداند:

  • یک token رشته
  • یک عدد expiresInSeconds . یک توکن در این مدت پس از واکشی منقضی می شود.

کتابخانه ردیابی حمل و نقل جاوا اسکریپت از طریق واکشی نشانه احراز هویت، زمانی که هر یک از موارد زیر درست باشد، یک رمز درخواست می کند:

  • رمز معتبری ندارد، مانند زمانی که واکشی را در بارگذاری صفحه جدید فراخوانی نکرده است، یا زمانی که واکشی با یک توکن برنگشته است.
  • توکنی که قبلاً واکشی شده بود منقضی شده است.
  • توکنی که قبلاً واکشی شده است در عرض یک دقیقه پس از انقضا است.

در غیر این صورت، کتابخانه از رمز صادر شده قبلی استفاده می کند و هنوز معتبر است و واکشی را فراخوانی نمی کند.

مثال زیر نحوه ایجاد یک واکشی نشانه احراز هویت را نشان می دهد:

جاوا اسکریپت

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 داده شده است. ExpiresInSeconds.
  • همانطور که در مثال نشان داده شده است، واکشی نشانه احراز هویت باید زمان انقضا (بر حسب ثانیه، از زمان واکشی) را به کتابخانه منتقل کند.
  • SERVER_TOKEN_URL به پیاده‌سازی باطن شما بستگی دارد، اینها نشانی‌های وب برای نمونه برنامه پشتیبان هستند:
    • https:// SERVER_URL /token/delivery_driver/ DELIVERY_VEHICLE_ID
    • https:// SERVER_URL /token/delivery_consumer/ TRACKING_ID
    • https:// SERVER_URL /token/fleet_reader

یک نقشه از HTML بارگیری کنید

مثال زیر نحوه بارگیری کتابخانه ردیابی حمل و نقل جاوا اسکریپت را از یک URL مشخص نشان می دهد. پارامتر callback تابع initMap را پس از بارگیری API اجرا می کند. ویژگی defer به مرورگر اجازه می‌دهد تا زمانی که API بارگیری می‌شود، بقیه صفحه شما را رندر کند.

<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>

یک محموله را دنبال کنید

این بخش نحوه استفاده از کتابخانه ردیابی حمل و نقل جاوا اسکریپت را برای پیگیری تحویل یا تحویل نشان می دهد. قبل از اجرای کد، حتماً کتابخانه را از تابع callback مشخص شده در تگ اسکریپت بارگیری کنید .

ارائه دهنده محل حمل و نقل را معرفی کنید

کتابخانه ردیابی حمل و نقل جاوا اسکریپت یک ارائه دهنده مکان را برای API Fleet Engine Deliveries از پیش تعریف می کند. از شناسه پروژه خود و یک مرجع به کارخانه توکن خود برای نمونه سازی آن استفاده کنید.

جاوا اسکریپت

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

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

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

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

نمای نقشه را اولیه کنید

پس از بارگیری کتابخانه جاوا اسکریپت Journey Sharing، نمای نقشه را مقداردهی اولیه کرده و به صفحه HTML اضافه کنید. صفحه شما باید حاوی یک عنصر <div> باشد که نمای نقشه را نگه می دارد. در مثال زیر، عنصر <div> map_canvas نامگذاری شده است.

برای اجتناب از شرایط مسابقه، شناسه ردیابی را برای ارائه‌دهنده موقعیت مکانی در تماسی که پس از مقداردهی اولیه نقشه فراخوانی می‌شود، تنظیم کنید.

جاوا اسکریپت

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

// If you did not specify a tracking ID in the location
// provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.trackingId = 'your-tracking-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({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);

TypeScript

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

// If you did not specify a tracking ID in the location
// provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.trackingId = 'your-tracking-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({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);

شناسه پیگیری

شناسه ردیابی ارائه‌شده به ارائه‌دهنده موقعیت مکانی ممکن است با چندین کار مطابقت داشته باشد. به عنوان مثال، یک تحویل و یک کار تحویل برای یک بسته، یا چندین تلاش ناموفق برای تحویل. یک کار انتخاب شده است تا در نقشه ردیابی محموله نشان داده شود. وظیفه نمایش داده شده به شرح زیر تعیین می شود:

  1. اگر دقیقاً یک کار پیکاپ باز وجود داشته باشد، نشان داده می شود. در صورت وجود چندین کار بازیابی، خطا ایجاد می شود.
  2. اگر دقیقاً یک وظیفه تحویل باز وجود داشته باشد، نشان داده می شود. اگر چندین وظیفه تحویل باز وجود داشته باشد، خطا ایجاد می شود.
  3. اگر وظایف تحویل بسته وجود دارد:
    • اگر دقیقاً یک وظیفه تحویل بسته وجود داشته باشد، نشان داده می شود.
    • اگر چندین کار تحویل بسته وجود داشته باشد، یکی با آخرین زمان نتیجه نشان داده می شود.
    • اگر چندین کار تحویل بسته وجود داشته باشد که هیچکدام زمان نتیجه ندارند، خطا ایجاد می شود.
  4. اگر وظایف تحویل بسته وجود دارد:
    • اگر دقیقاً یک وظیفه پیکاپ بسته وجود داشته باشد، نشان داده می شود.
    • اگر چندین کار تحویل بسته وجود داشته باشد، یکی با آخرین زمان نتیجه نشان داده می شود.
    • اگر چندین کار پیکاپ بسته وجود داشته باشد که هیچکدام زمان نتیجه ندارند، یک خطا ایجاد می شود.
  5. در غیر این صورت، هیچ وظیفه ای نشان داده نمی شود.

به تغییر رویدادها گوش دهید

شما می توانید متا اطلاعات مربوط به یک کار را از شی اطلاعات ردیابی کار با استفاده از ارائه دهنده مکان بازیابی کنید. اطلاعات متا شامل ETA، تعداد توقف‌های باقی‌مانده و مسافت باقی‌مانده قبل از تحویل یا تحویل است. تغییرات در اطلاعات متا باعث یک رویداد به‌روزرسانی می‌شود. مثال زیر نحوه گوش دادن به این رویدادهای تغییر را نشان می دهد.

جاوا اسکریپت

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

TypeScript

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

رسیدگی به خطاها

خطاهایی که به طور ناهمزمان از درخواست اطلاعات حمل و نقل به وجود می آیند، رویدادهای خطا را ایجاد می کنند. مثال زیر نحوه گوش دادن به این رویدادها را برای رسیدگی به خطاها نشان می دهد.

جاوا اسکریپت

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

توجه: مطمئن شوید که تماس‌های کتابخانه را در بلوک‌های try...catch تا خطاهای پیش‌بینی نشده را مدیریت کنید.

ردیابی را متوقف کنید

برای جلوگیری از ردیابی محموله توسط ارائه دهنده موقعیت مکانی، شناسه ردیابی را از ارائه دهنده موقعیت مکانی حذف کنید.

جاوا اسکریپت

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

ارائه دهنده موقعیت مکانی را از نمای نقشه حذف کنید

مثال زیر نحوه حذف ارائه دهنده موقعیت مکانی را از نمای نقشه نشان می دهد.

جاوا اسکریپت

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

ظاهر و احساس نقشه پایه را سفارشی کنید

برای سفارشی کردن ظاهر و احساس اجزای نقشه، نقشه خود را با استفاده از ابزار مبتنی بر ابر یا با تنظیم گزینه‌ها مستقیماً در کد، استایل دهید .

از طراحی نقشه مبتنی بر ابر استفاده کنید

طراحی نقشه‌های مبتنی بر ابر به شما امکان می‌دهد سبک‌های نقشه را برای هر یک از برنامه‌های خود که از Google Maps از کنسول Google Cloud استفاده می‌کنند ایجاد و ویرایش کنید، بدون اینکه نیازی به تغییر در کد خود داشته باشید. سبک های نقشه به عنوان شناسه نقشه در پروژه Cloud شما ذخیره می شوند. برای اعمال یک سبک در نقشه جاوا اسکریپت ردیابی حمل و نقل، هنگام ایجاد JourneySharingMapView ، یک mapId را مشخص کنید. پس از اینکه JourneySharingMapView نمونه برداری شد، فیلد mapId نمی توان تغییر داد یا اضافه کرد. مثال زیر نشان می دهد که چگونه می توان یک سبک نقشه ایجاد شده قبلی را با شناسه نقشه فعال کرد.

جاوا اسکریپت

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

TypeScript

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

از سبک نقشه مبتنی بر کد استفاده کنید

یکی دیگر از راه‌های سفارشی‌سازی استایل نقشه، تنظیم mapOptions هنگام ایجاد JourneySharingMapView است.

جاوا اسکریپت

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

از سفارشی سازی نشانگرها استفاده کنید

با کتابخانه ردیابی حمل و نقل جاوا اسکریپت، می توانید ظاهر و احساس نشانگرهای اضافه شده به نقشه را سفارشی کنید. شما این کار را با تعیین سفارشی‌سازی نشانگر انجام می‌دهید، که کتابخانه ردیابی حمل و نقل قبل از افزودن نشانگرها به نقشه و با هر به‌روزرسانی نشانگر اعمال می‌شود.

ساده ترین سفارشی سازی این است که یک شی MarkerOptions را مشخص کنید که برای همه نشانگرهای یک نوع اعمال شود. تغییرات مشخص شده در شی بعد از ایجاد هر نشانگر اعمال می شود و هر گزینه پیش فرض را بازنویسی می کند.

یک گزینه پیشرفته تر، تعیین یک تابع سفارشی سازی است. توابع سفارشی سازی امکان استایل نشانگرها را بر اساس داده ها و همچنین افزودن تعامل به نشانگرها، مانند مدیریت کلیک، فراهم می کند. به طور خاص، Shipment Tracking داده‌ها را در مورد نوع شیئی که نشانگر نشان می‌دهد: وسیله نقلیه یا مقصد، به تابع سفارشی‌سازی ارسال می‌کند. سپس این اجازه می دهد تا استایل نشانگر بر اساس وضعیت فعلی خود عنصر نشانگر تغییر کند. به عنوان مثال، تعداد توقف های برنامه ریزی شده باقی مانده تا مقصد. حتی می‌توانید به داده‌های منابع خارج از Fleet Engine ملحق شوید و نشانگر را بر اساس آن اطلاعات استایل دهید.

کتابخانه Shipment Tracking پارامترهای سفارشی سازی زیر را در FleetEngineShipmentLocationProviderOptions ارائه می دهد:

با استفاده از MarkerOptions استایل نشانگرها را تغییر دهید

مثال زیر نحوه پیکربندی استایل نشانگر خودرو را با یک شی MarkerOptions نشان می دهد. این الگو را دنبال کنید تا با استفاده از هر یک از سفارشی سازی نشانگرهای ذکر شده در بالا، استایل هر نشانگر را سفارشی کنید.

جاوا اسکریپت

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

با استفاده از توابع سفارشی‌سازی، استایل نشانگرها را تغییر دهید

مثال زیر نحوه پیکربندی استایل نشانگر خودرو را نشان می دهد. این الگو را دنبال کنید تا با استفاده از هر یک از پارامترهای سفارشی‌سازی نشانگر فهرست شده در بالا، استایل هر نشانگر را سفارشی کنید.

جاوا اسکریپت

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    const stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

کنترل کلیک را به نشانگرها اضافه کنید

مثال زیر نشان می دهد که چگونه می توان کنترل کلیک را به نشانگر خودرو اضافه کرد. این الگو را دنبال کنید تا با استفاده از هر یک از پارامترهای سفارشی‌سازی نشانگر فهرست شده در بالا، مدیریت کلیک را به هر نشانگری اضافه کنید.

جاوا اسکریپت

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

TypeScript

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

از سفارشی سازی های چند خطی استفاده کنید

با کتابخانه ردیابی حمل و نقل، می توانید ظاهر و احساس مسیر محموله را روی نقشه نیز سفارشی کنید. کتابخانه یک شی google.maps.Polyline برای هر جفت مختصات در مسیر فعال یا باقیمانده محموله ایجاد می کند. شما می توانید با تعیین سفارشی سازی چند خط به اشیاء Polyline استایل دهید. سپس کتابخانه این سفارشی‌سازی‌ها را در دو موقعیت اعمال می‌کند: قبل از افزودن اشیاء به نقشه، و زمانی که داده‌های مورد استفاده برای اشیاء تغییر کرده‌اند.

مشابه سفارشی‌سازی نشانگر، می‌توانید مجموعه‌ای از PolylineOptions را تعیین کنید تا روی همه اشیاء Polyline همسان در هنگام ایجاد یا به‌روزرسانی اعمال شوند.

به همین ترتیب، می توانید یک تابع سفارشی سازی را مشخص کنید. توابع سفارشی‌سازی امکان استایل‌سازی فردی اشیاء را بر اساس داده‌های ارسال شده توسط Fleet Engine فراهم می‌کنند. این تابع می تواند سبک هر شی را بر اساس وضعیت فعلی حمل و نقل تغییر دهد. به عنوان مثال، شیء Polyline را با سایه عمیق تر رنگ آمیزی کنید، یا زمانی که وسیله نقلیه کندتر حرکت می کند، آن را ضخیم تر کنید. حتی می‌توانید از منابع خارج از Fleet Engine به آن بپیوندید و شی Polyline را بر اساس آن اطلاعات استایل دهید.

می توانید با استفاده از پارامترهای ارائه شده در FleetEngineShipmentLocationProviderOptions ، سفارشی سازی ها را مشخص کنید. می‌توانید سفارشی‌سازی‌هایی را برای حالت‌های مسیر مختلف در سفر خودرو تنظیم کنید - قبلاً سفر کرده‌اید، فعالانه سفر کرده‌اید یا هنوز سفر نکرده‌اید. پارامترها به شرح زیر است:

با استفاده از PolylineOptions استایل اشیاء Polyline را تغییر دهید

مثال زیر نحوه پیکربندی یک ظاهر طراحی شده برای یک شی Polyline را با PolylineOptions نشان می دهد. این الگو را دنبال کنید تا با استفاده از هر یک از سفارشی‌سازی‌های چند خطی که قبلاً ذکر شد، استایل هر شی Polyline را سفارشی کنید.

جاوا اسکریپت

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

TypeScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

با استفاده از توابع سفارشی سازی، استایل اشیاء Polyline را تغییر دهید

مثال زیر نحوه پیکربندی استایل یک شیء فعال Polyline را نشان می دهد. برای سفارشی کردن استایل هر شیء Polyline با استفاده از هر یک از پارامترهای سفارشی سازی چند خطی که قبلا ذکر شد، از این الگو پیروی کنید.

جاوا اسکریپت

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    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: ShipmentPolylineCustomizationFunctionParams) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    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 آن را تنظیم کنید:

جاوا اسکریپت

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

نمایش یک InfoWindow برای نشانگر وسیله نقلیه یا مکان

می توانید از InfoWindow برای نمایش اطلاعات اضافی در مورد یک وسیله نقلیه یا نشانگر موقعیت استفاده کنید.

مثال زیر نحوه ایجاد InfoWindow و اتصال آن به نشانگر خودرو را نشان می دهد:

جاوا اسکریپت

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', e => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

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

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

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

اتصالات خودکار را غیرفعال کنید

با غیرفعال کردن نصب خودکار، می‌توانید نقشه را از نصب خودکار نمای درگاه روی خودرو و مسیر پیش‌بینی‌شده متوقف کنید. مثال زیر نحوه غیرفعال کردن اتصال خودکار را هنگام پیکربندی نمای نقشه اشتراک گذاری سفر نشان می دهد.

جاوا اسکریپت

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

TypeScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

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

یک نقشه موجود را جایگزین کنید

می‌توانید از کتابخانه ردیابی حمل‌ونقل جاوا اسکریپت برای جایگزینی نقشه‌های موجود که شامل نشانگرها یا سفارشی‌سازی‌های دیگر است، بدون از دست دادن آن سفارشی‌سازی‌ها استفاده کنید.

برای مثال، فرض کنید یک صفحه وب با یک موجودیت استاندارد 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 Uluru
  var uluru = {lat: -25.344, lng: 131.036};
  // 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 Uluru
  var marker = new google.maps.Marker({position: uluru, 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>

برای افزودن کتابخانه جاوا اسکریپت Journey Sharing:

  1. کدی را برای کارخانه توکن احراز هویت اضافه کنید.
  2. یک ارائه دهنده مکان را در تابع initMap() راه اندازی کنید.
  3. نمای نقشه را در تابع initMap() راه اندازی کنید. نمای شامل نقشه است.
  4. سفارشی سازی خود را به تابع callback برای مقداردهی اولیه نمای نقشه منتقل کنید.
  5. کتابخانه مکان را به بارگذار 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
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.FleetEngineShipmentLocationProvider({
    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.trackingId = TRACKING_ID;

    // (4) Add customizations like before.

    // The location of Uluru
    var uluru = {lat: -25.344, lng: 131.036};
    // 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 Uluru
    var marker = new google.maps.Marker({position: uluru, 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.
    -->
    <script defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
    </script>
  </body>
</html>

اگر بسته ردیابی شده با شناسه مشخص شده در نزدیکی Uluru دارید، اکنون روی نقشه ارائه می شود.