Connecteur personnalisé

Étendez The Wallet Crew avec des scripts côté tenant pour appeler des services externes ou implémenter une logique d’intégration spécifique à l’exécution.

Les connecteurs personnalisés étendent The Wallet Crew avec des scripts côté locataire. Ils sont utiles lorsque les données de Carte doivent être enrichies à partir d’un système externe ou lorsque de la logique personnalisée doit s’exécuter lorsqu’une Carte est installée ou désinstallée.

Ce modèle conserve l’intégration dans l’environnement d’exécution du locataire. Il évite d’exposer la logique du connecteur dans le code côté client et facilite le contrôle des appels externes.

Exemples concrets

• Une marque enrichit une Carte de fidélité avec des points et des données de niveau provenant d’un CRM externe.

• Un partenaire remplit une Carte avec des attributs de profil provenant d’une API propriétaire.

• Une équipe synchronise l’état d’installation de la Carte avec une plateforme de marketing ou d’analyse.

Exigences

Pour créer un script, ouvrez Settings → Advanced → Advanced Configuration. Cette section contient les fichiers de configuration du locataire.

Les fichiers de script sont stockés sous /server/script/....

customProvider n’est qu’un nom d’exemple. Vous pouvez remplacer chaque customProvider occurrence par le nom du connecteur qui doit être enregistré, ou le conserver.

Créer le fichier de script

Dans l’explorateur de fichiers, créez un fichier tel que /server/script/customProvider.js.

Si le dossier ou le fichier n’existe pas encore, créez-le d’abord. Pour créer un dossier depuis l’explorateur de fichiers, saisissez le nom du dossier suivi de /.

Enregistrer le connecteur

Une fois le fichier de script existant, ajoutez l’enregistrement du connecteur :

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

Fonction Fill

La Fill fonction est le point d’entrée utilisé pour récupérer et injecter des données externes dans le cycle de vie de la Carte.

En pratique, cette fonction reçoit le contexte actuel de la Carte, appelle les services externes requis et retourne ou applique les données nécessaires au connecteur. L’implémentation exacte dépend du système externe connecté.

Le contrat d’exécution pour Fill est disponible dans la référence de la fonction Fill.

Exemple d’implémentation

Cet exemple lit les identifiants externes ajoutés lors de la création d’une Carte, appelle une API externe et remappe la réponse dans l’entité.

async function fill(entity) {
  const externalId = entity["id.externalId"];
  if (!externalId) {
    return false;
  }

  try {
    const res = await fetch("https://example.com/api/wallet", {
      Method: "GET",
      Headers: {
        "Content-Type": "application/json",
        "X-API-KEY": API_KEY,
      }
    });

    const item = JSON.parse(res.ResponseText)[0];

    entity.eventName = item?.eventName ?? `event ${externalId}`;
    entity.external_last_name = item?.lastName ?? null;
    entity.external_first_name = item?.firstName ?? null;
    entity.external_image_url = item?.imageUrl ?? null;
    entity.external_logo = item?.logo ?? null;
    entity.external_color = item?.color ?? null;
    entity.external_background_color = item?.backgroundColor ?? null;

    return true;
  } catch (e) {
    entity.external_error = `Une erreur s’est produite lors de l’appel à l’API externe : ${e}`;
    return true;
  }
}

Ce que fait cet enregistrement

Le script enregistre deux points d’entrée d’exécution. Chacun a un objectif différent.

runtime.scriptable.customerProvider.customProvider

Cet enregistrement expose une fonction nommée Fill. La Fill fonction est utilisée pour remplir les Cartes avec des données externes.

C’est l’endroit où appeler des API externes et enrichir les données de la Carte avec des informations provenant de systèmes partenaires, de plateformes CRM, de moteurs de fidélité ou de tout autre backend connecté au projet.

runtime.wallet.passUpdater

Cet enregistrement expose deux hooks de cycle de vie :

• OnPassInstalled

• OnPassUninstalled

Ces hooks sont déclenchés lorsqu’une Carte est installée ou désinstallée. Ils permettent d’exécuter la logique du connecteur au moment exact où le cycle de vie de Wallet change.

Les usages typiques incluent la synchronisation de l’état d’installation, le lancement d’un parcours de bienvenue ou l’arrêt des communications de rappel une fois la Carte déjà installée.

Le contrat d’exécution de ces hooks est disponible dans la référence OnPassInstalled and OnPassUninstalled.

Pour le comportement complet des hooks d’installation et de désinstallation, voir Hooks d’installation et de désinstallation de Carte.

FAQ

Le fichier de script doit-il être nommé customProvider.js?

Non. Le nom du fichier peut suivre n’importe quelle convention de nommage utilisée par le projet. Ce qui compte, c’est la clé d’enregistrement d’exécution utilisée dans le script.

Peut-on customProvider être remplacé par un autre nom de connecteur ?

Oui. Remplacez customProvider par le nom du connecteur qui doit être exposé par l’enregistrement d’exécution.

Quand faut-il enregistrer runtime.wallet.passUpdater ?

Enregistrez-le lorsque l’intégration doit réagir aux événements d’installation ou de désinstallation de la Carte. Si seul l’enrichissement de la Carte est nécessaire, l’enregistrement du fournisseur client peut suffire.