自動リンクされたパス

背景

自動リンクされたパス機能を使用すると、Google ウォレットに既存のパスをすでに持っているユーザーに追加のパスを送信できます。ユーザーがプライマリ（メイン）パスを保存する際に、パスをプライマリパスに事前にリンクすることもできます。自動リンクされたパスは、プライマリ パスとグループ化され、プライマリ パスの上に、新しいパスがリンクされたことをユーザーに知らせるコールアウトが表示されます。次のパスタイプは、プライマリ パスまたはリンク済みパスとしてサポートされています。

  • イベント チケット
  • 搭乗券
  • 交通機関のパス
  • 特典
  • ギフトカード
  • ポイントカード パス
  • 汎用パス
自動リンクされたパスのプライマリ パスの例 自動リンクされたパスの二次的な例
新しいパスが追加されたことを示すコールアウトがあるメインパス メインパスにリンクされた新しいパス

ユースケース

パスを既存のパスにリンクするユースケースはさまざまです。いくつかの例を以下に示します。

  • 既存のポイントカードにクーポンをリンクします。
  • 食事クーポンを搭乗券またはイベント チケットにリンクします。
  • 駐車券をイベント チケットにリンクする。

自動リンクされたパスを使用する際の考慮事項

  • プライマリ オブジェクトとリンクされたオブジェクトは、同じ IssuerId を使用する必要があります。
  • プライマリ オブジェクトごとにリンク オブジェクトの上限が 50 個あります。
  • リンクされたパスの自動プッシュは保証されず、ベスト エフォートとして扱われます。ユーザーは自動リンクされたパスの受信を無効にできます。ユースケースが重要で、ユーザーがリンクされたパスを受け取る必要がある場合は、別のチャネルで連絡して、ユーザーがパスを追加できるようにすることをおすすめします。
  • Google ウォレット AUP の更新には、自動リンクされたパスの使用に関するガイダンスが含まれており、これに準拠する必要があります。

統合の手順

プライマリ オブジェクトをすでに作成している場合は、ステップ 1 をスキップできます。

  1. 必要なパラメータを使用して、リストされている任意のパスタイプのオブジェクトを作成します。これはプライマリ オブジェクトです。
  2. リストされている任意のパスタイプの別のオブジェクトを作成します。これはリンクされたオブジェクトになります。
  3. プライマリ オブジェクトの保存前または保存後に、linkedObjectIds パラメータのリンクされたオブジェクトの ID でプライマリ オブジェクトを更新します。

プライマリ パスに linkedObjectIds を設定するには、最小ペイロードが必要です。次の 3 つの必須パラメータがあります。

  1. ISSUERID.PRIMARY_OBJECT_ID
  2. ISSUERID.PRIMARY_CLASS_ID
  3. ISSUERID.LINKED_OBJECT_ID

リンク済みオブジェクトをパス オブジェクトに追加する JSON リクエストの例

  …
  {
    "id": "ISSUERID.PASS_OBJECTID",
    "classId": "ISSUERID.PASS_CLASSID",
    "barcode": {
      "type": "qrCode",
      "value": "QR code"
    },
    "linkedObjectIds": ["ISSUERID.LINKED_PASS_OBJECTID"]
  }
  …

オブジェクトをパス オブジェクトにリンクした後の JSON レスポンスの例

  …
  "state": "active",
  "linkedObjectIds": {
    "ISSUERID.LINKED_PASS_OBJECTID"
  }
  …

予想される動作

正常なレスポンスを受信すると、パスを更新したデバイスは、リンクされたパスを受信します。このリンクされたパスは、プライマリ パスとともにグループ化されます。右にスワイプすると、リンクされたパスが表示されます。

例外処理

API を誤って使用すると、次のようなエラーが発生する可能性があります。

メッセージ 理由
プライマリ オブジェクトとリンクされたオブジェクトが同じ発行元 ID を共有していない。 リンクされたオブジェクトを別の発行元のオブジェクトに関連付けることはできません。
プライマリ オブジェクトとリンクされたオブジェクトが同じオブジェクトを参照している。 linkedObject と同じオブジェクトをアタッチすることはできません。
リンクされたオブジェクトが存在しません。 リンクされたオブジェクトは、すでに Wallet API に挿入されているはずです。
リンクされたオブジェクトにすでに別のリンクされたオブジェクトがあります。ネストされたリンク済みオブジェクトを追加することはできません。 リンクされたオブジェクトに別のリンクされたオブジェクトを設定することはできません。
オブジェクトはすでに別のオブジェクトにリンクされています。ネストされたリンク済みオブジェクトを追加することはできません。 プライマリ オブジェクト自体をリンク オブジェクトにすることはできません。
リンクされたオブジェクトを追加できません。上限を超えています。 プライマリ パスのリンク済みパスの上限（50 個）に達しています。