Tessere collegate automaticamente
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Sfondo
La funzionalità Tessere collegate automaticamente ti consente di inviare tessere aggiuntive a un
utente che ha già la tua tessera esistente in Google Wallet. Puoi anche
precollegare le tessere a una tessera principale quando un utente salva la tessera principale
(principale). La tessera collegata automaticamente viene raggruppata con la tessera principale con un callout sopra la tessera principale che informa l'utente che è stata collegata una nuova tessera. I seguenti tipi di tessere sono supportati come tessere principali o collegate:
- Biglietto evento
- Carta d'imbarco
- Tessera per il trasporto pubblico
- Offerta
- Carta regalo
- Carta fedeltà
- Tessera generica
|
|
|
Tessera principale con il callout che indica che è stata aggiunta una nuova tessera
|
Nuova tessera collegata alla tessera principale
|
Casi d'uso
Potrebbero esserci diversi casi d'uso per collegare le tessere a una tessera esistente. Ecco alcuni esempi:
- Collega un'offerta a una carta fedeltà esistente.
- Collega un buono pasto a una carta d'imbarco o a un biglietto per un evento.
- Collega un pass per il parcheggio a un biglietto di un evento.
Alcune considerazioni sull'utilizzo delle tessere collegate automaticamente
- L'oggetto principale e l'oggetto collegato devono utilizzare lo stesso issuerId.
- Esiste un limite di 50 oggetti collegati per oggetto principale.
- L'invio automatico delle tessere collegate non è garantito e viene considerato come servizio di tipo best effort. Gli utenti possono disattivare la ricezione delle tessere collegate automaticamente. Se il caso d'uso è prioritario e l'utente deve ricevere la tessera collegata, ti consigliamo di comunicare tramite un altro canale per assicurarti che l'utente aggiunga la tessera.
- Gli aggiornamenti alle Norme relative all'utilizzo di Google Wallet includono indicazioni sull'utilizzo delle tessere collegate automaticamente, a cui è necessario attenersi.
Passaggi per l'integrazione
Se hai già creato un oggetto principale, puoi saltare il passaggio 1.
- Crea un oggetto di qualsiasi tipo di passaggio elencato con i parametri richiesti. Questo è l'oggetto principale.
- Crea un altro oggetto di qualsiasi tipo di tessera elencato. Sarà l'oggetto
collegato.
- Prima o dopo il salvataggio dell'oggetto principale, aggiorna
l'oggetto principale con l'ID dell'oggetto collegato nel parametro linkedObjectIds.
È richiesto un payload minimo per impostare linkedObjectIds su un
passaggio principale. I tre parametri obbligatori includono:
- ISSUERID.PRIMARY_OBJECT_ID
- ISSUERID.PRIMARY_CLASS_ID
- ISSUERID.LINKED_OBJECT_ID
Esempio di richiesta JSON per aggiungere un oggetto collegato a un oggetto pass
…
{
"id": "ISSUERID.PASS_OBJECTID",
"classId": "ISSUERID.PASS_CLASSID",
"barcode": {
"type": "qrCode",
"value": "QR code"
},
"linkedObjectIds": {"ISSUERID.LINKED_PASS_OBJECTID"}
}
…
Esempio di risposta JSON dopo il collegamento di un oggetto a un oggetto pass
…
"state": "active",
"linkedObjectIds": {
"ISSUERID.LINKED_PASS_OBJECTID"
}
…
Comportamento previsto
Dopo aver ricevuto una risposta positiva, i dispositivi con la tessera che hai aggiornato dovrebbero ricevere la tessera collegata. Questa tessera collegata verrà raggruppata con la tessera principale. Gli utenti possono vedere la tessera collegata scorrendo verso destra.
Gestione delle eccezioni
Potrebbero verificarsi errori con un uso non corretto dell'API, che possono includere:
| Messaggio |
Motivo |
| L'oggetto principale e l'oggetto collegato non condividono lo stesso ID emittente. |
Non puoi allegare un oggetto collegato all'oggetto di un altro emittente. |
| Oggetto principale e oggetto collegato fanno riferimento allo stesso oggetto. |
Non puoi collegare lo stesso oggetto di LinkedObject. |
| L'oggetto collegato non esiste. |
L'oggetto collegato dovrebbe essere già inserito nell'API Wallet. |
| L'oggetto collegato ha già un altro oggetto collegato. Impossibile aggiungere oggetti collegati nidificati. |
Gli oggetti collegati non possono avere un altro oggetto collegato. |
| L'oggetto è già collegato a un altro oggetto. Non è possibile aggiungere oggetti
collegati nidificati. |
L'oggetto principale non può essere di per sé un oggetto collegato. |
| Impossibile aggiungere altri oggetti collegati, limite superato. |
È stato raggiunto il limite di 50 tessere collegate per la tessera principale. |
Salvo quando diversamente specificato, i contenuti di questa pagina sono concessi in base alla licenza Creative Commons Attribution 4.0, mentre gli esempi di codice sono concessi in base alla licenza Apache 2.0. Per ulteriori dettagli, consulta le norme del sito di Google Developers. Java è un marchio registrato di Oracle e/o delle sue consociate.
Ultimo aggiornamento 2025-09-04 UTC.
[null,null,["Ultimo aggiornamento 2025-09-04 UTC."],[[["\u003cp\u003eAuto Linked Passes enable sending additional Google Wallet passes to users who already possess an existing pass, like linking an offer to a loyalty card.\u003c/p\u003e\n"],["\u003cp\u003eSupported pass types include event tickets, boarding passes, transit passes, offers, gift cards, loyalty passes, and generic passes.\u003c/p\u003e\n"],["\u003cp\u003ePrimary and linked passes must share the same issuer ID, with a maximum of 50 linked passes per primary pass, and automatic delivery is best-effort, not guaranteed.\u003c/p\u003e\n"],["\u003cp\u003eIntegration involves creating primary and linked pass objects, then updating the primary object with the linked object's ID using the \u003ccode\u003elinkedObjectIds\u003c/code\u003e parameter.\u003c/p\u003e\n"],["\u003cp\u003ePotential errors include issuer ID mismatch, self-referencing objects, nonexistent or already linked objects, nested linking attempts, and exceeding the linked pass limit.\u003c/p\u003e\n"]]],["Auto Linked Passes enable sending additional passes to users with an existing primary pass in Google Wallet. To implement, create a primary and a linked object. Update the primary object with the linked object's ID using the `linkedObjectIds` parameter. The issuer ID must be the same for both objects, with a limit of 50 linked passes per primary pass. Linked passes are displayed grouped with the primary pass. There are errors for nested linked passes or using different issuer ids.\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/tickets/boarding-passes/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/tickets/boarding-passes/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. |"]]
