# Connecteur personnalisé

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.

<details>

<summary><strong>Exemples concrets</strong></summary>

* 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.

</details>

## 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/...`.

{% hint style="info" %}
`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.
{% endhint %}

## 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 :

```js
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](https://app-qa.neostore.cloud/api/swagger/tenantConfiguration/index.html#section/Scripts/runtime.scriptable.customerPipelineElement.scriptId).

### 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é.

```javascript
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](https://app-qa.neostore.cloud/api/swagger/tenantConfiguration/index.html#section/Scripts/runtime.wallet.passUpdater).

Pour le comportement complet des hooks d’installation et de désinstallation, voir [Hooks d’installation et de désinstallation de Carte](/fr/connecter/custom-connector/installation-changed-extensibility.md).

## FAQ

<details>

<summary><strong>Le fichier de script doit-il être nommé <code>customProvider.js</code>?</strong></summary>

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.

</details>

<details>

<summary><strong>Peut-on <code>customProvider</code> être remplacé par un autre nom de connecteur ?</strong></summary>

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

</details>

<details>

<summary><strong>Quand faut-il enregistrer <code>runtime.wallet.passUpdater</code> ?</strong></summary>

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.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.thewalletcrew.io/fr/developper/guides/connecteur-personnalise.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.