> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/fr/scripting/extensions/klaviyo.md).

# Scripts Klaviyo

Référence des scripts de mappage de profil Klaviyo et de fournisseur d’abonnements : gestionnaires, règles d’abonnement aux listes, le paramètre de consentement SMS et exemples.

Deux scripts ajustent le connecteur Klaviyo. Le mappeur modifie le profil que le connecteur envoie à Klaviyo. Le fournisseur d'abonnements décide aux listes Klaviyo auxquelles un client est abonné, et pour quel canal. Cette page est la référence pour `extensions.klaviyo.mapper` et `extensions.klaviyo.subscriptions.provider`. Le connecteur est décrit sur les [pages du connecteur Klaviyo](https://app.gitbook.com/s/lP7d71aYydav6e0pRkxc/marketing-automation/klaviyo/reference#custom-profile-mapping); les règles partagées par chaque script de connecteur se trouvent dans [Scripts du connecteur](https://docs.thewalletcrew.io/developers-guides/fr/scripting/extensions.md).

<details>

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

* Une marque redirige le consentement e-mail vers une liste « Newsletter » et le consentement SMS vers une liste « VIP SMS ».
* Une marque définit le numéro de téléphone du profil Klaviyo à partir du compte portefeuille.

</details>

## Enregistrement

| Clé                                         | Fichier des slots                   | Méthodes (obligatoires en **gras**) |
| ------------------------------------------- | ----------------------------------- | ----------------------------------- |
| `extensions.klaviyo.mapper`                 | `klaviyo.mapper.js`                 | **`MapToKlaviyo`**                  |
| `extensions.klaviyo.subscriptions.provider` | `klaviyo.subscriptions.provider.js` | **`GetSubscriptions`**              |

Les fichiers se trouvent dans le dossier `server/scripts/`, avec le nom du fichier de slot. Un fichier nommé `/server/script/klaviyo.js` n'est jamais chargé : le dossier est `scripts`, au pluriel, et le nom de fichier est celui du slot. Les slots sont lus et écrits avec `GET` et `PUT /api/{tenantId}/admin/extensions/klaviyo/scripts`. Lorsqu'aucun script n'est enregistré pour une clé, le comportement par défaut s'applique.

Les slots sont **Mappage de profil** et **Fournisseur d'abonnements** dans le **onglet Avancé** onglet du connecteur Klaviyo.

## Quand il s’exécute

`MapToKlaviyo` s'exécute chaque fois que le connecteur construit un profil Klaviyo, juste après le mappage par défaut : dans le `klaviyo` étape d'inscription et lorsqu'une Carte est installée ou supprimée. `GetSubscriptions` s'exécute dans le `klaviyo` étape d'un flux d'inscription, lorsque le connecteur calcule l'état d'abonnement du client.

Le mappage par défaut renseigne `Courriel` depuis `courriel`, `LastName` depuis `nom de famille`, `FirstName` depuis `prénom`, `Location.Country` depuis `country`, `Location.City` depuis `ville` et `Location.Zip` depuis `postCode` ou `codePostal`.

## Gestionnaires

| Méthode            | Paramètres          | Retours                                   | Obligatoire | Synchrone ou asynchrone |
| ------------------ | ------------------- | ----------------------------------------- | ----------- | ----------------------- |
| `MapToKlaviyo`     | `compte`, `profile` | rien                                      | Obligatoire | **Synchrone**           |
| `GetSubscriptions` | `compte`            | un tableau de `{ ListId?, Email?, Sms? }` | Obligatoire | **Synchrone**           |

* **`MapToKlaviyo`.** `profile` est le profil Klaviyo auquel le mappage par défaut a déjà été appliqué. L'objet vendeur conserve ses noms de membres .NET : `PhoneNumber`, `ExternalId`, `Courriel`, `FirstName`, `Location`, et `Properties[...]` pour les propriétés personnalisées. Un nom JSON tel que `phone_number` n'est que le nom utilisé lors de l'envoi du profil : lui affecter une valeur n'a aucun effet, c'est pourquoi l'exemple écrit `profile.PhoneNumber`.
* **`GetSubscriptions`.** Il renvoie une entrée par liste : `ListId` (l'identifiant de la liste Klaviyo), `Courriel` et `Sms` sous forme de booléens. Un `ListId` de `null` signifie une mise à jour du consentement sans liste. La méthode est synchrone : renvoyez le tableau, pas une promesse.

### Comment les abonnements se combinent avec le `listId` paramètre

Les abonnements que le script renvoie sont ajoutés à l'abonnement de `listId` configuré dans les paramètres du connecteur. Ils ne le remplacent pas. Pour utiliser le script seul, effacez `listId`. La valeur `builtin` pour `listId` met à jour les consentements intégrés de Klaviyo, sans lien avec une liste.

### Consentement SMS

La clé `consentements_sms` contrôle l'abonnement SMS uniquement lorsque le paramètre du connecteur **Activer la prise en charge SMS** est activé, ce qui n'est pas le cas par défaut. Lorsqu'il est désactivé, le consentement SMS est ignoré et consigné au niveau de débogage. Un script qui renvoie `Sms: true` n'a donc aucun effet tant que le paramètre n'est pas activé.

Les valeurs de `consents_email` et `consentements_sms` peuvent arriver sous forme booléenne ou textuelle, selon le formulaire. Le connecteur les lit comme des booléens : une valeur textuelle est ignorée par la `listId` abonnement. Un script peut convertir le texte lui-même, comme le fait l'exemple ci-dessous. Les membres d'un abonnement renvoyé sont en PascalCase : `ListId`, `Courriel`, `Sms`.

## Erreurs et cas limites

* **Aucun script enregistré**: le mappage par défaut s'applique, et seul le `listId` est utilisé.
* **Une méthode requise est manquante**: l'appel échoue avec `méthode <Name> manquante` lorsque le connecteur l'atteint.
* **`GetSubscriptions` renvoie un tableau vide**: aucun abonnement de script n'est ajouté ; le `listId` abonnement s'applique toujours. Sans `listId` non plus, aucune mise à jour d'abonnement n'est envoyée. L'avertissement « aucune liste configurée » n'est journalisé que lorsqu'aucun script n'est enregistré.
* **Un script lève**: l'erreur n'est pas interceptée et fait échouer l' `klaviyo` étape d'inscription.

## Exemple

Le fournisseur d'abonnements abonne un client à une liste, pour les canaux dont le consentement existe sur le compte. Le `toBoolean` utilitaire convertit `consents_email` et `consentements_sms` car elles peuvent arriver sous forme de texte.

```js
const NEWSLETTER_LIST = 'WnP7MK';

function toBoolean(value) {
  return value === true || value === 'true' || value === 'y' || value === 'yes';
}

function getSubscriptions(account) {
  const subscription = { ListId: NEWSLETTER_LIST };

  if (account['email'] && account['consents_email'] !== undefined) {
    subscription.Email = toBoolean(account['consents_email']);
  }
  if (account['phoneNumber'] && account['consents_sms'] !== undefined) {
    subscription.Sms = toBoolean(account['consents_sms']);
  }

  return subscription.Email === undefined && subscription.Sms === undefined ? [] : [subscription];
}

export default function (context) {
  context.register('extensions.klaviyo.subscriptions.provider', {
    GetSubscriptions: getSubscriptions
  });
}
```

Le mappeur définit le numéro de téléphone du profil Klaviyo :

```js
function mapToKlaviyo(account, profile) {
  const phoneNumber = account['phoneNumber'];
  if (phoneNumber) {
    profile.PhoneNumber = phoneNumber;
  }
}

export default function (context) {
  context.register('extensions.klaviyo.mapper', {
    MapToKlaviyo: mapToKlaviyo
  });
}
```

## Pièges courants

* Le script est enregistré en dehors de `server/scripts/` (par exemple sous `/server/script/klaviyo.js`) : il n'est jamais chargé.
* Le mappeur affecte `profile.phone_number`: le membre est `PhoneNumber`.
* `GetSubscriptions` ou `MapToKlaviyo` est déclaré `async`: les deux doivent être synchrones.
* Le `listId` paramètre est toujours défini, donc le client est aussi abonné à cette liste.
* Le consentement SMS est ignoré parce que **Activer la prise en charge SMS** est désactivé.

## FAQ

<details>

<summary><strong>Un script modifie-t-il les profils existants ?</strong></summary>

Oui, une fois déployé : il modifie la manière dont les mises à jour d'abonnement sont calculées pour chaque profil qui passe par un flux avec une `klaviyo` étape. Testez-le d'abord sur un petit ensemble de profils de test.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/fr/scripting/extensions/klaviyo.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
