設定 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」。

設定授權

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

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 尚未在重新載入的網頁上呼叫擷取器，或是擷取器尚未傳回權杖。

  • 權杖已過期。

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

否則，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,
  };
}

後續步驟