Fast alle Karten/Tickets, die du für einen Endnutzer zum Speichern in seinem Google Wallet-Konto ausstellen kannst, werden durch zwei Komponenten definiert: eine Karten-/Ticketklasse und ein Karten-/Ticketobjekt. Wenn du eine Karte bzw. ein Ticket für einen Nutzer ausstellst, benötigst du eine Instanz einer Karten-/Ticketklasse und eines Karten-/Ticketobjekts, das der Google Wallet API mitteilt, welche Art von Karte/Ticket erstellt werden soll, sowie Details, die auf der Karte bzw. dem Ticket angezeigt werden sollen, z. B. der Wert einer Geschenkkarte oder der Name eines Ticketinhabers.
Die Google Wallet API bietet einen vordefinierten Satz von Karten-/Ticketklassen und Karten-/Ticketobjekten, für die du Instanzen erstellst. Mit diesen kannst du dann Karten/Tickets erstellen, die für einen Nutzer ausgestellt werden, z. B. GiftCardClass und GiftCardObject, GenericClass und GenericObject.
Jede Instanz der Karten-/Ticketklasse und des Karten-/Ticketobjekts ist als JSON-Objekt mit einer Reihe erforderlicher und optionaler Eigenschaften definiert, die dem spezifischen Anwendungsfall entsprechen, der für diesen Karten-/Tickettyp vorgesehen ist.
Karten-/Ticketklassen
Du kannst dir eine Karten-/Ticketklasse als gemeinsame Vorlage vorstellen, mit der eine oder mehrere Karten/Tickets erstellt werden, die du deinen Nutzern ausstellst. Eine Karten-/Ticketklasse definiert einen gemeinsamen Satz von Eigenschaften, die in allen Karten/Tickets enthalten werden, die darauf verweisen.
Die folgende Instanz von EventTicketClass definiert beispielsweise die Felder, die alle ausgestellten Tickets für eine anstehende Veranstaltung haben(Veranstaltungsort, Veranstaltungsname, Aussteller, Datum/Uhrzeit).
{
"id": "ISSUER_ID.EVENT_CLASS_ID",
"issuerName": "[TEST ONLY] Heraldic Event",
"localizedIssuerName": {
"defaultValue": {
"language": "en-US",
"value": "[TEST ONLY] Heraldic Event"
}
},
"eventName": {
"defaultValue": {
"language": "en-US",
"value": "Google Live"
}
},
"venue": {
"name": {
"defaultValue": {
"language": "en-US",
"value": "Shoreline Amphitheater"
}
},
"address": {
"defaultValue": {
"language": "en-US",
"value": "ADDRESS_OF_THE_VENUE"
}
}
},
"dateTime": {
"start": "2023-04-12T11:30"
},
"reviewStatus": "UNDER_REVIEW"
}
Für jede Instanz einer Karten-/Ticketklasse ist eine id-Eigenschaft erforderlich, die du festlegst. Diese Klassen-ID dient als eindeutige Kennung, auf die du immer dann verweisst, wenn du damit eine neue Instanz des Karten-/Ticketobjekts erstellst.
Karten-/Ticketobjekte
Während eine Instanz einer Karten-/Ticketklasse eine Reihe von gemeinsamen Eigenschaften angibt, die in einer oder mehreren Karten/Tickets verwendet werden sollen, gibt ein Karten-/Ticketobjekt die eindeutigen Details einer bestimmten Karte bzw. eines bestimmten Tickets an, die für einen bestimmten Nutzer ausgestellt wird.
Wenn beispielsweise eine Veranstaltungsticketkarte mit der Google Wallet API erstellt wird, enthält eine EventTicketObject-Instanz Attribute für den Sitz dieses Tickets, da diese Werte für jedes ausgestellte Ticket eindeutig sind.
{
"id": "ISSUER_ID.OBJECT_ID",
"classId": "ISSUER_ID.EVENT_CLASS_ID",
"state": "ACTIVE",
"seatInfo": {
"seat": {
"defaultValue": {
"language": "en-us",
"value": "9"
}
},
"row": {
"defaultValue": {
"language": "en-us",
"value": "L"
}
},
"section": {
"defaultValue": {
"language": "en-us",
"value": "45"
}
},
"gate": {
"defaultValue": {
"language": "en-us",
"value": "7C"
}
}
},
"barcode": {
"type": "BARCODE_TYPE_UNSPECIFIED",
"value": "BARCODE_VALUE",
"alternateText": ""
}
}
Für jede Instanz eines Karten-/Ticketobjekts ist eine von dir angegebene id-Eigenschaft erforderlich. Diese Objekt-ID dient als eindeutige Kennung, auf die du verweisst, wenn du einem Nutzer die Karte bzw. das Ticket ausstellst.
So funktionieren Karten-/Ticketklassen mit Karten-/Ticketobjekten
Karten-/Ticketobjekte müssen eine Instanz einer Karten-/Ticketklasse entweder durch Verweis auf ihre Klassen-ID oder durch Einschließen der vollständigen Karten-/Ticketklassendefinition erweitern. Durch diese Beziehung zwischen einer Karten-/Ticketklasse und einer Instanz des Karten-/Ticketobjekts kannst du Attribute festlegen und aktualisieren, die allen ausgestellten Karten/Tickets über die Instanz der Karten-/Ticketklasse gemeinsam sind, sowie Attribute, die für eine einzelne Karte / ein Ticket in der Instanz des Karten-/Ticketobjekts eindeutig sind.
Das folgende Diagramm eines einfachen Veranstaltungstickets zeigt beispielsweise, wie die Felder, die in der gemeinsamen EventTicketClass definiert sind, und die Felder für ein bestimmtes Ticket, die in EventTicketObject definiert sind, kombiniert werden, um die endgültige ausgestellte Karte bzw. das endgültige Ticket zu erstellen. Auf die ID der Karten-/Ticketklasse wird in der Eigenschaft classId des Karten-/Ticketobjekts verwiesen.
Änderungen, die an einer Instanz der Karten-/Ticketklasse vorgenommen werden, werden sofort für alle Instanzen des Karten-/Ticketobjekts übernommen, die darauf verweisen. Nutzer sehen bei der nächsten Synchronisierung alle Änderungen, die du an einer Karten-/Ticketklasseninstanz vornimmst, in ihrer Google Wallet App.
Karte/Ticket zum Google Wallet eines Nutzers hinzufügen
Wenn du dem Google Wallet eines Nutzers eine Karte bzw. ein Ticket hinzufügen möchtest, erstellst du ein JSON Web Token (JWT), das Anforderungen enthält, die du (der Aussteller) bezüglich der Instanz des Karten-/Ticketobjekts stellst, das im Google Wallet des Nutzers gespeichert wird – vor allem die Objekt-ID der Karten-/Ticketobjektinstanz, die du dem Nutzer ausstellst. Das JWT wird dann über die Schaltfläche Zu Google Wallet hinzufügen oder Zu Google Wallet hinzufügen an den Nutzer gesendet.
Nachdem ein Nutzer auf die Schaltfläche oder den Link geklickt hat, um eine ausgestellte Karte / ein ausgestelltes Ticket zu Google Wallet hinzuzufügen, wird ein Link der im JWT codierten Instanz des Karten-/Ticketobjekts mit dem Google-Konto dieses Nutzers verknüpft. Wenn der Nutzer also noch einmal auf die Schaltfläche klickt, ist bereits ein Link zu diesem Karten-/Ticketobjekt vorhanden, sodass dem Wallet des Nutzers keine Duplikate hinzugefügt werden.
Wenn ein Nutzer eine Karte bzw. ein Ticket aus der Google Wallet App entfernt, wird die Verknüpfung der entsprechenden Karten-/Ticketobjektinstanz automatisch aufgehoben, aber nicht gelöscht. Das bedeutet, dass ein Nutzer noch einmal auf die Schaltfläche Zu Google Wallet hinzufügen oder den Link klicken kann, um die Karte bzw. das Ticket zu speichern, ohne dass eine neue Instanz des Karten-/Ticketobjekts oder ein neues JWT erstellt werden muss.