Présentation des classes et des objets des cartes

Presque toutes les cartes que vous pouvez émettre pour qu'un utilisateur final les enregistre dans son compte Google Wallet sont définies par deux composants: une classe Cartes et un objet Cartes. Chaque fois que vous envoyez 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, ainsi que les informations à afficher sur la carte, 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 d'objets Cartes et de classes de cartes dont vous créez des instances, puis que vous utilisez pour créer une carte émise à un utilisateur, par exemple GiftCardClass et GiftCardObject, GenericClass et GenericObject, entre autres.

Chaque classe d'objet Cartes et chaque instance d'objet Cartes est définie en tant qu'objet JSON, qui possède un ensemble de propriétés obligatoires et facultatives correspondant au cas d'utilisation spécifique destiné à ce type de carte.

Classes de cartes

Considérez une classe Cartes comme un modèle partagé permettant de créer une ou plusieurs cartes. que vous fournirez à vos utilisateurs. Une classe Cartes définit un ensemble commun de propriétés qui seront incluses dans toutes les cartes qui le référencent.

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érencerez chaque fois que vous l'utiliserez pour créer un objet Cartes. Compute Engine.

Objets des cartes

Alors qu'une instance d'une classe Cartes spécifie un ensemble de propriétés partagées à utiliser dans une ou plusieurs d'une carte, un objet Cartes spécifie les détails uniques d'une carte émise à un utilisateur donné.

Par exemple, lorsqu'un billet pour un événement est créé avec l'API Google Wallet, un EventTicketObject inclut des propriétés pour le siège attribué à ce billet, car ces valeurs sont uniques pour chaque le ticket a bien été é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 nécessite une propriété id, que vous spécifiez. Cet ID d'objet sert d'identifiant unique auquel vous vous référer lorsque vous fournirez la carte à un utilisateur.

Fonctionnement des classes Cartes avec les objets Cartes

Les objets Cartes doivent étendre une instance d'une classe de carte, soit en référençant son ID de classe, soit 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 schéma suivant, qui représente une carte de billet pour un événement simple, montre comment les champs définis dans le EventTicketClass partagé et ceux d'un billet spécifique définis dans EventTicketObject sont combinés pour créer la dernière carte émise. 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'appliqueront immédiatement à toutes les instances de l'objet Cartes qui y font référence. Les utilisateurs verront toutes les modifications que vous apportez à une instance de classe Cartes sur la carte dans l'application Google Wallet lors de sa prochaine synchronisation.

Ajouter une carte au compte Google Wallet d'un utilisateur

Pour ajouter une carte au compte Google Wallet d'un utilisateur, vous devez créer un jeton Web JSON (JWT) contenant les revendications. que vous (l'émetteur) formulez concernant l'instance d'objet Cartes qui sera enregistrée dans le compte Google Wallet de l'utilisateur : et surtout, l'ID d'objet de l'instance de l'objet Cartes que vous fournissez à l'utilisateur. Le jeton JWT est ensuite proposée à l'utilisateur via le bouton Ajouter à Google Wallet ou 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 d'objet Cartes encodée dans le JWT est associée au compte Google de cet utilisateur. Cela signifie que lorsque l'utilisateur clique de nouveau sur le bouton, cela signifie qu'il existe déjà un lien vers cet objet Cartes. les copies ne seront 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é de l'utilisateur, mais il n'est pas supprimé. Cela signifie qu'un utilisateur peut cliquer Ajouter à Google Wallet pour enregistrer la carte sans avoir besoin d'un une instance d'objet Cartes ou un jeton JWT.