Cartes associées automatiquement

Contexte

La fonctionnalité de 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. La carte associée automatiquement est regroupée avec la carte principale avec un avertissement 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 de carte principale de carte associée automatiquement Exemple de carte secondaire associée automatiquement
Carte principale avec un 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 :

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

Éléments à prendre en compte lorsque vous utilisez des cartes associées automatiquement

  • L'objet principal et l'objet associé doivent utiliser le même ID d'émetteur.
  • Le nombre d'objets associés est limité à 50 par objet principal.
  • La transmission automatique des cartes associées n'est pas garantie et n'est pas considérée comme la meilleure. 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 mises à jour de la PUA de Google Wallet incluent des conseils sur l'utilisation des cartes associées automatiquement, qui doivent être respectées.

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 répertorié avec les paramètres requis. Il s'agit de l'objet principal.
  2. Créez un autre objet de n'importe quel type de carte répertorié. Il s'agira 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 linkedObjectId sur une carte principale. Voici les trois paramètres obligatoires :

  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 de 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

Après avoir reçu une réponse positive, les appareils avec la carte que vous avez mise à jour doivent la recevoir. Cette carte associée sera regroupée avec la carte principale. Les utilisateurs peuvent voir 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 associer le même objet que l'objet "linkObject".
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 associés imbriqués. Les objets associés ne peuvent pas être associés à un autre objet.
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é seul.
Impossible d'ajouter d'autres objets associés, car la limite a été dépassée. La limite de 50 cartes associées a été atteinte pour la carte principale.