# Extensibilité

L'extensibilité personnalise la façon dont le connecteur résout les contacts, mappe les champs et formate les événements. Cela est principalement utilisé par les équipes techniques lorsque le comportement par défaut ne correspond pas au modèle de données.

## Configuration

L'extensibilité est configurée dans la console d'administration The Wallet Crew. Chaque point d'entrée est un script JavaScript stocké dans le connecteur Bloomreach **Paramètres avancés**.

La mise en pré-production (staging) est le point de départ recommandé. Cela réduit le risque de perturber la segmentation et les déclencheurs de scénarios en production.

{% stepper %}
{% step %}

#### Ouvrir les paramètres avancés du connecteur Bloomreach

<p align="center"><a href="https://admin.thewalletcrew.io/tenant/~/integrations/bloomreach/advanced" class="button secondary" data-icon="chevrons-right">Ouvrir la page Paramètres avancés</a></p>

Chaque point d'entrée possède son propre emplacement de script :

* Contact Finder
* Event Interceptor
* Customer Mapper
  {% endstep %}

{% step %}

#### Commencez par le changement le plus petit possible

Contact Finder est généralement implémenté en premier lorsque l'email n'est pas l'identifiant principal. Event Interceptor est généralement implémenté en premier lorsque la nomenclature des événements ou la gouvernance est requise.

Garder les modifications petites facilite l'isolation des problèmes d'attribution et d'ingestion.
{% endstep %}

{% step %}

#### Valider le comportement de bout en bout

La validation couvre généralement les deux directions du connecteur :

* Une activité fonctionne toujours (Mettre à jour la carte / Notifier / Appliquer un privilège).
* Un événement est toujours attribué au contact Bloomreach attendu.

Lorsque Event Interceptor est utilisé, la validation doit confirmer le nom final de l'événement et les propriétés visibles dans Bloomreach.
{% endstep %}

{% step %}

#### Déployer en production et surveiller

Une fois que le comportement en staging correspond aux attentes, les mêmes scripts peuvent être appliqués en production. Lorsque les événements sont utilisés comme déclencheurs de scénario, il est recommandé de déployer pendant une fenêtre de changement.
{% endstep %}
{% endstepper %}

## Points d'entrée d'extensibilité

Les scripts du connecteur sont configurés dans les paramètres avancés du connecteur Bloomreach dans la console d'administration The Wallet Crew.

{% hint style="warning" %}
Les modifications peuvent impacter le suivi des événements et l'exécution des scénarios. Un environnement de staging est recommandé pour les tests.
{% endhint %}

### Contact Finder

Une carte est liée à des identifiants externes (email, téléphone, ID membre, ...). Lorsqu'un événement se produit sur une carte, le connecteur doit l'attacher à un contact Bloomreach.

Contact Finder personnalise la façon dont ces identifiants sont convertis en identifiants de contact Bloomreach.

```js
/**
 * Récupérer l'identifiant de contact à partir des identifiants de la carte pour déterminer le contact Bloomreach d'une carte.
 * L'implémentation par défaut utilise l'email comme identifiant enregistré
 *
 * Cette méthode est asynchrone, permettant des appels à des services web externes si nécessaire.
 *
 * @param {Record<string, any>} identifiers - Paires clé-valeur des identifiants de la carte
 * @returns {Promise<Record<string, string>>} Objet avec la clé 'registered' contenant l'identifiant du contact côté Bloomreach
 */
async function getContactIdentifiers(identifiers) {
  // Exemple : utiliser l'email comme identifiant de contact
  // ceci est l'implémentation par défaut
  return { "registered": identifiers["email"] };
}

export default function (context) {
  context.register('extensions.bloomreach.contactFinder', {
    GetContactIdentifiers: getContactIdentifiers
  });
}
```

### Event Interceptor

Event Interceptor peut transformer `eventName` et `properties` avant d'envoyer l'événement à Bloomreach. Ceci est utile pour les conventions de nommage, le filtrage et l'enrichissement.

Retourner `null` supprime l'événement.

```js
/**
 * Intercepter les événements avant de les envoyer à Bloomreach.
 * Utilisez ceci pour transformer dynamiquement les noms d'événements ou les propriétés.
 * Exemple : ajouter des champs calculés, renommer des propriétés, filtrer des données
 *
 * @param {Object} eventData - Objet de données de l'événement
 * @param {string} eventData.Name - Nom de l'événement suivi
 * @param {Record<string, string>} eventData.Properties - Attributs/métadonnées de l'événement
 * @returns {Promise<Object>} Objet de données d'événement modifié - peut être null pour omettre cet événement
 */
async function interceptEvent({ Name, Properties }) {
  // Exemple : renvoyer l'événement tel quel (pas de transformation)
  // Modifier selon vos besoins
  return { Name, Properties };
}

export default function (context) {
  context.register('extensions.bloomreach.event.interceptor', {
    Intercept: interceptEvent
  });
}
```

### Customer Mapper

Customer Mapper personnalise le mapping entre les champs du formulaire d'inscription The Wallet Crew et les champs Bloomreach. Ceci est utilisé lorsque des données sont envoyées vers ou récupérées depuis Bloomreach avec des composants comme PassDataProvider et CustomerFlowElement.

```js
/**
 * Mappe les données du compte Wallet Crew vers les propriétés Bloomreach.
 *
 * @param {Object} account - L'objet compte Wallet Crew avec des champs comme firstName, email, etc.
 * @param {Object} properties - Objet de propriétés Bloomreach à remplir (muté en place)
 */
function mapToBloomreach(account, properties) {
  // Exemples de mappages - personnaliser en fonction de vos noms de champs
  if (account?.firstName) {
    properties["first_name"] = account.firstName;
  }
  if (account?.lastName) {
    properties["last_name"] = account.lastName;
  }
  if (account?.email) {
    properties["email"] = account.email;
  }
}

/**
 * Mappe les données client Bloomreach vers les champs du compte Wallet Crew.
 *
 * @param {Object} customer - Objet client Bloomreach avec Properties et Identifiers
 * @param {Object} account - L'objet account de Wallet Crew à remplir (muté sur place)
 */
function mapFromBloomreach(customer, account) {
  // Exemples de mappages - personnaliser en fonction de vos noms de champs
  if (customer && customer.Properties) {
    if (customer.Properties["first_name"]) {
      account["firstName"] = customer.Properties["first_name"];
    }
    if (customer.Properties["last_name"]) {
      account["lastName"] = customer.Properties["last_name"];
    }
    if (customer.Properties["email"]) {
      account["email"] = customer.Properties["email"];
    }
  }
}

export default function (context) {
  context.register('extensions.bloomreach.mapper', {
    MapToBloomreach: mapToBloomreach,
    MapFromBloomreach: mapFromBloomreach
  });
}
```

## FAQ

<details>

<summary><strong>Contact Finder peut-il appeler des services externes ?</strong></summary>

Oui. Contact Finder est asynchrone et peut appeler des services externes si nécessaire.

Ceci est typiquement utilisé lorsque l'identifiant de contact Bloomreach n'est pas directement stocké sur la carte. Les schémas courants incluent la résolution d'un `memberId` en un email, ou le mapping de plusieurs identifiants vers un unique identifiant Bloomreach « registered ».

</details>

<details>

<summary><strong>Un événement peut-il être supprimé avant d'atteindre Bloomreach ?</strong></summary>

Oui. Event Interceptor peut retourner `null` pour omettre un événement.

Ceci est utile pour la gouvernance et la réduction du bruit. Par exemples : filtrer les événements de scan provenant de cartes de test, supprimer des propriétés sensibles, ou ignorer des événements à fort volume qui ne sont pas exploitables dans Bloomreach.

</details>

<details>

<summary><strong>Quand Customer Mapper est-il utilisé ?</strong></summary>

Customer Mapper est utilisé lorsque les données Bloomreach sont lues ou écrites via des composants du connecteur. Les points d'entrée typiques sont PassDataProvider (lecture) et CustomerFlowElement (écriture).

Il n'est pas utilisé par chaque activité. Par exemple, l'envoi d'un message Notify ne nécessite pas Customer Mapper à moins que les propriétés Bloomreach ne soient également utilisées comme source de données pour le rendu de la carte.

Customer Mapper est l'endroit approprié pour aligner les conventions de nommage, les formats de données et les champs optionnels. Il aide également à maintenir la stabilité des modèles de carte lorsque les noms de champs Bloomreach changent.

</details>