Tessere collegate automaticamente

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
Esempio principale di tessera collegata automaticamente Esempio di tessera collegata automaticamente secondaria
Documento principale con il callout che indica che è stato aggiunto un nuovo documento Nuovo documento di identità collegato al documento principale

Casi d'uso

Potresti avere diversi casi d'uso per il collegamento delle 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 una tessera 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 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.

  1. Crea un oggetto di qualsiasi tipo di passaggio elencato con i parametri richiesti. Questo è l'oggetto principale.
  2. Crea un altro oggetto di qualsiasi tipo di tessera elencato. Sarà l'oggetto collegato.
  3. 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:

  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 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

Con l'utilizzo errato dell'API possono verificarsi potenziali errori, tra cui:

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.
L'oggetto principale e l'oggetto collegato fanno riferimento allo stesso oggetto. Non puoi allegare 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. 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 tessere collegate per la tessera principale.