自動リンクされたパス

背景

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

イベントチケット
搭乗券
交通機関のパス
特典
ギフトカード
ポイントカード
汎用パス


新しいパスが追加されたことを示す吹き出しが表示されたメインのパス	メインのパスにリンクされた新しいパス

ユースケース

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

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

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

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

統合の手順

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

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

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

ISSUERID.PRIMARY_OBJECT_ID
ISSUERID.PRIMARY_CLASS_ID
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 として添付することはできません。
リンクされたオブジェクトが存在しません。	リンクされたオブジェクトは、ウォレット API にすでに挿入されている必要があります。
リンクされたオブジェクトには、すでに別のリンクされたオブジェクトがあります。ネストされたリンクオブジェクトを追加することはできません。	リンクされたオブジェクトに別のリンクされたオブジェクトを含めることはできません。
オブジェクトはすでに別のオブジェクトにリンクされています。ネストされたリンクオブジェクトを追加することはできません。	プライマリオブジェクトをリンクオブジェクト単独にすることはできません。
リンクされたオブジェクトを追加できません。上限を超えています。	メインパスのリンク済みパスの上限である 50 に達しました。

自動リンクされたパス コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

背景