Automatisch verknüpfte Karten/Tickets

Hintergrund

Mit der Funktion „Automatisch verknüpfte Karten/Tickets“ können Sie einem Nutzer, der Ihre Karte bzw. Ihr Ticket bereits in Google Wallet hat, zusätzliche Karten/Tickets senden. Du kannst Karten/Tickets auch vorab mit einer primären Karte bzw. einem primären Ticket verknüpfen, wenn ein Nutzer die primäre (Haupt-)Karte speichert. Die automatisch verknüpfte Karte bzw. das verknüpfte Ticket wird mit der primären Karte bzw. dem primären Ticket gruppiert. Über der primären Karte bzw. dem primären Ticket wird der Nutzer darüber informiert, dass eine neue Karte bzw. ein neues Ticket verknüpft wurde. Die folgenden Karten-/Tickettypen werden als primäre oder verknüpfte Karten/Tickets unterstützt:

• Veranstaltungstickets
• Bordkarte
• Fahrkarte
• Angebot
• Geschenkkarte
• Kundenkarte
• Generische Karten/Tickets

Hauptkarte/-ticket mit dem Zusatz, dass eine neue Karte/ein neues Ticket hinzugefügt wurde	Neue Karte/neues Ticket, das mit der primären Karte/dem primären Ticket verknüpft ist

Anwendungsfälle

Es gibt verschiedene Anwendungsfälle für die Verknüpfung von Karten/Tickets mit einer vorhandenen Karte/einem vorhandenen Ticket. Hier einige Beispiele:

• Verknüpfen Sie ein Angebot mit einer vorhandenen Kundenkarte.
• Verknüpfen Sie einen Essensgutschein mit einer Bordkarte oder einem Veranstaltungsticket.
• Verknüpfen Sie einen Parkschein mit einem Veranstaltungsticket.

Hinweise zur Verwendung automatisch verknüpfter Karten/Tickets

• Für das primäre Objekt und das verknüpfte Objekt muss dieselbe Aussteller-ID verwendet werden.
• Pro primärem Objekt sind maximal 50 verknüpfte Objekte zulässig.
• Das automatische Senden verknüpfter Karten/Tickets kann nicht garantiert werden und gilt als Best-Effort-Verfahren. Nutzer können festlegen, dass sie keine automatisch verknüpften Karten/Tickets mehr erhalten. Wenn der Anwendungsfall kritisch ist und der Nutzer die verknüpfte Karte/das verknüpfte Ticket erhalten muss, empfehlen wir, über einen anderen Kanal zu kommunizieren, damit der Nutzer die Karte/das Ticket hinzufügt.
• Die Aktualisierungen der Google Wallet-Nutzungsbedingungen enthalten Hinweise zur Verwendung automatisch verknüpfter Karten/Tickets, die befolgt werden müssen.

Integrationsschritte

Wenn Sie bereits ein primäres Objekt erstellt haben, können Sie Schritt 1 überspringen.

1. Erstelle ein Objekt eines der aufgeführten Karten-/Tickettypen mit den erforderlichen Parametern. Dies ist das primäre Objekt.
2. Erstellen Sie ein weiteres Objekt eines der aufgeführten Karten-/Tickettypen. Dies ist das verknüpfte Objekt.
3. Aktualisieren Sie das primäre Objekt vor oder nach dem Speichern des primären Objekts mit der ID des verknüpften Objekts im Parameter „linkedObjectIds“.

Es ist eine Mindestnutzlast erforderlich, um die linkedObjectIds auf einem primären Ausweis festzulegen. Die drei erforderlichen Parameter sind:

1. ISSUERID.PRIMARY_OBJECT_ID
2. ISSUERID.PRIMARY_CLASS_ID
3. ISSUERID.LINKED_OBJECT_ID

Beispiel für eine JSON-Anfrage zum Hinzufügen eines verknüpften Objekts zu einem Karten-/Ticketobjekt

  …
  {
    "id": "ISSUERID.PASS_OBJECTID",
    "classId": "ISSUERID.PASS_CLASSID",
    "barcode": {
      "type": "qrCode",
      "value": "QR code"
    },
    "linkedObjectIds": {"ISSUERID.LINKED_PASS_OBJECTID"}
  }
  …

Beispiel für eine JSON-Antwort, nachdem ein Objekt mit einem Karten-/Ticketobjekt verknüpft wurde

  …
  "state": "active",
  "linkedObjectIds": {
    "ISSUERID.LINKED_PASS_OBJECTID"
  }
  …

Erwartetes Verhalten

Nachdem Sie eine erfolgreiche Antwort erhalten haben, sollten Geräte mit der aktualisierten Karte bzw. dem aktualisierten Ticket die verknüpfte Karte bzw. das verknüpfte Ticket erhalten. Dieser verknüpfte Ausweis wird mit dem Hauptausweis gruppiert. Nutzer können den verknüpften Ausweis aufrufen, indem sie nach rechts wischen.

Ausnahmebehandlung

Bei falscher Verwendung der API können folgende Fehler auftreten:

Botschaft	Grund
Primäres Objekt und verknüpftes Objekt haben nicht dieselbe Aussteller-ID.	Sie können ein verknüpftes Objekt nicht an das Objekt eines anderen Ausstellers anhängen.
Primäres Objekt und verknüpftes Objekt beziehen sich auf dasselbe Objekt.	Sie können nicht dasselbe Objekt anhängen wie das verknüpfte Objekt.
Das verknüpfte Objekt ist nicht vorhanden.	Das verknüpfte Objekt sollte bereits in die Wallet API eingefügt sein.
Das verknüpfte Objekt hat bereits ein anderes verknüpftes Objekt. Es können keine verschachtelten verknüpften Objekte hinzugefügt werden.	Verknüpfte Objekte können kein anderes verknüpftes Objekt haben.
Das Objekt ist bereits mit einem anderen Objekt verknüpft. Verschachtelte verknüpfte Objekte können nicht hinzugefügt werden.	Das primäre Objekt kann kein verknüpftes Objekt sein.
Es können keine weiteren verknüpften Objekte hinzugefügt werden, das Limit wurde überschritten.	Für die Hauptkarte/den Hauptfahrschein wurde das Limit von 50 verknüpften Karten/Fahrscheinen erreicht.