Technische Details zu Motics-Tickets in Google Wallet

Diese Seite enthält die technischen Details zu einem öffentlichen Verkehrsunternehmen und Der Systemintegrator muss eine Verknüpfung mit Google herstellen, um Motics-Tickets anbieten zu können. in Google Wallet. Die Lösung nutzt die Google Wallet API und auf dem öffentlichen Verkehrsunternehmen einen Aktivierungsendpunkt implementiert.

Systemarchitektur

In diesem Abschnitt werden die Systemarchitektur und der Motics-Speichervorgang erläutert.

Abbildung 1. Motics Ticket-Rabatt

Abbildung 1 zeigt den Ablauf zum Erstellen, Aktivieren und Anpinnen eines Motics-Tickets in Google Wallet für verschiedene Rechtssubjekte:

• auf Google-Servern
• Betreiberserver (System Integrator)
• Motics-SCE-Server
• Web-Shop

Im Folgenden wird der Ablauf ausführlicher beschrieben:

1. In der Ersteinrichtungsphase erstellt der Server des öffentlichen Verkehrsunternehmens die transitClass, Übergeben von ownerId und activationUrl mithilfe von transitClass:Insert Google Wallet API-Endpunkt. Dies ist eine einmalige Aktivität.
2. Wenn ein Nutzer als Nächstes ein Ticket im Webshop kauft, ruft der Server des Verkehrsverbunds transitObject:Insert grundlegende Fahrkarteninformationen und einige gibt an, dass es sich um ein Motics-Ticket handelt.
3. Dann arbeiten der Server des öffentlichen Verkehrsunternehmens und der Webshop zusammen, um den Schaltfläche „Zu Google Wallet hinzufügen“ und gibt schließlich das JWT des Tickets an Google über den Link „Speichern“.
4. Jetzt kann die Ticket-Pinierungsphase beginnen, wenn der Google-Server die Aktivierungsendpunkt hinter dem activationUrl.
5. Als Antwort auf Schritt 4 generiert der Server des öffentlichen Verkehrsunternehmens die Signatur (sigSTB). das die vom SAM unterzeichnete SCE_ID enthält.
6. Bevor auf den activationUrl-Aufruf geantwortet wird, sollte der Server des öffentlichen Verkehrsunternehmens zuerst Rufen Sie transitObject:Patch mit allen erforderlichen Motics-Informationen auf. einschließlich applicationData von Motics.
7. Erst nachdem der Aufruf von transitObject:Patch erfolgreich war, muss der Verkehrsverbund Der Server sollte eine HTTP-200-Antwort an den activationUrl zurückgeben. anrufen.

Implementieren und Vorgang zum Aufheben der Verknüpfung

Für eine gute Nutzererfahrung sollten Nutzende in der Lage sein, ihre Motics zu bewegen. Ticket von einem Gerät zum anderen innerhalb bestimmter, vom Aussteller festgelegter Einschränkungen. Dazu muss der Aussteller den Vorgang zum Verschieben und Aufheben der Verknüpfung implementieren.

Aktivierungsendpunkt

Der Aussteller/Öffentliche Verkehrsunternehmen (oder sein Systemintegrator) muss ein Ticket implementieren. Aktivierungsendpunkt, den Google beim Speichern des Tickets aufruft. URL zu diesem Endpunkt im Aufruf von transitClass:Insert bereitgestellt werden. Der Aktivierungsendpunkt generiert die Signatur (sigSTB) und ruft die Methode transitObject:Patch mit den im Folgenden definierten Parametern .

Wichtig: Der Server des Verkehrsverbunds (Systemintegrator) muss transitObject:Patch aufrufen. bevor sie vom Aktivierungsendpunkt zurückgegeben werden.

Anfrage

Die Anfrage an den Aktivierungsendpunkt hat das folgende Format:

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

Antwort

Eine HTTP-200-Erfolgsantwort mit einem leeren Textkörper sollte in folgenden Fällen zurückgegeben werden:

• Die sigSTB mit SCE_ID wurde generiert und vom SAM signiert
• Die Methode "transitObject:Patch" wurde aufgerufen.

Status: 200 - OK
Body: {}

Latenzziele

Der Aktivierungsendpunkt sollte die folgenden Latenzziele einhalten:

• Mindestens 50% aller Anfragen sollten innerhalb von 200ms beantwortet werden
• Mindestens 95% aller Anfragen sollten innerhalb von 2s beantwortet werden
• Es besteht eine feste Obergrenze von 10s

Änderungen an der Google Wallet API

Im Folgenden werden die Änderungen an den Google Wallet API-Endpunkten beschrieben, um unterstützen Motics wie in der Systemarchitektur beschrieben.

Wichtig :Im Folgenden wird davon ausgegangen, dass Sie bereits eine Standard- Integration der Google Wallet API Nur die Aktualisierungen und Änderungen an den Endpunkten unterstützt Motics hier.

Methode: transitClass:insert

Dies ist der Google Wallet API-Endpunkt zum Erstellen eines transitClass auf der von Google Back-End. Der Systemintegrator muss diese API mit dem folgenden Befehl aufrufen: Anfrageparameter zusammen mit allen anderen anwendbaren Feldern an. Weitere Informationen finden Sie unter transitClass und transitClass.Insert in der API-Dokumentation. Dort finden Sie eine vollständige Liste der (non-Motics) Parameter und weitere Details.

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

JSON-Darstellung

Für die Motics-Integration ist mindestens die folgende JSON-Darstellung von den transitClass im transitClass:insert-Anfragetext. Sonstige obligatorische transitClass-Metadatenfelder müssen ebenfalls festgelegt werden.

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

Wenn certEnvironment = PRODUCTION ist, ruft der Google-Server das Zertifikat ab vom Motics-Produktionsserver. Wenn certEnvironment = STAGING the Google das Zertifikat vom Sandbox Motics-Server abruft.

Methode: transitObject:insert

Dies ist der Google Wallet API-Endpunkt zum Einfügen der transitObject für das neue Ticket, das ein Nutzer kaufen und zu Google Wallet hinzufügen möchte. Das System Der Integrator sollte eine transitObject übergeben, die hauptsächlich die Ticketinformationen enthält. Punkt zu kommen. Weitere Informationen finden Sie im Abschnitt zu transitObject und API transitObject.Insert Dokumentation finden Sie eine vollständige Liste der (nicht Motics) Parameter und weitere Details.

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

JSON-Darstellung

Für die Motics-Integration ist mindestens die folgende JSON-Darstellung von den transitObject im transitObject:insert-Anfragetext. Anderes Objekt Metadatenfelder können ebenfalls festgelegt werden. Alle anderen Pflichtfelder sollten ebenfalls enthalten.

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

Hinweise:

• Für die API muss das Feld applicationData enthalten sein. An dieser Stelle im Aktivierungsablauf von Motics ist der applicationData-Wert noch nicht bekannt. Daher muss er auf einen leeren String gesetzt werden.
  • Der applicationData wird später im transitObject:Patch festgelegt anrufen.
• Die validTimeInterval DateTime-Objekte müssen einen Zeitzonenversatz haben angegeben, z. B. 2024-04-12T19:20:50.52-04:00.

Methode: transitObject:patch

Dies ist der Google Wallet API-Endpunkt zum Patchen der transitObject mit zu aktualisierenden Daten wird von Google zur Generierung von Motics-Barcodes und zum Abrufen des VDV eTicket Service verwendet. Zertifikate. Weitere Informationen finden Sie im Abschnitt zu transitObject und API transitObject.Patch Dokumentation finden Sie eine vollständige Liste der (nicht Motics) Parameter und weitere Details.

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

JSON-Darstellung

Für die Motics-Integration ist folgende Darstellung des transitObject im transitObject:patch-Anfragetext. Beachten Sie, dass es sich dass das Feld applicationData mit Daten gefüllt wird.

Hinweis: Der Endpunkt „transitObject:patch“ unterstützt die Patch-Semantik. nur die folgenden Motics-spezifischen Informationen enthalten, wenn Patch wird aufgerufen.

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

Spezifikationen für Anwendungsdaten

Im Folgenden finden Sie die Motics-Spezifikation für den Inhalt des applicationData (Tag:0x5F07). Die applicationData sollte generiert werden durch Systemintegrator im TLV-Format (Tag-Length-Wert) abrufen. Diese Daten sind später in eine größere Datenstruktur gekapselt, damit diese schließlich als Teil des QR-Codes codiert wird Code.

Tag	Länge	Wert
0x9E	81 80	Unterschrift OctetString, die ersten 128 Byte signierter Berechtigungsdaten Google-Begriff: sigSTB
0x9A	Variiert	Restdaten OctetString, verbleibende Berechtigungsdaten Google-Begriff: sigSTB cont.
0x7F21	81 C8	Zertifikat des ausstellenden OctetString, Zertifikatsdaten Google-Begriff: Cert(puk_SAM)
0x42	08	Zertifizierungsstellenreferenz (Certificate Authority Reference, CAR) OctetString, CAR-Wert Google-Begriff: CAR