Presque toutes les cartes que vous pouvez émettre et qu'un utilisateur final peut enregistrer dans Google Wallet sont définies par deux composants: une classe Cartes et un objet Cartes. Chaque fois que vous émettez une carte à un utilisateur, vous avez besoin d'une instance de classe Cartes et d'un objet Cartes, qui indique à l'API Google Wallet le type de carte à créer et les informations à afficher sur la carte, comme la valeur d'une carte cadeau ou le nom d'un titulaire de billets.
L'API Google Wallet fournit un ensemble prédéfini de classes et d'objets de cartes dont vous créez des instances, puis vous utilisez pour créer une carte délivrée à un utilisateur, comme GiftCardClass et GiftCardObject, GenericClass et GenericObject, entre autres.
Chaque instance de classe de carte et d'objet de carte est définie comme un objet JSON, qui possède un ensemble de propriétés obligatoires et facultatives correspondant au cas d'utilisation spécifique prévu pour ce type de carte.
Classes de cartes
Considérez une classe de carte comme un modèle partagé permettant de créer une ou plusieurs cartes que vous émettez à vos utilisateurs. Une classe Cartes définit un ensemble commun de propriétés qui seront incluses dans toutes les cartes qui y font référence.
Par exemple, l'instance suivante de EventTicketClass 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 Cartes nécessite une propriété id que vous spécifiez. Cet ID de classe sert d'identifiant unique que vous référencez chaque fois que vous l'utilisez pour créer une instance d'objet Cartes.
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 délivrée à un utilisateur spécifique.
Par exemple, lorsqu'une carte de billetterie pour un événement est créée avec l'API Google Wallet, une instance EventTicketObject inclut les propriétés du 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 Cartes requiert une propriété id que vous spécifiez. Cet ID d'objet sert d'identifiant unique que vous référencez lorsque vous transmettez la carte à un utilisateur.
Fonctionnement des classes de 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 la classe Cartes, et les propriétés propres à une carte individuelle dans l'instance de l'objet Cartes.
Par exemple, le schéma suivant d'un billet pour un événement simple montre comment les champs définis dans le EventTicketClass partagé et ceux d'un billet spécifique défini dans EventTicketObject sont combinés pour créer la carte émise finale. 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 s'appliquent immédiatement à toutes les instances d'objet Cartes qui y font référence. Les modifications que vous apportez à une instance de classe de carte seront répercutées sur la carte dans l'application Google Wallet lors de la prochaine synchronisation.
Ajouter une carte au Google Wallet d'un utilisateur
Pour ajouter une carte au compte Google Wallet d'un utilisateur, créez un jeton Web JSON (JWT) qui contient les revendications que vous (l'émetteur) effectuez sur l'instance d'objet Cartes qui seront enregistrées dans Google Wallet de l'utilisateur (et plus important encore, l'ID d'objet de l'instance d'objet Cartes que vous envoyez à l'utilisateur). Le jeton JWT est ensuite envoyé à l'utilisateur via le bouton Ajouter à Google Wallet ou Ajouter à Google Wallet.
Lorsqu'un utilisateur clique sur le bouton ou le lien permettant d'ajouter une carte émise dans son compte Google Wallet, un lien (l'instance de l'objet Cartes 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, un lien vers cet objet Cartes existe déjà. Les 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 Cartes correspondante est automatiquement dissociée de l'utilisateur, mais elle 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 besoin de créer une instance d'objet Cartes ni un JWT.