Cartes associées automatiquement
Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Contexte
La fonctionnalité Cartes associées automatiquement vous permet d'envoyer des cartes supplémentaires à un utilisateur qui dispose déjà de votre carte existante dans Google Wallet. Vous pouvez également pré-associer des cartes à une carte principale lorsqu'un utilisateur enregistre la carte principale (principale). La carte associée automatiquement est regroupée avec la carte principale, avec un accroche au-dessus de la carte principale informant l'utilisateur qu'une nouvelle carte a été associée. Les types de cartes suivants sont acceptés en tant que cartes principales ou associées :
- Billet pour un événement
- Carte d'embarquement
- Titre de transport
- Offre
- Bon d'achat
- Carte de fidélité
- Carte générique
|
|
|
Carte principale avec le message indiquant qu'une nouvelle carte a été ajoutée
|
Nouvelle carte associée à la carte principale
|
Cas d'utilisation
L'association de cartes à une carte existante peut varier selon les cas d'utilisation. Voici quelques exemples :
- Associez une offre à une carte de fidélité existante.
- Associez un titre-restaurant à une carte d'embarquement ou à un billet pour un événement.
- Associer une carte de stationnement à un billet pour un événement
Éléments à prendre en compte lorsque vous utilisez des cartes associées automatiquement
- L'objet principal et l'objet associé doivent utiliser le même issuerId.
- Vous ne pouvez associer qu'un maximum de 50 objets par objet principal.
- L'envoi automatique des cartes associées n'est pas garanti et est considéré comme une solution de dernier recours. Les utilisateurs peuvent désactiver la réception des cartes associées automatiquement. Si le cas d'utilisation est critique et que l'utilisateur doit recevoir la carte associée, nous vous recommandons de communiquer via un autre canal pour vous assurer qu'il l'ajoute.
- Les mises à jour du Règlement Google Wallet incluent des consignes sur l'utilisation des cartes associées automatiquement que vous devez respecter.
Procédure d'intégration
Si vous avez déjà créé un objet principal, vous pouvez ignorer l'étape 1.
- Créez un objet de n'importe quel type de carte listé avec les paramètres requis. Il s'agit de l'objet principal.
- Créez un autre objet avec n'importe quel type de carte listé. Il s'agit de l'objet associé.
- Avant ou après l'enregistrement de l'objet principal, mettez à jour l'objet principal avec l'ID de l'objet associé dans le paramètre linkedObjectIds.
Une charge utile minimale est requise pour définir les linkedObjectIds sur une carte principale. Les trois paramètres obligatoires sont les suivants :
- ISSUERID.PRIMARY_OBJECT_ID
- ISSUERID.PRIMARY_CLASS_ID
- ISSUERID.LINKED_OBJECT_ID
Exemple de requête JSON pour ajouter un objet associé à un objet carte
…
{
"id": "ISSUERID.PASS_OBJECTID",
"classId": "ISSUERID.PASS_CLASSID",
"barcode": {
"type": "qrCode",
"value": "QR code"
},
"linkedObjectIds": {"ISSUERID.LINKED_PASS_OBJECTID"}
}
…
Exemple de réponse JSON après avoir associé un objet à un objet de carte
…
"state": "active",
"linkedObjectIds": {
"ISSUERID.LINKED_PASS_OBJECTID"
}
…
Comportement attendu
Après avoir reçu une réponse positive, les appareils avec la carte que vous avez mise à jour devraient recevoir la carte associée. Cette carte associée sera regroupée avec la carte principale. Les utilisateurs peuvent afficher la carte associée en balayant l'écran vers la droite.
Gestion des exceptions
Des erreurs potentielles peuvent se produire en cas d'utilisation incorrecte de l'API, par exemple :
| Message |
Motif |
| L'objet principal et l'objet associé ne partagent pas le même ID d'émetteur. |
Vous ne pouvez pas associer un objet associé à l'objet d'un autre émetteur. |
| L'objet principal et l'objet associé font référence au même objet. |
Vous ne pouvez pas joindre le même objet que le linkedObject. |
| L'objet associé n'existe pas. |
L'objet associé doit déjà être inséré dans l'API Wallet. |
| L'objet associé est déjà associé à un autre objet. Impossible d'ajouter des objets liés imbriqués. |
Les objets associés ne peuvent pas avoir d'autre objet associé. |
| L'objet est déjà associé à un autre objet. Impossible d'ajouter des objets liés imbriqués. |
L'objet principal ne peut pas être un objet associé. |
| Impossible d'ajouter d'autres objets associés, la limite est atteinte. |
Vous avez atteint la limite de 50 cartes associées pour la carte principale. |
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/03 (UTC).
[null,null,["Dernière mise à jour le 2025/09/03 (UTC)."],[[["\u003cp\u003eAuto Linked Passes enable you to send additional passes to users who already have an existing pass from your organization in their Google Wallet, pre-linking them for a seamless user experience.\u003c/p\u003e\n"],["\u003cp\u003eThis feature supports various pass types including Event tickets, Boarding passes, Transit passes, Offers, Gift cards, Loyalty passes, and Generic passes, offering flexibility for different use cases.\u003c/p\u003e\n"],["\u003cp\u003eWhen utilizing Auto Linked Passes, ensure the primary and linked objects share the same issuerId and be aware of the 50 linked object limit per primary object.\u003c/p\u003e\n"],["\u003cp\u003eWhile automatic delivery of linked passes is best-effort and user-configurable, the feature offers a convenient way to provide users with related passes, enhancing their experience with your services.\u003c/p\u003e\n"]]],["Auto Linked Passes enable grouping additional passes with an existing primary pass in Google Wallet. Supported pass types include event tickets, boarding passes, and loyalty passes. To link passes, create primary and linked objects, then update the primary object with the linked object's ID using the `linkedObjectIds` parameter. Both objects must share the same `issuerId`. There is a limit of 50 linked passes. Errors may occur if linked objects are from different issuers or the 50 limit is reached.\n"],null,["# Auto Linked Passes\n\n#### Background\n\nThe Auto Linked Passes feature lets you send additional passes to a\nuser who already has your existing pass in their Google Wallet. You can also\npre-link passes to a primary pass when a user saves the **primary**\n(main) pass. The Auto Linked Pass is grouped with the primary pass with a\ncallout above the primary pass informing the user that a new pass has been\nlinked. The following pass types are supported as primary or linked passes;\n\n- Event ticket\n- Boarding pass\n- Transit pass\n- Offer\n- Gift card\n- Loyalty pass\n- Generic pass\n\n|--------------------------------------------------------------|-------------------------------------|\n| | |\n| Primary pass with the callout that a new pass has been added | New pass linked to the primary pass |\n\n#### Use Cases\n\nYou may have different use cases for linking passes to an existing pass. Some\nexamples include:\n\n- Link an offer to an existing loyalty card.\n- Link a meal voucher to a boarding pass or event ticket.\n- Link a parking pass to an event ticket.\n\n#### Some considerations when using Auto Linked Passes\n\n- The primary object and linked object must use the same issuerId.\n- There is a limit of 50 linked objects per primary object.\n- Pushing linked passes automatically is not guaranteed and considered best-effort. Users can opt out of receiving Auto Linked Passes. If the use case is critical and the user must receive the linked pass, we recommend communicating through another channel to ensure the user adds the pass.\n- Updates to the [Google Wallet AUP](https://payments.developers.google.com/terms/aup) include guidance on the use of Auto Linked Passes which must be adhered to.\n\n#### Integration Steps\n\nIf you have already created a **primary** object you can skip step 1.\n\n1. Create an [object](/wallet/generic/use-cases/create) of any pass type listed with the required parameters. This is the **primary** object.\n2. Create another object of any pass type listed. This is going to be the **linked** object.\n3. Either before or after the primary object is saved, [update](/wallet/generic/use-cases/update) the primary object with the ID of the linked object in the linkedObjectIds parameter.\n\nThere is a minimum payload required to set the linkedObjectIds on a primary\npass. The 3 required parameters include;\n\n1. ISSUERID.PRIMARY_OBJECT_ID\n2. ISSUERID.PRIMARY_CLASS_ID\n3. ISSUERID.LINKED_OBJECT_ID\n\n#### Example JSON Request to add a linked object to a pass object\n\n```carbon\n ...\n {\n \"id\": \"ISSUERID.PASS_OBJECTID\",\n \"classId\": \"ISSUERID.PASS_CLASSID\",\n \"barcode\": {\n \"type\": \"qrCode\",\n \"value\": \"QR code\"\n },\n \"linkedObjectIds\": {\"ISSUERID.LINKED_PASS_OBJECTID\"}\n }\n ...\n```\n\n#### Example JSON Response after linking an object to a pass object\n\n```scdoc\n …\n \"state\": \"active\",\n \"linkedObjectIds\": {\n \"ISSUERID.LINKED_PASS_OBJECTID\"\n }\n …\n```\n\n#### Expected behavior\n\nAfter receiving a successful response, devices with the pass you updated\nshould receive the linked pass. This linked pass will be grouped together with\nthe primary pass. Users can see the linked pass by swiping right.\n\n#### Exception handling\n\nPotential errors may happen with incorrect use of the API which can\ninclude;\n\n| **Message** | **Reason** |\n|------------------------------------------------------------------------------------|----------------------------------------------------------------------|\n| Primary object and linked object don't share the same issuer ID. | You cannot attach a linked object to another issuer's object. |\n| Primary object and linked object refer to the same object. | You cannot attach the same object as the linkedObject. |\n| Linked object does not exist. | The linked object should already be inserted into the Wallet API. |\n| Linked object already has another linked object. Cannot add nested linked objects. | Linked objects cannot have another linked object. |\n| Object is already linked to another object. Cannot add nested linked objects. | Primary object cannot be a linked object by itself. |\n| Cannot add any more linked objects, limit exceeded. | The limit of 50 linked passes has been reached for the primary pass. |"]]
