背景
自動リンクパス機能を使用すると、Google ウォレットに既存のパスをすでに持っているユーザーに追加のパスを送信できます。ユーザーがメイン(メイン)のパスを保存する際に、パスをメインパスに事前リンクすることもできます。自動リンクされたパスはメインパスにグループ化され、新しいパスがリンクされたことをユーザーに知らせるメインパスの上にコールアウトが表示されます。メインパスまたはリンクされたパスとして、次のパスタイプがサポートされています。
- イベント チケット
- 搭乗券
- 交通機関のパス
- 特典
- ギフトカード
- ポイントパス
- 汎用パス
メインパス(新しいパスが追加されたことを示すコールアウト) | メインパスにリンクされた新しいパス |
ユースケース
パスを既存のパスにリンクするユースケースはさまざまです。いくつかの例を以下に示します。
- 既存のポイントカードにクーポンをリンクします。
- 食事クーポンを搭乗券またはイベント チケットにリンクします。
- 駐車パスをイベント チケットにリンクします。
自動リンクされたパスを使用する際の考慮事項
- プライマリ オブジェクトとリンクされたオブジェクトで同じ発行元 ID を使用する必要があります。
- リンクされたオブジェクトは、プライマリ オブジェクトごとに 50 個までに制限されています。
- リンクされたパスの自動プッシュは保証されておらず、ベスト エフォートと見なされます。ユーザーは自動リンクパスの受信を無効にできます。ユースケースが重要であり、ユーザーがリンクされたパスを受け取る必要がある場合は、ユーザーがパスを追加できるように別のチャネルを介して通信することをおすすめします。
- Google ウォレット AUP の更新には、自動リンクパスの使用に関するガイダンスが含まれており、遵守する必要があります。
統合の手順
すでにプライマリ オブジェクトを作成している場合は、ステップ 1 をスキップできます。
- 必須パラメータを含む任意のパスタイプのオブジェクトを作成します。これはプライマリ オブジェクトです。
- リストにある任意のパスタイプの別のオブジェクトを作成します。これがリンクされたオブジェクトになります。
- プライマリ オブジェクトの保存前または保存後に、linkedObjectIds パラメータにリンクされたオブジェクトの ID を使用して、プライマリ オブジェクトを更新します。
プライマリ パスに linksObjectId を設定するために必要な最小ペイロードがあります。必須の 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 を共有しません。 | リンクされたオブジェクトを別の発行者のオブジェクトにアタッチすることはできません。 |
プライマリ オブジェクトとリンクされたオブジェクトは同じオブジェクトを参照しています。 | LinkingObject と同じオブジェクトをアタッチすることはできません。 |
リンクされたオブジェクトは存在しません。 | リンクされたオブジェクトは、すでに Wallet API に挿入されている必要があります。 |
リンクされたオブジェクトには、すでに別のリンク済みオブジェクトがあります。ネストされたリンク オブジェクトは追加できません。 | リンクされたオブジェクトには、別のリンク済みオブジェクトを含めることはできません。 |
オブジェクトはすでに別のオブジェクトにリンクされています。ネストされたリンク オブジェクトは追加できません。 | プライマリ オブジェクトを単独でリンク オブジェクトにすることはできません。 |
上限を超えたため、これ以上リンクされたオブジェクトを追加できません。 | メインのパスのリンクされたパスの数が上限の 50 個に達しました。 |