设置 JavaScript Consumer SDK

借助 JavaScript 消费者 SDK，您的消费者应用可以在基于 Web 的地图上显示车辆位置以及 Fleet Engine 中跟踪的其他感兴趣的位置。这样，您的消费者用户就可以查看其配送进度。 本指南假定您已设置 Fleet Engine 及其关联的 Google Cloud 项目和 API 密钥。如需了解详情，请参阅 Fleet Engine。

您可以通过以下步骤设置 JavaScript 消费者 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 令牌 (JWT)。

JWT 源自您的服务器，经过签名和加密，并传递给客户端以进行后续服务器交互，直到它过期或不再有效。

重要详细信息

您的消费者应用应使用 Google Cloud 项目中的 delivery_consumer 角色对最终用户进行身份验证，以便仅返回消费者特定信息。这样，Fleet Engine 就会过滤并隐去响应中的所有其他信息。例如，在不可用任务期间，系统不会与最终用户分享任何位置信息。请参阅服务账号角色，了解计划任务。

授权的工作原理是什么？

使用 Fleet Engine 数据进行授权涉及服务器端和客户端实现。

服务器端授权

在基于 Web 的应用中设置身份验证和授权之前，您的后端服务器必须能够向基于 Web 的应用颁发 JSON Web 令牌，以便访问 Fleet Engine。您的基于 Web 的应用会随请求发送这些 JWT，以便 Fleet Engine 将请求识别为经过身份验证并获得授权，可以访问请求中的数据。如需了解服务器端 JWT 实现，请参阅 Fleet Engine 基础知识下的签发 JSON Web 令牌。

具体而言，请注意以下有关用于跟踪配送的 JavaScript 消费者 SDK 的事项：

客户端授权

当您使用 JavaScript Consumer SDK 时，它会使用授权令牌提取器向服务器请求令牌。当满足以下任一条件时，系统会执行此操作：

  • 不存在有效令牌，例如 SDK 尚未在全新网页加载时调用提取器，或者提取器尚未返回令牌。

  • 令牌已过期。

  • 令牌将在 1 分钟内过期。

否则，JavaScript 消费端 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,
  };
}

后续步骤