ユースケース

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


Google Pay API for Passes を使用すると、イベント チケットでユーザーにアピールできます。このガイドで説明するコンセプトは、保存されたイベント チケットの機能をより深く理解するために役立ちます。

イベント チケットを実装するには、JWT POST リクエスト メソッドを使用します。または、クラスとオブジェクトを事前に挿入するスリムな JWT リンクを使用します。

以下では、イベント チケット カテゴリでのみ使用できるユースケースを説明します。

パスを更新する

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

会場所在地が変更された場合など、特定のイベントに関するすべてのイベント チケットのフィールドを更新するには、EventTicketClassupdate または patch するか、Google Pay Merchant Center を使用するだけで大丈夫です。この情報は、更新された EventTicketClass に関連付けられているすべての EventTicketObject に渡されます。これは、EventTicketClass レベルで定義されているすべてのフィールドに当てはまります。

1 枚のパスを更新する場合は(1 人のチケット所有者の座席番号が変更されたなど)、1 つの EventTicketObjectupdate または patch する必要があります。これは、EventTicketObject レベルで定義されているすべてのフィールドに当てはまります。

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

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

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

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

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

複数のパスに適用されるボタンの作成方法については、複数の参加者を保存するボタンをご覧ください。

パスの UI 表現の詳細については、イベント チケットのグループ化をご覧ください。

イベント チケットのグループ化

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

EventTicketObject がグループとみなされる条件は、class.eventID プロパティが定義されているかどうかで異なります。

class.eventId が設定されたグループ

class.eventId プロパティを使用すると、他のプロパティに関係なく、チケットをグループ化できます。 たとえば、2 つの EventTicketObject オブジェクトに class.eventId = "foo" が設定されている場合、class.eventNameclass.dateTime.start の値が異なっていても、この 2 つのオブジェクトは 1 つのグループとみなされます。

class.eventID が使用されている場合、次のプロパティの値が一致していれば、グループとみなされます。

  • 発行者 ID(Google Pay API for Passes Merchant Center から)
  • class.eventId

class.eventId が設定されていないグループ

EventTicketObject オブジェクトに class.eventId が設定されていない場合、以下のすべてのプロパティが一致していれば、同じグループのオブジェクトとして認識されます。

  • 発行者 ID(Google Pay API for Passes Merchant Center から)
  • class.eventName
  • class.dateTime.start

今後のイベントの通知を受け取る

Google Pay から、イベントの 3 時間前にユーザーに通知が送信されます。イベント時間は class.dateTime.start で定義されます。

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

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

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

class.eventName
Expand for more options

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

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

通知は固定され、ユーザーが開いても自動的には閉じません。class.dateTime.end の 60 分後に自動的に閉じます。class.dateTime.end 時間が指定されていない場合は、代わりに class.dateTime.start が使用されます。

リンクされたクーポン

リンクされたクーポンを使用すると、既存のクーポンをイベント チケットビュー内に表示でき、ユーザーは関連性の高いコンテンツを容易に見つけることができます。EventTicketObject の書き込み可能なリスト フィールド linkedOfferIds は、イベント チケットに関連付けられているクーポンを示します。

リンク前のクーポンの作成

クーポンをリンクするには、イベント チケットにリンクされるクーポンクラスおよびクーポン オブジェクトがすでに作成されている必要があります。クーポンの作成の詳細については、クーポンをご覧ください。スタンドアロンのクーポンとは異なり、リンクされたクーポンでは、ユーザーがクーポンを明示的に保存する必要はありません。OfferObject にある id フィールドは、EventTicketObject を参照するために使用されます。

既存のクーポンは、REST API 呼び出し insertupdatepatchmodifyLinkedOfferObjects を使用してイベント チケットにリンクできます。

イベント チケットの作成時に insert 呼び出しを使用してクーポンをイベント チケットにリンクするとき、または update 呼び出しを使用してクーポンを既存のイベント チケットにリンクするときとリンク解除するときに、フィールド linkedOfferIds は、形式が確立された他の EventTicketObject を使って書き込むことができます。

{
  "id": "2945482443380251551.ExampleObject1",
  "classId": "2945482443380251551.ExampleClass1",
  ...
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

patch 呼び出しでクーポンを既存のイベント チケットにリンクするときと、リンクを解除するとき、リクエストに含めることができるフィールドは linkedOfferIds だけです。

{
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

ただし、配列を処理する際のミスを避けるために、追加する必要があるリンクされたクーポンと、削除する必要があるリンクされたクーポンを指定します。変更しないリンクされたクーポンは省略できます。次の例に示すように、modifyLinkedOfferObjects メソッドを使用することをおすすめします。

{
  "linkedOfferObjectIds" {
    "addLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject1",
      "2945482443380251551.OfferObject2"
    ],
    "removeLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject3",
      "2945482443380251551.OfferObject4"
    ]
  }
}

リンクされたクーポンのあるイベント チケットのデザイン

リンクされたクーポンは、次のように、イベント チケットビューのカード セクションと詳細セクションの間に表示されます。カルーセルに表示されるのは、最大 5 件のリンクされたクーポンだけです。5 件を超えるクーポンがイベント チケットにリンクされている場合は、カルーセルの端にある [その他] ボタンをクリックすると、すべてを表示できます。

リンクされたクーポン

リンクされたクーポンをクリックすると、次のように、簡略化されたクーポン デザインが使用されます。

リンクされたクーポンをクリック

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

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

  • class.dateTime.end から 72 時間以上経過している。class.dateTime.end が指定されていない場合は、代わりに class.dateTime.start が使用されます。このパスは、class.dateTime.end または class.dateTime.start から 72~96 時間の間に [期限切れのパス] に移動されます。
  • object.validTimeInterval.end.date が期限切れになっている。このパスは、object.validTimeInterval.end.date を過ぎてから 24 時間以内に [期限切れのパス] に移動されます。
  • object.state フィールドが ExpiredInactive、または 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
              }
            }
    }
  }
  …
  …
  …
}