本頁面由 Cloud Translation API 翻譯而成。

追蹤出貨情況

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

初始化地圖並顯示共用路線
更新及追蹤歷程進度
停止追蹤運送作業
處理運送追蹤錯誤

設定地圖

如要在網頁應用程式中追蹤貨物提貨或送達情況，您必須載入地圖並將 Consumer SDK 例項化，才能開始追蹤貨物。您可以載入新地圖或使用現有地圖。接著，您可以使用初始化函式將 Consumer SDK 例項化，讓地圖檢視畫面對應至所追蹤項目的位置。

使用 Google Maps JavaScript API 載入新地圖

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

callback 參數會在 API 載入後執行 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 的資訊後提供進度。

提示：

請確認您的網頁包含可容納地圖檢視畫面的 <div> 元素。在以下範例中，<div> 元素的名稱為 map_canvas。
請注意，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 可能會與多個工作相關聯，例如同一個包裹的提貨工作和後續的配送工作，或是多個失敗的包裹運送工作。

為處理這種情況，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 區塊中包裝程式庫呼叫，以便處理意外錯誤。

後續步驟

設定地圖樣式