Dettagli tecnici per i ticket Motics in Google Wallet

In questa pagina vengono forniti i dettagli tecnici di un Operatore di trasporto pubblico (PTO) e il suo integratore di sistemi deve integrarsi con Google per fornire ticket di Motics in Google Wallet. La soluzione utilizza l'API Google Wallet e si basa anche sulla PTO che implementa un endpoint di attivazione.

Architettura di sistema

Questa sezione mostra l'architettura di sistema e il flusso di salvataggio di Motics.

Flusso di salvataggio del ticket Motics Figura 1. Flusso di salvataggio del ticket Motics

La figura 1 mostra il flusso per creare, attivare e bloccare un ticket Motics nella Google Wallet, in diverse entità:

  • Server Google
  • Server PTO (System Integrator)
  • Server SCE Motics
  • Web shop

Di seguito viene descritto il flusso in modo più dettagliato:

  1. Nella fase di configurazione iniziale, il server PTO crea transitClass, passando ownerId e activationUrl utilizzando transitClass:Insert Endpoint API Google Wallet. Si tratta di un'attività una tantum.
  2. Successivamente, quando un utente acquista un biglietto dal web shop, il server PTO chiama transitObject:Insert contenenti informazioni di base sulla vendita di ticket e alcune campi iniziali indicanti che si tratta di un ticket Motics.
  3. Quindi il server PTO e il web shop lavorano insieme per eseguire il rendering Aggiungi a Google Wallet e, infine, restituisci il JWT del biglietto a Google utilizzando il link Salva.
  4. Ora può iniziare la fase di blocco dei ticket, quando il server di Google chiama Endpoint di attivazione dietro activationUrl.
  5. In risposta al passaggio 4, il server PTO genera la firma (sigSTB) contenente lo SCE_ID firmato con il SAM.
  6. Prima di rispondere alla chiamata activationUrl, il server PTO deve chiama transitObject:Patch contenente tutte le informazioni Motics necessarie, tra cui applicationData di Motics.
  7. Solo dopo l'esito positivo della chiamata a transitObject:Patch, la PTO dovrebbe restituire una risposta di operazione riuscita (HTTP-200) a activationUrl chiamata.

Per offrire una buona esperienza utente, un utente deve essere in grado di spostare il proprio componente da un dispositivo all'altro, entro i limiti stabiliti dall'emittente. Per farlo, l'emittente deve implementare il flusso di trasferimento e scollegamento.

Endpoint di attivazione

L'emittente/la PTO (o il suo integratore di sistemi) deve implementare un ticket endpoint di attivazione che Google richiama quando il ticket viene salvato. URL a questo endpoint deve essere fornito nella chiamata a transitClass:Insert. L'endpoint di attivazione genererà la firma (sigSTB) e chiamerà il transitObject:Patch con i parametri definiti di seguito .

Richiesta

La richiesta all'endpoint di attivazione ha il seguente formato:

Content-Type: application/json
Body: {
  "classId": "123.classId",
  "expTimeMillis": 1669671940735,
  "eventType": "activate",
  "objectId": string - base64 encoded ID of the TransitObject,
  "deviceContext": string - base64 encoded SCE_ID,
}

Risposta

Una risposta positiva HTTP-200 con un corpo vuoto deve essere restituita se:

  • Il sigSTB contenente SCE_ID è stato generato e firmato con il SAM
  • Il metodo transitObject:Patch è stato chiamato
Status: 200 - OK
Body: {}

Destinazioni di latenza

L'endpoint di attivazione deve rispettare i seguenti target di latenza:

  • Almeno 50% di tutte le richieste deve ricevere risposte entro 200ms
  • Almeno 95% di tutte le richieste deve ricevere risposte entro 2s
  • Esiste un limite superiore fisso di 10s

Modifiche all'API Google Wallet

Di seguito vengono descritte le modifiche agli endpoint dell'API Google Wallet al fine di: per supportare Motics come descritto nell'architettura del sistema.

Metodo: transitClass:insert

Questo è l'endpoint dell'API Google Wallet per creare un transitClass su di un backend cloud. L'integratore di sistema deve richiamare questa API con quanto segue parametri di richiesta insieme a tutti gli altri campi applicabili. Consulta transitClass e documentazione dell'API transitClass.Insert per un elenco completo (non-Motics) e altri dettagli.

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitClass

Rappresentazione JSON

L'integrazione di Motics richiede almeno la seguente rappresentazione JSON di transitClass nel corpo della richiesta transitClass:insert. Altro obbligatorio Dovrai impostare anche i campi di metadati transitClass.

{
  "id": string,
  "multipleDevicesAndHoldersAllowedStatus": ONE_USER_ONE_DEVICE (MultipleDevicesAndHoldersAllowedStatus),
  "deviceCertificationSupport": {
     "vdvCertDetails": {
        "ownerId" string,
        "certEnvironment": PRODUCTION/STAGING,
      },
  },
  "activationOptions": {
    "activationUrl": string
  },
  ...
}

Quando certEnvironment = PRODUCTION il server di Google recupera il certificato dal server Motics di produzione. Quando certEnvironment = STAGING del Google recupererà il certificato dal server sandbox Motics.

Metodo: transitObject:insert

Questo è l'endpoint dell'API Google Wallet per inserire il transitObject per il nuovo biglietto che un utente vuole acquistare e aggiungere a Google Wallet. Il sistema l'integratore deve trasmettere un valore transitObject con principalmente le informazioni del ticket su a questo punto. Fai riferimento a transitObject & API transitObject.Insert documentazione per un elenco completo dei parametri (non-Motics) e ulteriori dettagli.

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitObject

Rappresentazione JSON

L'integrazione di Motics richiede almeno la seguente rappresentazione JSON di transitObject nel corpo della richiesta transitObject:insert. Altro oggetto possono essere impostati anche i campi dei metadati e tutti gli altri campi obbligatori devono essere inclusi.

{
  "id": string,
  "classId": string,
  "validTimeInterval": {
    object (TimeInterval)
  },
  "activationStatus": {
    "state": NOT_ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": "",
      },
    },
  },
  ...
}

Note:

  • L'API richiede che sia incluso il campo applicationData. A questo punto nel flusso di attivazione di Motics, il valore applicationData non è ancora noto, quindi deve essere impostato su una stringa vuota.
    • Il applicationData verrà impostato in un secondo momento in transitObject:Patch chiamata.
  • Gli oggetti DateTime validTimeInterval devono avere lo scarto del fuso orario specificato, ad esempio: 2024-04-12T19:20:50.52-04:00.

Metodo: transitObject:patch

Questo è l'endpoint dell'API Google Wallet per la patch del transitObject con dati da utilizzato da Google per la generazione del codice a barre Motics e per il recupero del servizio eTicket VDV certificati. Fai riferimento a transitObject & API transitObject.Patch documentazione per un elenco completo dei parametri (non-Motics) e ulteriori dettagli.

PATCH:
https://walletobjects.googleapis.com/walletobjects/v1/transitObject/{resourceId}

Rappresentazione JSON

L'integrazione di Motics richiede la seguente rappresentazione dei transitObject nel corpo della richiesta transitObject:patch. Nota che è in questo punto indica che il campo applicationData è compilato.

{
  "activationStatus": {
    "state": ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": string - Hex encoded,
      },
    },
  }
}

Specifiche dei dati applicazione

Di seguito è riportata la specifica Motics per i contenuti dei file applicationData (tag:0x5F07). applicationData deve essere generato l'integratore di sistema nel formato TLV (Tag-length-Value). Questi dati sono successivi incapsulati in una struttura di dati più ampia per essere finalmente codificati come parte del QR le API nel tuo codice.

Tag Lunghezza Valore
0x9E 81:80 Firma
OctetString, primi 128 byte di dati relativi ai diritti firmati
Termine Google: sigSTB
0x9A Variabile Dati residui
OctetString, dati dei diritti residui
Termine Google: sigSTB cont.
0x7F21 81 C8 Certificato dell'emittente
OctetString, dati del certificato
Termine Google: Cert(puk_SAM)
0x42 08 Riferimento dell'autorità di certificazione (CAR)
OctetString, valore CAR
Termine Google: CAR