JavaScript Consumer SDK をセットアップする

JavaScript Consumer SDK を使用すると、消費者向けアプリで、Fleet Engine で追跡された車両の位置情報やその他の関心対象地域をウェブベースの地図上に表示できます。これにより、一般ユーザーは配送状況を確認できます。このガイドでは、関連付けられた Google Cloud プロジェクトと API キーを使用して Fleet Engine を設定済みであることを前提としています。詳しくは、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 データを使用した認可には、サーバーサイドとクライアントサイドの両方の実装が必要です。

サーバーサイドの認可

ウェブベースのアプリケーションで認証と認可を設定する前に、バックエンド サーバーが Fleet Engine にアクセスするためにウェブベースのアプリケーションに JSON ウェブトークンを発行できる必要があります。ウェブベースのアプリケーションは、リクエストとともにこれらの JWT を送信します。これにより、Fleet Engine はリクエストが認証済みであり、リクエスト内のデータにアクセスする権限があることを認識します。サーバーサイドの JWT 実装の手順については、Fleet Engine の基本の JSON ウェブトークンを発行するをご覧ください。

特に、荷物の追跡用の JavaScript Consumer SDK については、次の点に注意してください。

クライアントサイドの認可

JavaScript Consumer SDK を使用すると、認証トークン フェッチャーを使用してサーバーからトークンがリクエストされます。これは、次のいずれかに該当する場合に実行されます。

  • 有効なトークンが存在しない場合（SDK が新しいページの読み込みでフェッチャーを呼び出していない場合や、フェッチャーがトークンを返していない場合など）。

  • トークンの有効期限が切れています。

  • トークンの有効期限が 1 分以内である。

それ以外の場合、JavaScript Consumer SDK は以前に発行された有効なトークンを使用し、フェッチャーを呼び出しません。

認証トークン フェッチャーを作成する

次のガイドラインに沿って、認可トークン フェッチャーを作成します。

  • フェッチャーは、次の例のように Promise でラップされた 2 つのフィールドを含むデータ構造を返す必要があります。

    • 文字列 token。

    • 数値 expiresInSeconds。トークンは、取得後この時間で期限切れになります。認証トークン フェッチャーは、例に示すように、取得時からライブラリまでの有効期限を秒単位で渡す必要があります。

  • フェッチャーはサーバー上の URL を呼び出してトークンを取得する必要があります。この URL（SERVER_TOKEN_URL）は、バックエンドの実装によって異なります。次の 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,
  };
}

次のステップ