Tessere collegate automaticamente

Contesto

La funzionalità dei pass collegati automaticamente ti consente di inviare tessere aggiuntive a un utente che ha già il tuo pass esistente nel suo Google Wallet. Puoi anche eseguire il pre-collegamento delle tessere a un pass principale quando un utente salva il pass principale (principale). Il pass collegato automaticamente viene raggruppato con il pass principale con un callout sopra quello principale che informa l'utente che una nuova tessera è stata collegata. I seguenti tipi di tessere sono supportati come documenti principali o collegati.

• Biglietto evento
• Carta d'imbarco
• Pass per il trasporto pubblico
• Offerta
• Carta regalo
• Pass fedeltà
• Tessera generica

Casi d'uso

Potresti avere 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 coupon pasto a una carta d'imbarco o a un biglietto per un evento.
• Collega un pass per il parcheggio a un biglietto per 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 ed è considerato come "best effort". Gli utenti possono disattivare la ricezione delle tessere collegate automaticamente. Se il caso d'uso è critico e l'utente deve ricevere il pass collegato, ti consigliamo di comunicare tramite un altro canale per assicurarti che l'utente aggiunga il pass.
• Gli aggiornamenti alle AUP (Acceptable Use Policy, norme di utilizzo accettabile) di Google Wallet includono indicazioni sull'utilizzo dei pass collegati automaticamente che è necessario rispettare.

Passaggi per l'integrazione

Se hai già creato un oggetto principale, puoi saltare il passaggio 1.

1. Crea un oggetto di qualsiasi tipo di pass elencato con i parametri richiesti. Questo è l'oggetto principale.
2. Crea un altro oggetto di qualsiasi tipo di pass elencato. Questo sarà l'oggetto collegato.
3. Prima o dopo il salvataggio dell'oggetto principale, aggiorna l'oggetto principale con l'ID dell'oggetto collegato nel parametrolinkedObjectIds.

È richiesto un payload minimo per impostare ilinkedObjectIds su un pass primario. I 3 parametri obbligatori includono:

1. ISSUERID.PRIMARY_OBJECT_ID
2. ISSUERID.PRIMARY_CLASS_ID
3. 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 aver collegato un oggetto a un oggetto Pass

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

Comportamento previsto

Dopo aver ricevuto una risposta corretta, i dispositivi con la tessera che hai aggiornato dovrebbero ricevere la tessera collegata. Questa tessera collegata verrà raggruppata con il pass principale. Gli utenti possono vedere la tessera collegata scorrendo verso destra.

Gestione delle eccezioni

Potrebbero verificarsi errori con un uso non corretto dell'API, tra cui:

Messaggio	Motivo
L'oggetto principale e l'oggetto collegato non condividono lo stesso ID emittente.	Non puoi collegare un oggetto collegato a un oggetto di un altro emittente.
L'oggetto principale e l'oggetto collegato fanno riferimento allo stesso oggetto.	Non puoi collegare lo stesso oggetto collegatoObject.
L'oggetto collegato non esiste.	L'oggetto collegato dovrebbe essere già inserito nell'API Wallet.
L'oggetto collegato è già associato a un altro oggetto. Impossibile aggiungere oggetti collegati nidificati.	Gli oggetti collegati non possono avere un altro oggetto collegato.
L'oggetto è già collegato a un altro oggetto. Impossibile aggiungere oggetti collegati nidificati.	L'oggetto principale non può essere un oggetto collegato da solo.
Impossibile aggiungere altri oggetti collegati. Limite superato.	È stato raggiunto il limite di 50 pass collegati per il pass principale.