ユースケース

次のいずれかのパスカテゴリを選択して、使用方法の詳細をご覧ください。

Google Pay API for Passes を使用すると、バス、フェリー、鉄道などの交通機関のパスでユーザーにアピールできます。このガイドで説明するコンセプトを学習することで、交通機関のパスの機能をより深く理解できます。

交通機関のパスを実装するには、JWT POST リクエスト メソッドを使用します。または、クラスとオブジェクトを事前に挿入するスリムな JWT リンクを使用します。

TransitClasses と TransitObjects

Google Pay API for Passes の他のカテゴリと同様に、乗車券のデータは TransitClass と TransitObject の 2 つのデータ構造に格納されます。このガイドでは、乗車券をサポートするように、これらのデータ構造を使用する方法について説明します。

TransitClass

TransitClass は、クラスに関連付けられたすべてのオブジェクトを表示するために使用されるテンプレートを定義します。テンプレートは、パスのさまざまなセクションに表示するフィールドを定義します。また、オブジェクト間で共有されるロゴと発行者名も定義します。

2 種類のパスがあり、パスの 1 つ以上のセクションにそれぞれ異なるデータを表示する必要がある場合は、2 つの独立した TransitClasses を作成することをおすすめします。たとえば、1 回のみ使用できる 2 地点間のパスに使用する TransitClass と、シーズンパスに使用する別の TransitClass を作成できます。

TransitObject

TransitObject は、乗車、交通機関、乗客を表すすべてのデータを保持します。たとえば、TransitObject には、出発地、目的地、出発時刻、交通機関番号、乗客名、座席番号などが含まれます。このような値の一部は、複数の TransitObjects. で共有されます。

TransitObject に含まれるリソースは、ユーザーの Google Pay アプリに保存されます。

サポートされている国

Google Pay アプリがサポートされている国を確認するには、利用できる国のリストをご覧ください。ユーザーがチケットを購入した国や地域に基づいて、[Google Pay に保存] ボタンの表示を制限することをおすすめします。

ユースケース

以下では、交通機関のパスカテゴリでのみ利用可能なユースケースについて説明します。

パスを更新する

パスの作成後に変更が発生した場合は、REST API を使用して変更をお客様に配信できます。変更がクラスにのみ影響する場合は、Google Pay Merchant Center を使用することもできます。パスの更新は、お客様とのやり取りで重要な処理の 1 つです。

ロゴが変更された場合など、パスの表示方法を更新するには、TransitClass を update または patch するか、Google Pay Merchant Center を使用するだけで対処できます。この情報は、更新された TransitClass に関連付けられているすべての TransitObject に渡されます。これは、TransitClass レベルで定義されているすべてのフィールドに当てはまります。

出発時刻が変更された場合などに単一のパスを更新するには、単一の TransitObject に対して update または patch を実行する必要があります。これは、TransitObject レベルで定義されているすべてのフィールドに当てはまります。

場合によっては、いつ変更が発生するか、あるいは update または patch リクエストをいつトリガーすればよいかわからないことがあります。そのような場合は、すべてのクラスとオブジェクトそれぞれに対して、update または patch リクエストを定期的にスケジュールします。TransitClass list メソッドを呼び出すと、特定の発行者アカウントのすべてのクラスを確認できます。また、TransitObject list メソッドを呼び出すと、特定のクラスのすべてのオブジェクトを確認できます。

複数区間の乗車を定義する

交通機関を利用する場合、目的地に直行するのではなく、複数の場所を経由することは少なくありません。そのような移動のために、交通事業者は乗車区間ごとにパスを 1 つずつ発行する場合もあれば、1 つのパスにまとめる場合もあります。Google Pay API for Passes でも同様です。区間ごとに 1 つの TransitObject で表す場合もあれば、複数の区間を 1 つの TransitObject で表す場合もあります。

区間ごとに 1 つの TransitObject を使用する方法は非常にシンプルです。object.ticketLeg を使用して区間を定義できます。各パスが独立している場合は、それぞれを作成または更新できます。ただし、これらのパスをグループ化する方法を定義した方がよい場合もあります。詳しくは、複数の乗車券をグループ化するをご覧ください。複数区間の乗車を定義する場合は、この方法をおすすめします。

複数区間の TransitObject オブジェクトは、このタイプの集約パスがすべての区間で認められており、QR コードなどのパスの情報がすべての区間で同じである場合に限って使用する必要があります。区間を定義するには object.ticketLegs[] リストを使用します。パスのカード部分には、最初の区間の出発地と最後の区間の目的値のみが表示されます。パスの詳細セクションには移動経路全体が表示されます。

複数のパスを保存するボタンを作成する

ユーザーが複数のパスを購入し、これらのパスを Google Pay に保存する可能性が高い場合、[Google Pay に保存] ボタンまたはリンクを 1 回クリックするだけで複数のオブジェクトを保存できるようにすると便利です。JSON Web Token（JWT）に署名するときに、複数のオブジェクトまたはクラスを定義できます。

次のいずれかの形式で JWT を作成する必要があります。

  • 事前に挿入されたクラスとオブジェクトのみ。
  • JWT 内で完全に定義されているオブジェクトとクラスのリソースのみ。

パスの UI 表現の詳細については、複数の乗車券をグループ化するをご覧ください。

複数の乗車券をグループ化する

グループで使用した場合と個々のオブジェクトで使用した場合で動作が異なる機能があります。たとえば、ユーザー インターフェースで保存された多くのパスを整理する場合やステータスを通知する場合は機能の動作が異なることがあります。

複数の TransitObject オブジェクトがグループとみなされるのは、これらのオブジェクトで object.classId, object.ticketLeg.departureDateTime が同一であり、かつ以下のプロパティのいずれかが同一である場合です（以下のプロパティは優先度順に示されています）。

  1. object.tripId
  2. object.purchaseDetails.confirmationCode

これは、乗車が同じで乗客が異なる複数のパスをグループ化することを意図したものです。

パスをグループ化する場合は、これらのフィールドを一貫した方法で設定することをおすすめします。これは、特定の TransitObject が他のオブジェクトとグループ化されない場合であっても同様です。

間近の乗車通知を受け取る

Google Pay から、乗車の 1 時間前にユーザーに通知が送信されます。乗車時刻は、object.ticketLeg.departureDateTime または最初の object.ticketLegs[].departureDateTime によって定義されます。

この通知を受け取るには、通知を有効にする必要があります。これを確認するには、[設定] > [通知] の順に移動し、[パスに関する最新情報] がオンになっているかを確認します。

通知は通知エリアに表示されます。ロック画面の通知を有効にした場合は、ロック画面にも表示されます。

通知は以下のような形式になっています。この形式は変更できません。

Ticket fot your upcoming trip to object.ticketLeg.destinationName
Expand for more options

通知をタップしてデバイスのロックを解除すると、Google Pay アプリにパスが表示されます。

複数のパスがある場合は、一番早く利用できるパスが 1 つだけ表示されます。複数の乗車券をグループ化して保存している場合、グループ内の 1 つのパスの通知のみが表示されます。このパスをタップして、左右にスワイプすると、グループ内の他のパスを表示できます。

通知は固定され、ユーザーが開いても自動的には閉じません。object.ticketLeg.departureDateTime または最初の object.ticketLegs[].departureDateTime から 60 分経過すると、通知は自動的に閉じます。

期限切れのパスを処理する

Google Pay アプリの [パス] タブの下に、アーカイブされたパスや無効なパスがすべて含まれた [期限切れのパス] セクションがあります。次の条件の少なくとも 1 つに該当する場合、乗車券は [期限切れのパス] セクションに移動されます。

  • object.ticketLeg.arrivalDateTime または最後の object.ticketLegs[].arrivalDateTime が期限切れになってから 24 時間以上経過している。このパスは、object.ticketLeg.arrivalDateTime または最後の object.ticketLegs[].arrivalDateTime が期限切れになってから 24～48 時間以内に [期限切れのパス] に移動されます。
  • object.validTimeInterval.end.date が期限切れになっている。このパスは、object.validTimeInterval.end.date を過ぎてから 24 時間以内に [期限切れのパス] に移動されます。
  • object.state フィールドが Expired、Inactive、または Completed としてマークされている。

ユーザーがパスを保存したら、その objectId を参照してパスにリンクできます。

次のリンクを使用してパスを参照します。

https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}

対象のパスは、Google Pay アプリまたはウェブブラウザで表示できます。

保存した Google Pay パスのヘッダーの下で、アプリまたはウェブサイトにリンクできます。この機能は、すべての種類の Google Pay パスでご利用いただけます。

アクセスをリクエストする

店舗販売者向けのサポート フォームを使用して、アクセスをリクエストします。次の点にご注意ください。

  • フォームでは発行者 ID を共有する必要があります。
  • [Issue type] で、[Technical/API Integration] を選択します。
  • [Link your app or website below the Google Pay pass] を選択します。

特定の Google Pay パスに対して、appLinkData を定義してアプリまたはウェブサイトの URI を設定します。URI には任意の形式を使用できますが、ダイナミック リンクを使用することをおすすめします。

appLinkData フィールドの形式とコンテキストは、次のソースコードで確認できます。

{
  "id": string,
  "classId": string,
  …
  …
  …
  "appLinkData": {
    "androidAppLinkInfo": {
      "appLogoImage": {
        "sourceUri": {
          "uri": string
        }
      },
        "title": {
          "defaultValue": {
            "language": string,
              "value": string
          }
        },
          "description": {
            "defaultValue": {
              "language": string,
                "value": string
            }
          },
            "appTarget": {
              "targetUri": {
                "uri": string,
                  "description": string
              }
            }
    }
  }
  …
  …
  …
}