追蹤出貨情況

您已為排定工作設定 JavaScript Consumer SDK，現在可以透過消費者應用程式追蹤貨運。本文將說明這項程序中的下列重要步驟：

  • 初始化地圖並顯示共用行程
  • 更新並追蹤旅程進度
  • 停止追蹤貨件
  • 處理貨運追蹤錯誤

設定地圖

如要在網頁應用程式中追蹤取貨或送貨進度，您必須載入地圖並例項化 Consumer SDK，才能開始追蹤貨件。您可以載入新地圖，也可以使用現有地圖。接著，您可以使用初始化函式例項化 Consumer SDK，讓地圖檢視畫面與追蹤項目的位置相符。

使用 Google Maps JavaScript API 載入新地圖

如要建立新地圖，請在網頁應用程式中載入 Google Maps JavaScript API。下列範例說明如何載入 Google Maps JavaScript API、啟用 SDK，以及觸發初始化檢查。

  • API 載入後，callback 參數會執行 initMap 函式。
  • 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>

建立貨運位置資訊供應商的例項

使用貨運位置資訊提供者和先前定義的授權權杖擷取器，開始從 Fleet Engine 接收資料。

以下範例說明如何例項化位置資訊供應器。

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

顯示共用行程

如要顯示排定工作的進度，請初始化其檢視畫面，這會設定地圖的影格，對應追蹤行程的位置。Consumer SDK 從 Fleet Engine 取得資訊後，就會提供進度。

提示：

  1. 確認網頁包含用於保存地圖檢視區塊的 <div> 元素。在以下範例中，<div> 元素名為 map_canvas。

  2. 請注意 Fleet Engine 對追蹤行程套用的預設可見度規則。您也可以為有效車輛出貨和排定停靠點工作設定瀏覽權限規則。請參閱「設定工作」指南中的「自訂工作顯示設定」。

這些範例說明如何初始化地圖檢視區塊。

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

更新出貨進度

您可以監聽事件，並在運送過程更新貨運進度。使用位置資訊供應器從 taskTrackingInfo 物件擷取中繼資訊。中繼資訊變更會觸發更新事件。taskTrackingInfo 物件提供下列項目：

  • 預計抵達時間
  • 剩餘停靠站數量
  • 取貨或送達前的剩餘距離

以下範例說明如何監聽這些變更事件。

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

顯示多項工作的評分標準

排定工作專用的 Consumer SDK 只會在每個追蹤 ID 的地圖上顯示一項工作。不過，您通常也會為特定出貨商品指派一個追蹤 ID，該 ID 會在商品於系統中運送的整個過程中與商品建立關聯。也就是說，單一追蹤 ID 可能會與多項工作相關聯，例如同一件包裹的取貨工作和運送工作，或是包裹的多項運送失敗工作。

為處理這種情況，Fleet Engine 會套用顯示工作的條件，如下表所示。

任務條件 結果
開啟取貨工作
恰好存在一個 顯示工作
存在多個 產生錯誤
已完成的取貨工作
恰好存在一個 顯示工作
有多個存在 (部分有結果時間) 顯示結果時間最近的任務
存在多個 (沒有任何結果時間) 產生錯誤
開啟送貨工作
恰好存在一個 顯示工作
存在多個 產生錯誤
已完成的送貨工作
恰好存在一個 顯示工作
有多個存在 (部分有結果時間) 顯示結果時間最近的任務
存在多個 (沒有任何結果時間) 產生錯誤

停止追蹤貨件

當運送過程完成或取消時，消費者應用程式應停止追蹤貨件，並從地圖檢視畫面中移除追蹤 ID 和位置資訊提供者。詳情請參閱以下各節說明。

移除追蹤 ID

如要停止追蹤貨件，請從位置資訊供應商移除追蹤 ID。以下範例說明如何執行這項操作。

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

從地圖檢視畫面中移除位置資訊供應器

以下範例說明如何從地圖檢視畫面中移除位置資訊供應器。

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

處理貨運追蹤錯誤

要求運送資訊時，如果發生非同步錯誤，系統會觸發 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);
});

注意：請務必將程式庫呼叫包裝在 try...catch 區塊中，以處理非預期的錯誤。

後續步驟