追蹤出貨情況

為排定的工作設定 JavaScript Consumer SDK 後, 準備好追蹤消費者應用程式的出貨資訊。本文件將介紹 以下是這項程序的關鍵步驟:

  • 初始化地圖並顯示分享的旅程
  • 更新並追蹤歷程進度
  • 停止分享旅程
  • 處理錯誤

設定地圖

如要在網頁應用程式中追蹤取貨或取貨地點,請載入地圖 並例項化 Consumer SDK 以開始追蹤商品運送情形。您可以載入 建立新的地圖或使用現有地圖接著使用初始化 函式,將 Consumer SDK 執行個體化,讓地圖檢視與 所追蹤項目的位置。

使用 Google Maps JavaScript API 載入新地圖

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

  • callback 參數會在 API 載入後執行 initMap 函式。
  • defer 屬性可讓瀏覽器繼續轉譯其餘內容的 頁面。

使用 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 擷取的流程 機群引擎

提示

  1. 確認您的網頁包含包含地圖檢視的 &lt;div&gt; 元素。 在以下範例中,<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 物件。變更中繼 資訊就會觸發 update 事件。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 區塊中包裝程式庫呼叫,以便處理意外錯誤。

後續步驟