Überblick

Mit der Google Wallet Passes API können Partner einen Endpunkt für die Aktivierung einer Fahrkarte angeben. Wenn eine Aktivierung erforderlich ist, wird dem Nutzer die Schaltfläche „Aktivieren“ angezeigt. Durch Antippen wird der angegebene Endpunkt mit den unten beschriebenen Parametern aufgerufen. Der Endpunkt muss dafür sorgen, dass vor der Rückgabe gültige Einlösungsinformationen (entweder Barcode oder visuelle Kontrolle) der Karte bzw. des Tickets vorliegen. Dann wird die Karte bzw. das Ticket im Wallet des Nutzers mit den Einlösungsinformationen aktualisiert. Beachten Sie, dass vor der Aktivierung keine Informationen zur Einlösung angezeigt werden.

Aktivierungs-API

Der Aktivierungsendpunkt wird in der API mit activationOptions in der Verkehrsklasse angegeben. Der Partner ist für die Aufrechterhaltung eines funktionierenden Aktivierungsendpunkts mit angemessener Latenz verantwortlich.

  activationOptions: {
    activationUrl: string
  }
Field Beschreibung
activationUrl

string

URL für den Partnerendpunkt, der für Aktivierungsanfragen aufgerufen wird. Die URL sollte auf HTTPS gehostet werden und robots.txt muss zulassen, dass der URL-Pfad für UserAgent:Google-Valuables zugänglich ist.

Der Aktivierungsstatus wird für das Objekt im Feld activationStatus gespeichert. Gültige Statuswerte sind NOT_ACTIVATED und ACTIVATED. Der Aktivierungsendpunkt sollte das Objekt mit dem Status ACTIVATED aktualisieren und prüfen, ob das Objekt gültige Einlösungsinformationen wie einen Barcode oder visuelle Prüfparameter aufweist. Das Feld deviceContext kann zum Zurückstellen von Geräten verwendet werden.

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
Field Beschreibung
activationStatus

enum (ActivationStatus)

Aktivierungsstatus für dieses Verkehrsobjekt. Durch diesen Status wird die Darstellung des Tickets geändert und Nutzer können Aktionen ausführen. Beispiel: Die Schaltfläche „Aktivieren“ wird in den Ticketdetails gerendert, wenn NOT_ACTIVATED festgelegt ist.

Akzeptable Werte sind:

  • NOT_ACTIVATED
  • ACTIVATED
deviceContext

object (DeviceContext)

Ein Gerätekontext, mit dem das Objekt verknüpft werden soll. Wenn festgelegt, werden Einlösungsinformationen nur an das angegebene Gerät zurückgegeben.
hasLinkedDevice

boolean

Gibt an, ob dieses Objekt derzeit mit einem einzelnen Gerät verknüpft ist.
DeviceContext
Field Beschreibung
deviceToken

string

Wenn festgelegt, werden Einlösungsinformationen nur bei Aktivierung des Objekts an das angegebene Gerät zurückgegeben. Sie kann nicht als stabile Kennung zum Nachverfolgen des Geräts eines Nutzers verwendet werden. Sie kann sich bei verschiedenen Karten/Tickets für dasselbe Gerät oder sogar bei verschiedenen Aktivierungen für dasselbe Gerät ändern. Bei dieser Einstellung müssen Aufrufer hasLinkedDevice für das zu aktivierende Objekt festlegen.

Beachten Sie, dass deviceToken aus dem Feld deviceContext der Aktivierungsparameter erhalten wird

Geräteverknüpfung

Die Geräteverknüpfung ist eine Funktion, mit der Nutzer das Ticket auf einem Gerät aktivieren können. Die Informationen zum Einlösen von Tickets werden dann nur auf diesem Gerät angezeigt. Dies unterscheidet sich vom multipleDevicesAndHoldersAllowedStatus von ONE_USER_ONE_DEVICE, bei dem das Ticket nur auf einem einzelnen Gerät angezeigt werden kann. Es wird empfohlen, den Status ONE_USER_ALL_DEVICES beim Verknüpfen von Geräten zu verwenden.

Vor der Aktivierung kann der Nutzer das Ticket und die Schaltfläche „Aktivieren“ auf jedem Gerät sehen. Nach der Aktivierung und der Verknüpfung mit einem Gerät werden auf dem angepinnten Gerät Einlösungsinformationen angezeigt. Auf anderen Geräten wird eine Aktivierungsschaltfläche angezeigt, über die der Nutzer das Ticket auf ein anderes Gerät verschieben kann. Wenn die Funktion zum Verschieben des Tickets nicht erwünscht ist, die Aktivierung auf einem beliebigen Gerät hingegen schon, kann das Ticket während der Aktivierung auf ONE_USER_ONE_DEVICE aktualisiert werden, anstatt die Geräteverknüpfung zu verwenden.

Zum Implementieren der Geräteverknüpfung sollte das Objekt mit dem Feld deviceToken aktualisiert werden, das mit den Aktivierungsparametern empfangen wird, und hasLinkedDevice sollte im selben API-Aufruf auf „true“ gesetzt werden. Bei Bedarf kann die Verknüpfung des Tickets mit einem Gerät aufgehoben werden, indem hasLinkedDevice in einem zukünftigen API-Aufruf auf „false“ gesetzt wird.

Sequenzdiagramm für Geräteverknüpfung

Aktivierungsparameter

Die Anfrage an den Aktivierungsendpunkt enthält die folgenden Parameter.

JSON-Beispiel: 

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

Kennung Beschreibung
classId

Voll qualifizierte Klassen-ID. Verwendet das folgende Format:

<issuer_id.class_id>
objectIds

Voll qualifiziertes Array von Objekt-IDs im folgenden Format:

<issuer_id.object_id>
expTimeMillis Ablaufzeit in Millisekunden seit EPOCH. Danach muss die Nachricht als ungültig eingestuft werden.
eventType Immer "activate".
nonce Nonce zur Nachverfolgung von doppelten Übermittlungen.
deviceContext

Eine eindeutige ID, die von Google generiert wird und das Gerät darstellt, auf dem der Nutzer aktiv wird. Diese ID sollte bei Aktualisierungen verwendet werden, die ein Objekt mit einem Gerät verknüpfen.

Diese ID ist möglicherweise für zukünftige Anfragen von einem bestimmten Gerät nicht konstant.