Übersicht

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 dieser Schaltfläche wird der angegebene Endpunkt mit den unten beschriebenen Parametern aufgerufen. Der Endpunkt muss prüfen, ob das Ticket gültige Einlösungsinformationen hat (entweder Barcode oder visuelle Kontrolle), bevor es zurückgegeben wird. Die Karte bzw. das Ticket wird dann im Wallet des Nutzers mit den Einlösungsinformationen aktualisiert. Beachten Sie, dass vor der Aktivierung keine Informationen zur Einlösung angezeigt werden.

Activation 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
  }
Feld 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 muss das Objekt mit dem Status ACTIVATED aktualisieren und prüfen, ob das Objekt gültige Einlösungsinformationen wie einen Barcode oder visuelle Kontrollparameter aufweist. Das Feld deviceContext kann zum Verknüpfen von Geräten verwendet werden.

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
Feld 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
Feld Beschreibung
deviceToken

string

Wenn festgelegt, werden Einlösungsinformationen nur bei Aktivierung des Objekts an das angegebene Gerät zurückgegeben. Dies kann nicht als stabile Kennung verwendet werden, um das Gerät eines Nutzers nachzuverfolgen. Es kann bei den verschiedenen Karten/Tickets für dasselbe Gerät oder sogar bei verschiedenen Aktivierungen für dasselbe Gerät variieren. 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

Das Verknüpfen von Geräten ist eine Funktion, mit der Nutzer das Ticket auf einem bestimmten 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 des „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 allen Geräten sehen. Nach der Aktivierung und der Verknüpfung mit einem Gerät werden auf dem verknüpften Gerät Einlösungsinformationen angezeigt. Auf den anderen Geräten wird die Schaltfläche „Aktivieren“ 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 gleichen API-Aufruf auf „true“ gesetzt werden. Bei Bedarf kann die Verknüpfung des Tickets mit einem Gerät aufgehoben werden. Setzen Sie dazu bei einem zukünftigen API-Aufruf hasLinkedDevice auf „false“.

Sequenzdiagramm zum Verknüpfen von Geräten

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

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