Hooks d’installation et de désinstallation de Carte

Créez un connecteur personnalisé qui appelle votre API lorsqu’une Carte est installée ou désinstallée dans Apple Wallet ou Google Wallet.

Il est possible de créer un connecteur personnalisé dans L'équipe Wallet pour appeler une API externe chaque fois qu'une carte est installée ou désinstallée sur Apple Wallet ou Google Wallet.

Cela permet aux marques de synchroniser l'état d'installation avec des systèmes externes tels qu'un CRM, un outil d'analyse ou une plateforme d'automatisation marketing.

Exemples concrets

• Une marque de distribution met à jour un champ CRM comme hasWalletPass=true juste après l'installation. Elle cesse alors d'envoyer des rappels « ajouter au Wallet ».
• Une marque de billetterie enregistre les installations et désinstallations dans sa pile BI. Elle suit l'adoption par événement, canal et type d'appareil.
• Une marque déclenche un parcours de bienvenue après l'installation. Elle utilise registrationSource pour segmenter par campagne UTM.
• Une marque détecte des pics de désinstallation inhabituels après une mauvaise version. Elle effectue rapidement un retour en arrière et communique de manière proactive.

Hooks d'exécution

La plateforme expose les hooks suivants sur le runtime.wallet.passUpdater point de terminaison :

• OnCarteInstalled → Déclenché lorsqu'une carte est ajoutée à Apple/Google Wallet
• OnCarteUninstalled → Déclenché lorsqu'une carte est retirée d'Apple/Google Wallet

Les deux méthodes reçoivent les mêmes paramètres :

Paramètre	Type	Description
passId	string	Identifiant unique de la carte
passType	string	Type de carte (fidélité, carte cadeau, billet d'événement… )
identifiers	Record<string, any>	Identifiants clé-valeur définis sur la carte (par ex. customerId)
device	"apple" ou "google"	plateforme Wallet
additionalInformation	AdditionalCarteInstallationInformation	Inclut des statistiques d'inscription

Exemple d'implémentation

Les scripts peuvent être placés dans le server/scripts dossier dans la configuration avancée.

const API_URL = 'https://partner';
import { getSecret } from 'neo/secrets';

/** 
 * @typedef {Object} RegistrationInformation 
 * @property {number} activeRegistrationCount - Inscriptions actives. 
 * @property {number} totalRegistrationCount - Total des inscriptions. 
 **/ 

/**
 * @typedef {Object} RegistrationSource
 * @property {string[]} tags - liste des tags spécifiés par l'intégration SDK
 * @property {string} medium - support spécifié par l'intégration SDK ou utm_medium
 * @property {string} origin  - URL depuis laquelle la carte est installée - peut être remplacée par l'intégration SDK
 * @property {string} userAgent - User-Agent facultatif utilisé pour installer la carte
 */

/** 
 * @typedef {Object} AdditionalCarteInstallationInformation
 * @property {RegistrationInformation} registrationInformation - Statistiques d'inscription. 
 * @property {RegistrationSource} registrationSource - Source de l'installation lorsqu'elle est disponible 
 */

/** méthodes déclenchées lorsqu'une carte est installée 
 * @param {string} passId - identifiant unique de la carte
 * @param {string} passType - type de carte de la carte actuelle
 * @param {Record<string, any>} identifiers - paires clé-valeur des identifiants de la carte
 * @param {"apple"|"google"} device - nom de l'appareil
 * @param {AdditionalPassInstallationInformation} additionalInformation - additionalInformation liée à cette installation de carte */
 async function onPassInstalled(passId, passType, identifiers, device, additionalInformation) {
     await onPassInstallationStatusChanged(passId, passType, identifiers, device, true);
} 

/** méthodes déclenchées lorsqu'une carte est désinstallée 
 * @param {string} passId - identifiant unique de la carte 
 * @param {string} passType - type de carte de la carte actuelle
 * @param {Record<string, any>} identifiers - paires clé-valeur des identifiants de la carte
 * @param {"apple"|"google"} device - nom de l'appareil 
 * @param {AdditionalPassInstallationInformation} additionalInformation - additionalInformation liée à cette installation de carte 
 */ 
async function onPassUninstalled(passId, passType, identifiers, device, additionalInformation) { 
    await onPassInstallationStatusChanged(passId, passType, identifiers, device, false); 
} 

async function onPassInstallationStatusChanged(passId, passType, identifiers, device, isInstalled) {
  const customerId = identifiers["customerId"]; // ou tout autre identifiant externe
  const API_SECRET = await getSecret('PARTNER-API-SECRET');

  // ⚠️ Note : fetch n'est pas standard ici. Il utilise des options en PascalCase et un Body basé sur un objet.
  await fetch(API_URL + '/wallet/installation', {
    Method: "POST",
    Headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      "X-API-KEY": API_SECRET
    },
    Body: {
      customerId,
      isInstalled,
      device
    },
    ThrowOnError: false
  });
}

export default function (context) {
  context.register('runtime.wallet.passUpdater', {
    OnPassInstalled: onPassInstalled,
    OnPassUninstalled: onPassUninstalled
  });
}

Exemple minimal

Pour les tests ou la journalisation uniquement :

async function onPassInstalled(passId, passType, identifiers, device) {
  console.log(`Carte ${passId} installée sur ${device}`);
}

async function onPassUninstalled(passId, passType, identifiers, device) {
  console.log(`Carte ${passId} désinstallée de ${device}`);
}

export default function (context) {
  context.register('runtime.wallet.passUpdater', {
    OnPassInstalled: onPassInstalled,
    OnPassUninstalled: onPassUninstalled
  });
}

Quand les événements sont-ils déclenchés ?

• OnCarteInstalled → déclenché lorsqu'un utilisateur ajoute avec succès une carte à Apple ou Google Wallet.
• OnCarteUninstalled → déclenché lorsqu'un utilisateur retire la carte de son Wallet.
• Les événements sont fiables : la plateforme garantit une livraison correcte même en cas de forte charge.

Notes

• fetch est pas le fetch standard du navigateur — il accepte des options en PascalCase (Method, Headers, Body, ThrowOnError).
• L'authentification est flexible : vous pouvez utiliser des clés API (via getSecret) ou OAuth avec le custom fetch.
• Il n'existe aucune restriction de plateforme : l'exécution est sûre et entièrement gérée.

FAQ

Ces événements sont-ils en temps réel ?

Ils se déclenchent lorsque la carte est ajoutée ou retirée du Wallet. En pratique, vous devriez les considérer comme quasi temps réel. Concevez toujours votre API pour qu'elle soit idempotente, afin que les nouvelles tentatives ne créent pas de doublons.

Que se passe-t-il si mon API est indisponible ?

Le code de votre connecteur contrôle l'appel. Vous devez gérer les délais d'attente et les erreurs de manière élégante. Si le système externe est critique, mettez en place des tentatives de réessai et une stratégie de dead-letter de votre côté.

Puis-je utiliser cela pour déclencher des e-mails ou des campagnes push ?

Oui. Le schéma le plus courant consiste à appeler votre plateforme d'automatisation marketing (directement ou via votre backend) et à déclencher un parcours lors de l'installation. Utilisez les événements de désinstallation pour arrêter ou adapter les communications.

Qu'est-ce qui est inclus dans additionalInformation?

Il peut inclure des statistiques d'inscription et, lorsqu'elle est disponible, la source d'installation. Utilisez-le pour mesurer l'adoption et attribuer les installations à une campagne ou à une intégration SDK.