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 einem Hauptkarten/-ticket verknüpfen, wenn ein Nutzer das Hauptkarten/-ticket speichert. Die automatisch verknüpfte Karte/das automatisch verknüpfte Ticket wird mit der primären Karte/dem primären Ticket gruppiert. Über der primären Karte/dem primären Ticket wird der Nutzer darüber informiert, dass eine neue Karte/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

Primäre Karte/Ticket mit dem Callout, dass eine neue Karte bzw. 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.

Überlegungen bei der 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äres 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 bzw. das verknüpfte Ticket erhalten muss, empfehlen wir, über einen anderen Kanal zu kommunizieren, damit er die Karte bzw. 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 einer beliebigen Karten-/Ticketart, die mit den erforderlichen Parametern aufgeführt ist. Dies ist das primäre Objekt.
2. Erstelle ein weiteres Objekt eines beliebigen aufgeführten Karten-/Tickettyps. Dies ist das verknüpfte Objekt.
3. Aktualisieren Sie das primäre Objekt entweder vor oder nach dem Speichern mit der ID des verknüpften Objekts im Parameter „linkedObjectIds“.

Es ist eine Mindestnutzlast erforderlich, um die linkedObjectIds auf einem primären Ausweis festzulegen. Zu den drei erforderlichen Parametern gehören:

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

Nach Erhalt einer erfolgreichen Antwort 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 kein verknüpftes Objekt 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 wie "linkedObject" anhängen.
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 dürfen 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.