Automatisch verknüpfte Karten/Tickets

Hintergrund

Mit der Funktion „Automatisch verknüpfte Karten/Tickets“ kannst du zusätzliche Karten/Tickets an einen Nutzer senden, der deine vorhandenen Karten/Tickets bereits in Google Wallet hat. Du kannst Karten/Tickets auch vorab mit primären Karten/Tickets verknüpfen, wenn ein Nutzer die primäre (Hauptkarte) speichert. Die automatisch verknüpfte Karte bzw. das automatisch verknüpfte Ticket wird zusammen mit der primären Karte bzw. dem primären Ticket mit einem Hinweis über der primären Karte bzw. dem primären Ticket gruppiert, der den 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

Anwendungsbereiche

Möglicherweise gibt es unterschiedliche Anwendungsfälle für das Verknüpfen von Karten/Tickets mit vorhandenen Karten/Tickets. Hier einige Beispiele:

  • Angebot mit einer vorhandenen Kundenkarte verknüpfen.
  • Verknüpfe einen Essensgutschein mit einer Bord- oder Veranstaltungskarte.
  • Parkschein mit einem Veranstaltungsticket verknüpfen.

Einige Überlegungen bei der Verwendung von automatisch verknüpften Karten/Tickets

  • Das primäre Objekt und das verknüpfte Objekt müssen dieselbe Aussteller-ID haben.
  • Pro primäres Objekt können maximal 50 verknüpfte Objekte verwendet werden.
  • Das automatische Senden verknüpfter Karten/Tickets ist nicht garantiert und gilt nicht als Best-Effort. Nutzer können den Erhalt automatisch verknüpfter Karten/Tickets deaktivieren. 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 der Nutzer die Karte bzw. das Ticket hinzufügt.
  • Die Aktualisierungen der Richtlinien zur Fairen Nutzung für Google Wallet enthalten eine Anleitung zur Verwendung von automatisch verknüpften Karten/Tickets, die eingehalten werden müssen.

Integrationsschritte

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

  1. Erstelle ein Objekt eines beliebigen Karten-/Tickettyps, der mit den erforderlichen Parametern aufgeführt ist. 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 entweder 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 dielinkedObjectIds für einen 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 nach dem Verknüpfen eines Objekts mit einem Karten-/Ticketobjekt

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

Erwartetes Verhalten

Nach einer erfolgreichen Antwort sollten die Geräte mit der aktualisierten Karte bzw. dem aktualisierten Ticket die verknüpfte Karte bzw. das verknüpfte Ticket erhalten. Diese verknüpfte Karte bzw. dieses verknüpfte Ticket wird zusammen mit der primären Karte bzw. dem primären Ticket gruppiert. Wischen Sie nach rechts, um die verknüpfte Karte bzw. das verknüpfte Ticket aufzurufen.

Ausnahmebehandlung

Mögliche Fehler können durch eine falsche Verwendung der API entstehen. Dazu gehören:

Nachricht Grund
Das primäre Objekt und das verknüpfte Objekt haben nicht dieselbe Aussteller-ID. Du kannst ein verknüpftes Objekt nicht an das Objekt eines anderen Ausstellers anhängen.
Das primäre Objekt und das verknüpfte Objekt beziehen sich auf dasselbe Objekt. Sie können nicht dasselbe Objekt wie das „linkedObject“ anhängen.
Verknüpftes Objekt 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 weiteres verknüpftes Objekt haben.
Objekt ist bereits mit einem anderen Objekt verknüpft. Verschachtelte verknüpfte Objekte können nicht hinzugefügt werden. Ein primäres Objekt kann kein verknüpftes Objekt sein.
Es können keine weiteren verknüpften Objekte hinzugefügt werden. Das Limit wurde überschritten. Das Limit von 50 verknüpften Karten/Tickets wurde für die primäre Karte / das primäre Ticket erreicht.