Cartes associées automatiquement

Arrière-plan

La fonctionnalité de cartes associées automatiquement vous permet d'envoyer des cartes supplémentaires à un utilisateur qui possède déjà votre carte existante dans son Google Wallet. Vous pouvez également préassocier des cartes à une carte principale lorsqu'un utilisateur enregistre la carte principale (carte principale). La carte associée automatiquement est regroupée avec la carte principale. Une info-bulle s'affiche au-dessus de la carte principale pour informer l'utilisateur qu'une nouvelle carte a été associée. Les types de pass suivants sont acceptés comme pass principaux ou associés :

• Billet pour un événement
• Carte d'embarquement
• Titre de transport
• Offre
• Bon d'achat
• Carte de fidélité
• Carte générique

Carte principale avec l'info-bulle 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 pass à un pass existant. Voici quelques exemples :

• Associez une offre à une carte de fidélité existante.
• Associez un bon de repas à une carte d'embarquement ou à un billet pour un événement.
• Associez un pass de parking à 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 pouvez associer jusqu'à 50 objets à un objet principal.
• L'envoi automatique des cartes associées n'est pas garanti et est considéré comme un effort optimal. Les utilisateurs peuvent désactiver la réception des 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 avec lui par un autre canal pour vous assurer qu'il ajoute la carte.
• Les mises à jour du Règlement d'utilisation acceptable de Google Wallet incluent des consignes sur l'utilisation des cartes associées automatiquement, que vous devez respecter.

Étapes d'intégration

Si vous avez déjà créé un objet primary, 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 de l'un des types de cartes listés. 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 pass

  …
  {
    "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 l'association d'un objet à un objet Pass

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

Comportement attendu

Une fois que vous avez reçu une réponse positive, les appareils sur lesquels vous avez mis à jour la carte devraient recevoir la carte associée. Ce pass associé sera regroupé avec le pass principal. 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. Voici quelques exemples :

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 lié à 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 linkedObject.
L'objet associé n'existe pas.	L'objet associé doit déjà être inséré dans l'API Wallet.
L'objet associé possède déjà un autre objet associé. 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. La limite est dépassée.	La limite de 50 cartes associées a été atteinte pour la carte principale.