ユースケース

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

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

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

FlightClass と FlightObject

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

FlightClass

FlightClass には、特定の日時の特定のフライトについて、すべての乗客または乗客のサブセットが共通して保持するデータが格納されます。たとえば、共通のデータには、航空会社、出発地、目的地、フライト番号、出発時刻などがあります。そのフライトのすべての乗客の搭乗券に、同じデータが記載されます。

FlightClass に、同じ飛行機の乗客のサブセットについて共通するデータを格納することもできます。たとえば、ファーストクラス、ビジネスクラス、エコノミークラスの 3 種類の FlightClass 構造を作成できます。これにより、必要に応じて、サブセットごとに異なるフィールドを使用できます。この場合、依然として 3 つすべてのクラスが、特定の日時に同じ経路を飛行する同じ飛行機を表します。

FlightObject

FlightObject は、特定の時点に特定の飛行機でフライトする各乗客を表します。たとえば、FlightObject には、乗客名、座席番号、搭乗バーコードが含まれています。これらは乗客の搭乗券ごとに異なります。

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

サポートされている国

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

ユースケース

以下では、搭乗券のカテゴリにのみ使用できるユースケースについて説明します。

パスを更新する。
経由地のあるフライト情報を保存する。
複数のパスを保存するボタンを作成する。
複数の搭乗券をグループ化する。
間近のフライトの通知を受け取る。
フライトの更新通知を受け取る。
期限切れのパスを処理する
保存されたパスにリンクする。
保存したパスからリンクする。

パスを更新する

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

出発予定時刻が変更された場合など、特定のフライトに関するすべての搭乗券のフィールドを更新するには、FlightClass を update または patch するか、Google Pay Merchant Center を使用するだけで大丈夫です。この情報は、更新された FlightClass に関連付けられているすべての FlightObject に渡されます。これは、FlightClass レベルで定義されているすべてのフィールドに当てはまります。

1 枚のパスを更新する場合は（1 人の搭乗者の座席番号が変更されたなど）、1 つの FlightObject を update または patch する必要があります。これは、FlightObject レベルで定義されているすべてのフィールドに当てはまります。

注: データ構造について詳しくは FlightClass と FlightObject をご覧ください。

注: update と patch の違いについては、パッチ（部分更新）をご覧ください。

どの update ロジックでも、最初に GET リクエストを実行してクラスまたはオブジェクトを取得する必要があります。これにより、クラスまたはオブジェクトの最新バージョンが確実に使用されます。省略したフィールドは消去されます。

一般的に、変更するフィールドのみにデータを指定する場合は、patch を使用するほうが安全です。省略したフィールドは消去されません。ただし、配列を変更する場合は特に注意が必要です。配列を含むパッチリクエストを実行すると、既存の配列も、指定した配列で置換されます。配列内の要素を部分的に変更、追加、削除することはできません。

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

フライトの最新情報のデータソース

class.localScheduledDepartureDateTime で指定された時間が過去 24 時間以内または次の 48 時間以内の場合、フライトステータスカードが表示されます。この場合、Google Pay では、Google フライトのデータまたは Google Pay パスで取得した情報を表示できます。どちらのソースが使用されるかは、以下によって異なります。

class.localEstimatedOrActualDepartureDateTime を指定していない場合、Google フライトが使用されます。この場合、設定した class.flightStatus は無視されます。

たとえば、フライトが遅延すると、Google Pay アプリの [ホーム] タブの下に新しい出発時刻を記載したカードが表示されます。同様に、遅延カードも [パス] タブの下に表示されます。
class.localEstimatedOrActualDepartureDateTime を指定していても、class.flightStatus を指定しなかった場合は、指定した時刻に基づいてフライトが遅延しているかどうかが判断されます。カードのフライトステータスは、次のロジックに基づいて表示されます。
- class.localEstimatedOrActualDepartureDateTime が class.localScheduledDepartureDateTime を上回っている場合、遅延フライトを記載したカードがユーザーに表示されます。
- class.localEstimatedOrActualDepartureDateTime が class.localScheduledDepartureDateTime を上回らない場合、ステータスメッセージのない、フライト情報を記載したカードがユーザーに表示されます。

フライトに関する情報のソースとして Google フライトを使用しない場合は、FlightClass の flightStatus、localScheduledDepartureDateTime、localEstimatedOrActualDepartureDateTime を入力する必要があります。本人のデータのみがカードに使用されます。FlightClass で IATA コードの代わりに ICAO 空港コードを使用する場合も、Google フライトはフライト情報のソースとして使用されません。

特定のフィールドが変更されると、ユーザーは変更に関するプッシュ通知を受け取ります。詳細については、フライトの更新通知を受け取るをご覧ください。

経由地のあるフライト情報を保存する

飛行機で旅行する場合、目的地に直行するのではなく、複数の場所を経由することも少なくありません。航空会社は、最終目的地までの搭乗券をまとめて発券します。Google Pay API for Passes でも、出発地から最終目的地までを 1 つの FlightObject で表します。

たとえば、SFO から LAX 経由で TPE まで行く乗客が 2 人いる場合、2 つの FlightClass 構造と 4 つの FlightObject オブジェクトを使用します。

	`FlightClass` A（SFO から LAX - 航空会社、フライト番号、出発時刻）	`FlightClass` B（LAX から TPE - 航空会社、フライト番号、出発時刻）
搭乗者 Q	`FlightObject: id_01`	`FlightObject: id_02`
搭乗者 Z	`FlightObject: id_03`	`FlightObject: id_04`

これらの項目は実際の搭乗券の情報を反映しています。搭乗者 Q と Z はともに 2 枚の搭乗券を所有しています。

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

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

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

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

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

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

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

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

各オブジェクトで以下のプロパティがすべて一致していれば、FlightObject オブジェクトはグループとみなされます。

発行者 ID（Google Pay API for Passes Merchant Center から）
class.flightHeader.carrier.carrierIataCode
class.flightHeader.flightNumber
class.localScheduledDepartureDateTime
object.reservationInfo.confirmationCode

2 つの FlightObject オブジェクトで上記のいずれかのプロパティが異なる場合、オブジェクトはグループとみなされません。

注: これはクラスプロパティの場合もあれば、オブジェクトプロパティの場合もあります。これにより、異なるクラスの FlightObject オブジェクトをグループ化できます。

間近のフライトの通知を受け取る

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

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

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

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

Boarding pass for your flight to class.destination.airportIataCode
Expand for more options

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

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

通知は固定され、ユーザーが開いても自動的には閉じません。class.localScheduledDepartureDateTime の 60 分後に自動的に閉じます。

フライトの更新通知を受け取る

フライトの特定のフィールドが変更されると、搭乗券を保存しているユーザーのデバイスにプッシュ通知が送信されます。これは特定の条件が満たされた場合にのみ発生します。

ターミナルと搭乗ゲート

class.origin.terminal または class.origin.gate が変更され、次の条件が満たされると、フィールドが変更されたという通知が送信されます。

class.localScheduledDepartureDateTime まで 3 時間未満である。

通知の形式は、「Sample Airlines によってゲートが A1 に変更されました」のようになります。この形式は変更できません。

搭乗時間と出発時間

class.localBoardingDateTime または class.localEstimatedOrActualDepartureDateTime が変更され、次の条件が満たされると、フィールドが変更されたという通知が送信されます。

class.localScheduledDepartureDateTime まで 24 時間未満である。
時間の変更が 10 分以上である。

通知の形式は、「Sample Airlines が搭乗時間を午後 6:00 に更新しました。」のようになります。この形式は変更できません。

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

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

class.localScheduledDepartureDateTime または class.localEstimatedOrActualDepartureDateTime から 24 時間以上経過している。このパスは、class.localScheduledDepartureDateTime または class.localEstimatedOrActualDepartureDateTime から 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 パスのヘッダーの下で、アプリまたはウェブサイトにリンクできます。この機能は、すべての種類の Google Pay パスでご利用いただけます。

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

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

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

Google Pay パスでアプリへのリンクを設定する

特定の 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
              }
            }
    }
  }
  …
  …
  …
}