典型的な API フロー

次の図は、クラスの挿入、オブジェクトの保存、オブジェクトの更新で行われる一般的な通信フローを示しています。サーバー、ウェブブラウザ、Google Pay API for Passes 間のアクションはすべてご自身で実装する必要があります。以下の説明ではポイントカードを例にしていますが、他のパスでも類似したフローになります。

図 1. API フロー図。

JS ボタンと JWT ウェブリンクの典型的な API フロー

以下の概要では、図 1 と同じプロセスについて詳しく説明します。ここでは、JavaScript（JS）ボタンと JSON Web Token（JWT）の一般的な API フローについて説明します。

  1. ポイントカード発行者が LoyaltyClass を作成します。
    1. 使用するサーバーで LoyaltyClass を定義します。
    2. 使用するサーバーで POST リクエストを作成し、LoyaltyClass を Google Pay API for Passes サーバーに挿入します。
  2. サーバーには、特定の LoyaltyClass について、LoyaltyObject の JWT を生成するためのサービスが備わっています。このオブジェクトが、ユーザーのポイントカードを表します。
    1. サーバーにより、JWT を使用して [Google Pay に保存]（S2GP）ボタンが表示されます。
      • ウェブサイトの場合は、JavaScript ボタンを使用します。
      • メール、SMS、アプリの場合は、S2GP ボタンのある JWT リンクを使用します。
  3. ユーザーが、ポイントカード発行者のウェブサイト、メール、アプリ、SMS で、[Google Pay に保存] をクリックするかタップします。
    1. ユーザーはランディング ページに移動して LoyaltyClass オブジェクトを保存します。保存されるオブジェクトは、JWT に基づいてランディング ページに表示されます。ボタンがアプリからタップされた場合、ユーザーはオブジェクトを Google Pay アプリに保存するよう求められます。
    2. ユーザーが発行者のプロパティで [Google Pay に保存] をクリックし、LoyaltyObject を保存します。
    3. LoyaltyObject が Google サーバーに挿入され、Google Pay アプリに push されます。LoyaltyObject がポイントパスとして参照されます。
  4. カード発行者がカードデータを更新します。
    1. ポイントカード発行者が Object.id を使用して LoyaltyObject の GET リクエストを発行します。
    2. ポイントカード発行者が LoyaltyObject を更新します。
    3. ポイントカード発行者が PUT または PATCH リクエストを作成し、更新した LoyaltyObject を Google Pay API for Passes サーバーに挿入します。
    4. LoyaltyObject が Google Pay アプリに push されます。

スリムな JWT

ブラウザによる切り捨てのため、ウェブリンクで使用する JWT は 1,800 文字以下にする必要があります。この制限内に収めるのが難しい場合は、クラスとオブジェクトの両方を事前に挿入するのが最善の方法です。この場合、JWT にはオブジェクト ID フィールドを含めるだけですみます。

次の図に、メールまたは SMS に [Google Pay に保存] ボタンを追加する場合の API フローを示します。

図 2. スリムな JWT の図。

JWT POST リクエストの API フロー

オブジェクトを保存する前にクラスの作成と挿入に必要なバックエンド作業を実装するのが難しいことも少なくありません。JWT は、1,800 文字の制限を超える可能性がありますが、イベント チケットや搭乗券など、時間とともに多くのクラスが作成されるパスを扱う場合はとても便利な方法です。

たとえば、フライトクラスのフローは次のようになります。

  1. サーバーは、FlightObject と FlightClass の両方の JWT を生成します。どちらも JSON で定義され、FlightObject が FlightClass を参照しています。
  2. この JWT がサーバーからクライアント アプリケーションに送信され、クライアント アプリケーションに [Google Pay に保存] ボタンが表示されます。S2GP ブランド ガイドラインに遵守しているボタンを使用してください。
  3. ユーザーがクライアント アプリケーションで S2GP ボタンをクリックします。
    1. JWT エンドポイントに POST リクエストが送信されます。これにより、クラス ID とオブジェクト ID が挿入されます。JWT のクラス ID またはオブジェクト ID がシステムにすでに存在する場合、これらの ID が再度挿入されることはありません。既存のクラスとオブジェクトを更新する方法については、API リファレンスのドキュメントをご覧ください。すでに挿入されている場合、エラーは発生しません。
    2. ユーザーがパスを保存できるように、レスポンスで返された URI がユーザーに提供されます。この URI は、返された時点から 1 週間有効です。

API を実装するには、JWT POST リクエスト メソッドを使用するをご覧ください。

図 3. JWT POST リクエストの図。

図 3 では、保存フローの Your server と Google server の間に矢印はありません。これは、JWT リンクやインテント メソッドと JWT POST の基本的な違いです。ただし、パスを更新するにはサーバー間通信を実装することをおすすめします。