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.

Hinweise zur Verwendung automatisch verknüpfter Karten/Tickets

• Das primäre Objekt und das verknüpfte Objekt müssen dieselbe Aussteller-ID verwenden.
• 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. Das 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“.

Zum Festlegen der verknüpftenObjectIds auf einer primären Karte bzw. einem primären Ticket ist eine Mindestnutzlast erforderlich. 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 nach dem Verknüpfen eines Objekts mit einem Karten-/Ticketobjekt

  …
  "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. Verschachtelte verknüpfte Objekte können nicht 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.