Ikuti pengiriman

Setelah menyiapkan JavaScript Consumer SDK untuk tugas terjadwal, Anda siap melacak pengiriman dengan aplikasi konsumen. Dokumen ini membahas langkah-langkah utama berikut dalam proses ini:

  • Melakukan inisialisasi peta dan menampilkan perjalanan bersama
  • Memperbarui dan mengikuti progres perjalanan
  • Berhenti mengikuti pengiriman
  • Menangani error pelacakan pengiriman

Menyiapkan peta

Untuk melacak pengambilan atau pengiriman paket di aplikasi web, Anda perlu memuat peta dan membuat instance Consumer SDK untuk mulai melacak paket. Anda dapat memuat peta baru atau menggunakan peta yang sudah ada. Kemudian, Anda menggunakan fungsi inisialisasi untuk membuat instance Consumer SDK sehingga tampilan peta sesuai dengan lokasi item yang dilacak.

Memuat peta baru menggunakan Google Maps JavaScript API

Untuk membuat peta baru, muat Google Maps JavaScript API di aplikasi web Anda. Contoh berikut menunjukkan cara memuat Google Maps JavaScript API, mengaktifkan SDK, dan memicu pemeriksaan inisialisasi.

  • Parameter callback menjalankan fungsi initMap setelah API dimuat.
  • Atribut defer memungkinkan browser terus merender bagian halaman Anda yang lain saat API dimuat.

Gunakan fungsi initMap untuk membuat instance Consumer SDK. Contoh:

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

Memuat peta yang ada

Anda juga dapat memuat peta yang ada yang dibuat oleh Google Maps JavaScript API, seperti peta yang sudah Anda gunakan.

Misalnya, Anda memiliki halaman web dengan entitas google.maps.Map standar yang menampilkan penanda seperti yang ditentukan dalam kode HTML berikut. Tindakan ini akan menampilkan peta Anda menggunakan fungsi initMap yang sama dalam callback di bagian akhir:

    <!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>

Membuat instance penyedia lokasi pengiriman

Gunakan penyedia lokasi pengiriman, bersama dengan pengambil token otorisasi yang Anda tentukan sebelumnya, untuk mulai menerima data dari Fleet Engine.

Contoh ini menunjukkan cara membuat instance penyedia lokasi.

JavaScript

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

TypeScript

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

Menampilkan perjalanan bersama

Untuk menampilkan progres tugas terjadwal, lakukan inisialisasi tampilannya, yang menetapkan bingkai untuk peta agar sesuai dengan lokasi untuk perjalanan yang dilacak. Progres kemudian diberikan oleh Consumer SDK setelah mendapatkan informasi dari Fleet Engine.

Tips:

  1. Pastikan halaman Anda berisi elemen <div> yang menyimpan tampilan peta. Dalam contoh berikut, elemen <div> diberi nama map_canvas.

  2. Perhatikan aturan visibilitas default yang diterapkan Fleet Engine ke perjalanan yang dilacak. Anda juga dapat mengonfigurasi aturan visibilitas untuk pengiriman kendaraan aktif dan tugas perhentian terjadwal. Lihat Menyesuaikan visibilitas tugas dalam panduan Mengonfigurasi tugas.

Contoh ini menunjukkan cara menginisialisasi tampilan peta.

JavaScript

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
    // Any undefined styling options use defaults.
  });

  // If you did not specify a tracking ID in the location
  // provider constructor, you may do so here.
  // Location tracking starts 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

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
   // 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 starts 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);
}

Memperbarui progres pengiriman

Anda dapat memproses peristiwa dan memperbarui progres pengiriman seiring perjalanan berlangsung. Gunakan penyedia lokasi untuk mengambil informasi meta dari objek taskTrackingInfo. Perubahan pada informasi meta akan memicu peristiwa update. Objek taskTrackingInfo menyediakan hal berikut:

  • PWT
  • Jumlah perhentian yang tersisa
  • Jarak yang tersisa sebelum pengambilan atau pengiriman

Contoh berikut menunjukkan cara memproses peristiwa perubahan ini.

JavaScript

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

Menampilkan kriteria untuk beberapa tugas

Consumer SDK untuk tugas terjadwal hanya menampilkan satu tugas per ID pelacakan di peta. Namun, Anda juga biasanya menetapkan satu ID pelacakan ke barang pengiriman tertentu yang tetap terkait dengan barang tersebut selama perjalanannya di sistem Anda. Artinya, satu ID pelacakan dapat dikaitkan dengan beberapa tugas, seperti tugas pengambilan yang diikuti dengan tugas pengiriman untuk paket yang sama, atau beberapa tugas pengiriman yang gagal untuk sebuah paket.

Untuk menangani situasi ini, Fleet Engine menerapkan kriteria untuk menampilkan tugas, yang ditunjukkan dalam tabel berikut.

Kriteria tugas Hasil
Membuka tugas pengambilan
Hanya ada satu Menampilkan tugas
Ada beberapa Menghasilkan error
Tugas pengambilan yang ditutup
Hanya ada satu Menampilkan tugas
Ada beberapa (beberapa dengan waktu hasil) Menampilkan tugas dengan waktu hasil terbaru
Ada beberapa (tidak ada yang memiliki waktu hasil) Menghasilkan error
Membuka tugas pengiriman
Hanya ada satu Menampilkan tugas
Ada beberapa Menghasilkan error
Tugas pengiriman yang ditutup
Hanya ada satu Menampilkan tugas
Ada beberapa (beberapa dengan waktu hasil) Menampilkan tugas dengan waktu hasil terbaru
Ada beberapa (tidak ada yang memiliki waktu hasil) Menghasilkan error

Berhenti mengikuti pengiriman

Saat perjalanan pengiriman selesai atau dibatalkan, aplikasi konsumen Anda harus berhenti mengikuti pengiriman dengan menghapus ID pelacakan dan penyedia lokasi dari tampilan peta. Untuk mengetahui detailnya, lihat bagian berikut.

Menghapus ID pelacakan

Untuk menghentikan penyedia lokasi melacak pengiriman, hapus ID pelacakan dari penyedia lokasi. Contoh berikut menunjukkan cara melakukannya.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Menghapus penyedia lokasi dari tampilan peta

Contoh berikut menunjukkan cara menghapus penyedia lokasi dari tampilan peta.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Menangani error pelacakan pengiriman

Error yang muncul secara asinkron dari permintaan informasi pengiriman memicu peristiwa error. Contoh berikut menunjukkan cara memproses peristiwa ini untuk menangani error.

JavaScript

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

Catatan: Pastikan untuk menggabungkan panggilan library dalam blok try...catch untuk menangani error yang tidak terduga.

Langkah berikutnya