Fast alle Karten/Tickets, die Sie für einen Endnutzer ausstellen können, damit er sie in Google Wallet speichert, werden durch zwei Komponenten definiert: eine Karten-/Ticketklasse und ein Karten-/Ticketobjekt. Jedes Mal, wenn Sie eine Karte/ein Ticket für einen Nutzer ausstellen, benötigen Sie eine Instanz einer Karten-/Ticketklasse und eines Karten-/Ticketobjekts. Damit wird der Google Wallet API mitgeteilt, welche Art von Karte/Ticket erstellt werden soll und welche Details auf der Karte/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, von denen Sie Instanzen erstellen und die Sie dann verwenden, um eine Karte/ein Ticket zu erstellen, das für einen Nutzer ausgestellt wird, z. B. GiftCardClass und GiftCardObject, GenericClass und GenericObject.
Jede Instanz von Karten-/Ticketklasse und Karten-/Ticketobjekt wird als JSON-Objekt definiert, das eine Reihe von erforderlichen und optionalen Eigenschaften enthält, die dem jeweiligen Anwendungsfall entsprechen, für den der Kartentyp vorgesehen ist.
Kartenklassen
Eine Pass-Klasse ist eine gemeinsame Vorlage, mit der ein oder mehrere Pässe erstellt werden, die Sie an Ihre Nutzer ausstellen. Eine Pass-Klasse definiert eine gemeinsame Gruppe von Attributen, die in allen Pässen enthalten sind, die darauf verweisen.
Die folgende Instanz von EventTicketClass definiert beispielsweise die Felder, die für alle ausgestellten Tickets für eine bevorstehende Veranstaltung gelten(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-Property erforderlich, die Sie angeben. Diese Klassen-ID dient als eindeutige Kennung, auf die Sie sich beziehen, wenn Sie damit eine neue Passes-Objektinstanz erstellen.
Karten-/Ticketobjekte
In einer Instanz einer Karten-/Ticketklasse wird eine Reihe gemeinsamer Attribute angegeben, die in einer oder mehreren Karten/Tickets verwendet werden sollen. In einem Karten-/Ticketobjekt werden die eindeutigen Details einer bestimmten Karte/eines bestimmten Tickets angegeben, die für einen bestimmten Nutzer ausgestellt werden.
Wenn beispielsweise ein Veranstaltungsticket mit der Google Wallet API erstellt wird, enthält eine EventTicketObject-Instanz Attribute für den Sitzplatz, der diesem Ticket zugewiesen ist, 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 Passes-Objekts ist ein id-Attribut erforderlich, das Sie angeben. Diese Objekt-ID dient als eindeutige Kennung, auf die Sie verweisen, wenn Sie einem Nutzer die Karte ausstellen.
Funktionsweise von Karten-/Ticketklassen mit Karten-/Ticketobjekten
Karten-/Ticketobjekte müssen eine Instanz einer Karten-/Ticketklasse erweitern, indem sie entweder auf ihre Klassen-ID verweisen oder die vollständige Definition der Karten-/Ticketklasse enthalten. Aufgrund dieser Beziehung zwischen einer Karten-/Ticketklasse und einer Karten-/Ticketobjektinstanz können Sie Eigenschaften, die für alle ausgestellten Karten/Tickets gelten, über die Karten-/Ticketklasseninstanz festlegen und aktualisieren. Eigenschaften, die nur für eine einzelne Karte/ein einzelnes Ticket gelten, können Sie in der Karten-/Ticketobjektinstanz festlegen.
Das folgende Diagramm eines einfachen Event-Ticket-Passes zeigt beispielsweise, wie die Felder, die im gemeinsamen EventTicketClass definiert sind, und die Felder für ein bestimmtes Ticket, die in EventTicketObject definiert sind, kombiniert werden, um den endgültigen ausgestellten Pass zu erstellen. Beachten Sie, wie die ID der Karten-/Ticketklasse im Attribut classId des Karten-/Ticketobjekts referenziert wird.
Änderungen an einer Instanz einer Karten-/Ticketklasse werden sofort auf alle Karten-/Ticketobjektinstanzen übertragen, die darauf verweisen. Nutzer sehen alle Änderungen, die Sie an einer Passes Class-Instanz vornehmen, beim nächsten Synchronisieren auf der Karte/dem Ticket in ihrer Google Wallet App.
Karte/Ticket zur Google Wallet eines Nutzers hinzufügen
Wenn Sie einer Google Wallet eines Nutzers eine Karte oder ein Ticket hinzufügen möchten, erstellen Sie ein JSON Web Token (JWT), das Anforderungen enthält, die Sie (der Aussteller) bezüglich der Instanz des Karten-/Ticketobjekts stellen, die in der Google Wallet des Nutzers gespeichert wird. Am wichtigsten ist die Objekt-ID der Instanz des Karten-/Ticketobjekts, die Sie für den Nutzer ausstellen. Das JWT wird dann über die Schaltfläche Zu Google Wallet hinzufügen oder den Link Zu Google Wallet hinzufügen an den Nutzer gesendet.
Nachdem ein Nutzer auf den Button oder Link geklickt hat, um eine ausgestellte Karte/ein ausgestelltes Ticket in Google Wallet hinzuzufügen, wird ein Link zur im JWT codierten Passes Object-Instanz mit dem Google-Konto des Nutzers verknüpft. Wenn der Nutzer also noch einmal auf den Button klickt, ist bereits ein Link zu diesem Karten-/Ticketobjekt vorhanden. Es werden also keine Duplikate in der Wallet des Nutzers hinzugefügt.
Wenn ein Nutzer eine Karte oder ein Ticket aus der Google Wallet App entfernt, wird die entsprechende Passes-Objektinstanz automatisch von ihm entknüpft, aber nicht gelöscht. Ein Nutzer kann also noch einmal auf den Button oder Link Zu Google Wallet hinzufügen klicken, um die Karte bzw. das Ticket zu speichern, ohne dass eine neue Karten-/Ticketobjektinstanz oder ein neues JWT erstellt werden muss.