設定 JavaScript Consumer SDK

有了 JavaScript Consumer SDK，消費者應用程式就能在網頁式地圖上，顯示車輛位置和 Fleet Engine 追蹤的其他興趣點。這樣一來，消費者就能查看運送進度。本指南假設您已設定 Fleet Engine，以及相關聯的 Google Cloud 專案和 API 金鑰。詳情請參閱「Fleet Engine」。

請按照下列步驟設定 JavaScript Consumer SDK：

  1. 啟用 Maps JavaScript API。
  2. 設定授權。

啟用 Maps JavaScript API

在用於 Fleet Engine 執行個體的 Google Cloud 控制台專案中，啟用 Maps JavaScript API。詳情請參閱 Maps JavaScript API 說明文件中的「啟用 API」。

設定授權

Fleet Engine 規定，從低信任環境 (智慧型手機和瀏覽器) 呼叫 API 方法時，必須使用 JSON Web Token (JWT)。

JWT 源自伺服器，經過簽署和加密，並傳遞至用戶端，用於後續的伺服器互動，直到過期或失效為止。

重要詳細資料

消費者應用程式應使用 Google Cloud 雲端專案中的 delivery_consumer 角色驗證使用者，只傳回消費者專屬資訊。這樣一來，Fleet Engine 就會篩選並遮蓋回應中的所有其他資訊。舉例來說，在無法提供服務的工作期間，系統不會與使用者分享位置資訊。請參閱排定工作的服務帳戶角色。

授權的運作方式

Fleet Engine 資料授權涉及伺服器端和用戶端實作。

伺服器端授權

在網頁式應用程式中設定驗證和授權機制前，後端伺服器必須能向網頁式應用程式核發 JSON Web Token，以便存取 Fleet Engine。網頁式應用程式會隨要求傳送這些 JWT，讓 Fleet Engine 辨識要求已通過驗證和授權，可存取要求中的資料。如需伺服器端 JWT 實作操作說明，請參閱「Fleet Engine 基本概念」中的「核發 JSON Web Token」。

具體來說，使用 JavaScript Consumer SDK 追蹤運送作業時，請注意下列事項：

用戶端授權

使用 JavaScript Consumer SDK 時，SDK 會透過授權權杖擷取器向伺服器要求權杖。如果符合下列任一條件，就會發生這種情況：

  • 沒有有效的權杖，例如 SDK 尚未在重新載入網頁時呼叫擷取器，或擷取器尚未傳回權杖。

  • 權杖已過期。

  • 權杖將在一分鐘內過期。

否則，JavaScript Consumer SDK 會使用先前核發的有效權杖，不會呼叫擷取器。

建立授權權杖擷取器

請按照下列規範建立授權權杖擷取工具：

  • 擷取器必須傳回包含兩個欄位的資料結構，並包裝在 Promise 中，如下所示：

    • 字串 token。

    • 數字 expiresInSeconds。權杖會在擷取後這段時間內失效。驗證權杖擷取器必須將到期時間 (以秒為單位) 傳遞至程式庫，如範例所示。

  • 擷取器應呼叫伺服器上的網址來擷取權杖。這個網址 (SERVER_TOKEN_URL) 取決於後端實作方式。以下範例網址適用於 GitHub 上的範例應用程式後端：

    • https://SERVER_URL/token/delivery_consumer/TRACKING_ID

範例：建立驗證權杖擷取器

以下範例說明如何建立授權權杖擷取器：

JavaScript

async 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.ExpiresInSeconds,
  };
}

後續步驟