Connecteurs personnalisés

Étendez The Wallet Crew avec des scripts côté locataire pour les appels externes et les hooks d’exécution.

Connecteurs personnalisés

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 lorsqu'une logique personnalisée doit s'exécuter lors de l'installation ou de la désinstallation d'une Carte.

Ce modèle maintient l'intégration dans le runtime du locataire. Il évite d'exposer la logique du connecteur dans le code côté client et facilite le contrôle des appels externes.

Utilisez ce guide lorsqu'aucun connecteur natif n'existe pour votre logiciel et que l'intégration doit être mise en œuvre avec du scripting au runtime.

Liste de contrôle de création

Avant d'écrire des scripts, confirmez les points suivants :

Élément

Résultat attendu

Stratégie d'identifiants

Champs d'ID stables disponibles sur chaque enregistrement lié à une Carte

Propriété des données

Les systèmes sources pour les données de profil, de fidélité, de transaction et de ticket sont explicitement définis

Modèle de déclenchement

Décision claire sur le moment Remplissage, les hooks d'installation et de désinstallation sont utilisés

Modèle de sécurité

Clés API ou stratégie OAuth définies pour les appels externes

Gestion des erreurs

Comportement de nouvelle tentative, de délai d'attente et de surveillance convenu avec les équipes d'exploitation

Si l'un de ces éléments manque, alignez-le d'abord pour éviter un comportement instable du connecteur en production.

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 le statut d'installation de la Carte avec une plateforme marketing ou analytique.

Exigences

Pour créer un script, ouvrez Paramètres → Avancé → Configuration avancée. 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 vous pouvez le conserver.

Contraintes d'exécution

Les scripts de connecteur personnalisé s'exécutent dans un environnement d'exécution en bac à sable et versionné. Les contraintes suivantes s'appliquent à tous les scripts, quel que soit l'endroit où ils sont exécutés.

Temps d'exécution

Chaque invocation de script dispose d'un temps d'exécution maximal strict de 5 secondes. Les scripts qui dépassent cette limite sont interrompus. Concevez des scripts qui appellent des points de terminaison légers et à faible latence et évitez les opérations bloquantes.

Uniquement les bibliothèques approuvées

L'environnement d'exécution nil.js expose un ensemble restreint de bibliothèques explicitement approuvées et maintenues par The Wallet Crew. Les bibliothèques externes ou tierces ne peuvent pas être importées. Cela garantit un comportement déterministe, réduit la surface d'attaque et maintient des performances prévisibles.

Validation automatisée

Les scripts font l'objet d'une validation automatisée — y compris le linting et les vérifications de schéma — avant de pouvoir être enregistrés et exécutés. Un script qui échoue à la validation ne peut pas être déployé.

Modèle d'exécution

Selon le point de terminaison d'extensibilité, un script peut s'exécuter dans l'un des deux modes suivants :

Synchrone: exécuté en ligne dans un appel API, en contribuant à la réponse. La latence est critique dans ce mode.
Asynchrone: exécuté dans le cadre d'un flux de travail en arrière-plan déclenché via la messagerie. Plus tolérant au temps de traitement, mais toujours soumis à la limite de 5 secondes par invocation.

L'utilisation de la mémoire n'est pas plafonnée par un quota fixe, mais une consommation anormale déclenche des alertes de surveillance. Si un script provoque une pression soutenue sur les ressources, il sera examiné.

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 créé, ajoutez l'enregistrement du connecteur :

export default function(context) {
  context.register('runtime.scriptable.customerProvider.customProvider', {
    Remplissage : fill
  });
  context.register('runtime.wallet.passUpdater', {
    OnCarteInstalled: onPassInstalled,
    OnCarteUninstalled: onPassUninstalled
  });
}

Fonction de remplissage

La Remplissage 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, puis renvoie 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 Remplissage est disponible dans la référence de l'API.

Exemple d'implémentation

Cet exemple lit les identifiants externes qui sont ajoutés lorsqu'une Carte est créée, appelle une API externe et mappe 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 sert un objectif différent.

runtime.scriptable.customerProvider.customProvider

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

C'est l'endroit où appeler des API externes et enrichir les données de 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 :

OnCarteInstalled
OnCarteUninstalled

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 du Wallet change.

Les utilisations typiques incluent la synchronisation du statut d'installation, le lancement d'un parcours de bienvenue ou l'arrêt des communications de rappel une fois que la Carte est déjà installée.

Le contrat d'exécution pour ces hooks est disponible dans la référence de l'API.

La référence runtime ci-dessus est la source de vérité pour le comportement des hooks d'installation et de désinstallation.

Modèles associés

Utilisez les pages spécifiques au connecteur lorsque vous n'avez besoin que d'un seul comportement :

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 importe, c'est la clé d'enregistrement runtime utilisée à l'intérieur du script.

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

Oui. Remplacez customProvider par le nom du connecteur qui doit être exposé par l'enregistrement runtime.

Quand runtime.wallet.passUpdater doit-il être enregistré ?

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.

Mis à jour il y a 25 jours