Presque toutes les cartes que vous pouvez émettre pour qu'un utilisateur final les enregistre dans son Google Wallet sont définies par deux composants : une classe de cartes et un objet de carte. Chaque fois que vous émettez un pass pour un utilisateur, vous avez besoin d'une instance de classe de pass et d'une instance d'objet de pass. Ces instances indiquent à l'API Google Wallet le type de pass à créer, ainsi que les informations à afficher sur le pass, comme la valeur d'une carte cadeau ou le nom d'un détenteur de billet.
L'API Google Wallet fournit un ensemble prédéfini de classes et d'objets de cartes dont vous créez des instances, puis que vous utilisez pour créer une carte émise à un utilisateur, comme GiftCardClass et GiftCardObject, GenericClass et GenericObject, et d'autres.
Chaque instance de classe et d'objet de pass est définie comme un objet JSON, qui comporte un ensemble de propriétés obligatoires et facultatives correspondant au cas d'utilisation spécifique prévu pour ce type de pass.
Classes de cartes
Considérez une classe de cartes comme un modèle partagé utilisé pour créer une ou plusieurs cartes que vous émettrez à vos utilisateurs. Une classe de pass définit un ensemble commun de propriétés qui seront incluses dans tous les pass qui y font référence.
Par exemple, l'instance EventTicketClass suivante définit les champs communs à tous les billets émis pour un événement à venir(lieu, nom de l'événement, émetteur, date/heure).
{
"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"
}
Chaque instance d'une classe de pass nécessite une propriété id que vous spécifiez. Cet ID de classe sert d'identifiant unique que vous référencerez chaque fois que vous l'utiliserez pour créer une instance d'objet Pass.
Objets Cartes
Alors qu'une instance d'une classe Cartes spécifie un ensemble de propriétés partagées à utiliser dans une ou plusieurs cartes, un objet Cartes spécifie les détails uniques d'une carte spécifique émise pour un utilisateur spécifique.
Par exemple, lorsqu'un pass pour un événement est créé avec l'API Google Wallet, une instance EventTicketObject inclut des propriétés pour le siège attribué à ce billet, car ces valeurs sont uniques à chaque billet émis.
{
"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": ""
}
}
Chaque instance d'un objet Pass nécessite une propriété id que vous spécifiez. Cet ID d'objet sert d'identifiant unique auquel vous ferez référence lorsque vous émettrez la carte pour un utilisateur.
Fonctionnement des classes Cartes avec les objets Cartes
Les objets Cartes doivent étendre une instance d'une classe Cartes en référençant son ID de classe ou en incluant la définition complète de la classe Cartes. Cette relation entre une classe Cartes et une instance d'objet Cartes signifie que vous pouvez définir et mettre à jour les propriétés communes à toutes les cartes émises via l'instance de classe Cartes, et les propriétés propres à une carte individuelle dans l'instance d'objet Cartes.
Par exemple, le diagramme suivant d'un simple pass pour un billet d'événement montre comment les champs définis dans EventTicketClass partagé et les champs d'un billet spécifique définis dans EventTicketObject se combinent pour construire le pass émis final. Notez que l'ID de la classe Cartes est référencé dans la propriété classId de l'objet Cartes.
Les modifications apportées à une instance de classe Cartes sont immédiatement propagées à toutes les instances d'objet Cartes qui y font référence. Les utilisateurs verront les modifications que vous apportez à une instance de classe de cartes reflétées sur la carte dans leur application Google Wallet lors de la prochaine synchronisation.
Ajouter une carte à Google Wallet d'un utilisateur
Pour ajouter une carte à Google Wallet d'un utilisateur, vous devez créer un jeton Web JSON (JWT) contenant les revendications que vous (l'émetteur) effectuez sur l'instance de l'objet Cartes qui sera enregistrée dans Google Wallet de l'utilisateur. L'élément le plus important est l'ID d'objet de l'instance de l'objet Cartes que vous émettez pour l'utilisateur. Le JWT est ensuite transmis à l'utilisateur via un bouton Ajouter à Google Wallet ou un lien Ajouter à Google Wallet.
Lorsqu'un utilisateur clique sur le bouton ou le lien pour ajouter une carte émise à son compte Google Wallet, un lien vers l'instance de l'objet "carte" encodée dans le jeton JWT est associé au compte Google de cet utilisateur. Cela signifie que lorsque l'utilisateur clique de nouveau sur le bouton, le lien vers l'objet Carte existe déjà. Des copies en double ne seront donc pas ajoutées au portefeuille de l'utilisateur.
Si un utilisateur supprime une carte de l'application Google Wallet, l'instance d'objet Carte correspondante est automatiquement dissociée de l'utilisateur, mais n'est pas supprimée. Cela signifie qu'un utilisateur peut à nouveau cliquer sur le bouton ou le lien Ajouter à Google Wallet pour enregistrer la carte sans avoir à créer une nouvelle instance d'objet Cartes ni un nouveau JWT.