Cartes associées automatiquement

Contexte

La fonctionnalité Cartes associées automatiquement vous permet d'envoyer des cartes supplémentaires à un utilisateur qui dispose déjà de votre carte existante dans Google Wallet. Vous pouvez également pré-associer des cartes à une carte principale lorsqu'un utilisateur enregistre la carte principale (principale). La carte associée automatiquement est regroupée avec la carte principale, avec un accroche au-dessus de la carte principale informant l'utilisateur qu'une nouvelle carte a été associée. Les types de cartes suivants sont acceptés en tant que cartes principales ou associées :

  • Billet pour un événement
  • Carte d'embarquement
  • Titre de transport
  • Offre
  • Bon d'achat
  • Carte de fidélité
  • Carte générique
Exemple principal de carte associée automatiquement Exemple de carte associée automatiquement (secondaire)
Carte principale avec le message indiquant qu'une nouvelle carte a été ajoutée Nouvelle carte associée à la carte principale

Cas d'utilisation

Vous pouvez avoir différents cas d'utilisation pour associer des cartes à une carte existante. Voici quelques exemples :

  • Associer une offre à une carte de fidélité existante
  • Associez un titre-restaurant à une carte d'embarquement ou à un billet pour un événement.
  • Associer une carte de stationnement à un billet pour un événement

Éléments à prendre en compte lors de l'utilisation des cartes associées automatiquement

  • L'objet principal et l'objet associé doivent utiliser le même issuerId.
  • Vous ne pouvez associer qu'un maximum de 50 objets par objet principal.
  • Le transfert automatique des cartes associées n'est pas garanti et considéré comme la tâche la plus optimale possible. Les utilisateurs peuvent désactiver la réception de cartes associées automatiquement. Si le cas d'utilisation est critique et que l'utilisateur doit recevoir la carte associée, nous vous recommandons de communiquer via un autre canal pour vous assurer que l'utilisateur ajoute la carte.
  • Les modifications apportées à la PUA de Google Wallet incluent des instructions sur l'utilisation des cartes associées automatiquement, que vous devez respecter.

Procédure d'intégration

Si vous avez déjà créé un objet principal, vous pouvez ignorer l'étape 1.

  1. Créez un objet de n'importe quel type de carte listé avec les paramètres requis. Il s'agit de l'objet principal.
  2. Créez un autre objet avec n'importe quel type de carte listé. Il s'agit de l'objet associé.
  3. Avant ou après l'enregistrement de l'objet principal, mettez à jour l'objet principal avec l'ID de l'objet associé dans le paramètre linkedObjectIds.

Une charge utile minimale est requise pour définir les linkedObjectIds sur une carte principale. Les trois paramètres obligatoires sont les suivants :

  1. ISSUERID.PRIMARY_OBJECT_ID
  2. ISSUERID.PRIMARY_CLASS_ID
  3. ISSUERID.LINKED_OBJECT_ID

Exemple de requête JSON pour ajouter un objet associé à un objet carte

  …
  {
    "id": "ISSUERID.PASS_OBJECTID",
    "classId": "ISSUERID.PASS_CLASSID",
    "barcode": {
      "type": "qrCode",
      "value": "QR code"
    },
    "linkedObjectIds": {"ISSUERID.LINKED_PASS_OBJECTID"}
  }
  …

Exemple de réponse JSON après avoir associé un objet à un objet de carte

  …
  "state": "active",
  "linkedObjectIds": {
    "ISSUERID.LINKED_PASS_OBJECTID"
  }
  …

Comportement attendu

Une fois la réponse reçue, les appareils avec la carte que vous avez mise à jour devraient recevoir la carte associée. Cette carte associée sera regroupée avec la carte principale. Les utilisateurs peuvent afficher la carte associée en balayant l'écran vers la droite.

Gestion des exceptions

Des erreurs potentielles peuvent se produire en cas d'utilisation incorrecte de l'API, par exemple :

Message Motif
L'objet principal et l'objet associé ne partagent pas le même ID d'émetteur. Vous ne pouvez pas associer un objet associé à l'objet d'un autre émetteur.
L'objet principal et l'objet associé font référence au même objet. Vous ne pouvez pas joindre le même objet que le linkedObject.
L'objet associé n'existe pas. L'objet associé doit déjà être inséré dans l'API Wallet.
L'objet associé est déjà associé à un autre objet. Impossible d'ajouter des objets liés imbriqués. Les objets associés ne peuvent pas avoir d'autre objet associé.
L'objet est déjà associé à un autre objet. Impossible d'ajouter des objets associés imbriqués. L'objet principal ne peut pas être un objet associé.
Impossible d'ajouter d'autres objets associés, la limite est atteinte. La limite de 50 cartes associées a été atteinte pour la carte principale.