Panoramica

L'API Google Wallet Passes offre ai partner la possibilità di specificare un endpoint per l'attivazione di un biglietto per il trasporto pubblico. Quando è necessaria l'attivazione, verrà visualizzato un pulsante "Attiva" per l'utente che, se toccato, chiamerà l'endpoint specificato con i parametri descritti di seguito. L'endpoint deve garantire che la tessera abbia informazioni valide per l'utilizzo (codice a barre o ispezione visiva) prima di tornare, dopodiché la tessera nella sezione Wallet dell'utente verrà aggiornata per mostrare le informazioni sull'utilizzo. Tieni presente che prima dell'attivazione non verranno visualizzate informazioni esistenti sull'utilizzo.

API Activation

L'endpoint di attivazione è specificato nell'API utilizzando activationOptions nella classe di transito. Il partner è responsabile del mantenimento di un endpoint di attivazione funzionante con una latenza ragionevole.

  activationOptions: {
    activationUrl: string
  }
Campo Descrizione
activationUrl

string

URL dell'endpoint del partner che verrà chiamato per le richieste di attivazione. L'URL deve essere ospitato su HTTPS e il file robots.txt deve consentire a UserAgent:Google-Valuables di accedere al percorso dell'URL.

Lo stato di attivazione viene memorizzato nell'oggetto utilizzando il campo activationStatus. Gli stati validi includono NOT_ACTIVATED e ACTIVATED. L'endpoint di attivazione deve aggiornare l'oggetto con lo stato ACTIVATED e garantire che l'oggetto abbia informazioni di utilizzo valide, come un codice a barre o parametri di ispezione visiva. Il campo deviceContext può essere utilizzato per il blocco del dispositivo.

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
Campo Descrizione
activationStatus

enum (ActivationStatus)

Stato di attivazione per questo oggetto in transito. Questo stato cambierà la rappresentazione del ticket e consentirà agli utenti di intervenire. Ad esempio, se nei dettagli del ticket viene visualizzato un pulsante Attiva, se questo criterio è impostato su NOT_ACTIVATED.

I valori accettati sono:

  • NOT_ACTIVATED
  • ACTIVATED
deviceContext

object (DeviceContext)

Il contesto del dispositivo a cui associare l'oggetto. Se impostate, le informazioni sull'utilizzo verranno inviate soltanto al dispositivo in questione.
hasLinkedDevice

boolean

Indica se questo oggetto è attualmente collegato a un singolo dispositivo.
DeviceContext
Campo Descrizione
deviceToken

string

Se impostate, le informazioni sull'utilizzo verranno restituite al dispositivo in questione soltanto al momento dell'attivazione dell'oggetto. Non può essere utilizzato come identificatore stabile per tracciare il dispositivo di un utente. Può cambiare nei diversi pass per lo stesso dispositivo o anche tra attivazioni diverse per lo stesso dispositivo. Quando questa impostazione viene configurata, i chiamanti devono anche impostare hasLinkedDevice per l'oggetto in fase di attivazione.

Tieni presente che deviceToken viene ricevuto dal campo deviceContext dei parametri di attivazione

Blocco dispositivo

Il blocco dispositivo è una funzionalità che consente a un utente di attivare il ticket su un dispositivo e di visualizzare le informazioni sull'utilizzo dei biglietti solo su quel dispositivo. È separato da multipleDevicesAndHoldersAllowedStatus di ONE_USER_ONE_DEVICE, che consente di visualizzare i biglietti solo su un singolo dispositivo. Ti consigliamo di utilizzare lo stato ONE_USER_ALL_DEVICES con il dispositivo bloccato.

Prima dell'attivazione, l'utente può visualizzare il biglietto e attivare il pulsante su qualsiasi dispositivo di sua proprietà. Una volta attivato e bloccato su un dispositivo, il dispositivo bloccato mostrerà le informazioni sull'utilizzo, mentre sugli altri dispositivi verrà mostrato un pulsante di attivazione per consentire all'utente di spostare il biglietto su un altro dispositivo. Se lo spostamento del ticket non è desiderato, ma l'attivazione su qualsiasi dispositivo lo è, è possibile aggiornarlo su ONE_USER_ONE_DEVICE durante l'attivazione anziché utilizzare il blocco sul dispositivo.

Per implementare il blocco del dispositivo, l'oggetto deve essere aggiornato con il campo deviceToken ricevuto con i parametri di attivazione e impostando hasLinkedDevice su true nella stessa chiamata API. Se vuoi, il ticket può essere scollegato da un dispositivo impostando hasLinkedDevice su false in una chiamata API futura.

diagramma di sequenza per il blocco del dispositivo

Parametri di attivazione

La richiesta all'endpoint di attivazione conterrà i seguenti parametri.

Esempio JSON: 

  {
    classId: “123.classId”,
    objectIds: [ “123.objectId” ],
    expTimeMillis: 1669671940735,
    eventType: “activate”,
    nonce: “1c6fccce-6f66-11ed-a1eb-0242ac120002”,
    deviceContext: “6fba937a-6f6e-11ed-a1eb-0242ac120002”
  }

Identificatore Descrizione
classId

ID del corso completo. Utilizza il seguente formato:

<issuer_id.class_id>
objectIds

Array completo di ID oggetto che utilizzano il seguente formato:

<issuer_id.object_id>
expTimeMillis Tempo di scadenza in millisecondi dall'EPOCH. Dopo la scadenza, il messaggio deve essere considerato non valido.
eventType Sempre "activate".
nonce Non tenere traccia di eventuali pubblicazioni duplicate.
deviceContext

Un ID univoco generato da Google che rappresenta il dispositivo su cui l'utente sta eseguendo un'azione. Questo ID deve essere utilizzato per gli aggiornamenti che associano un oggetto a un dispositivo.

Questo ID potrebbe non essere costante per le richieste future da un determinato dispositivo.