# Configuration

Cette configuration connecte **Klaviyo** (segmentation, flows, campagnes) à **The Wallet Crew** (exécution du wallet et signaux du cycle de vie).

Klaviyo a besoin de deux choses :

* des identifiants afin que The Wallet Crew puisse envoyer des événements et mettre à jour les propriétés de profil Klaviyo
* un flux webhook afin que Klaviyo puisse demander une rétro-population de `neostore.authenticationToken` pour les profils existants

<details>

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

* Une marque veut des segments “installé vs non installé” pour supprimer les e-mails de rappel.
* Une équipe CRM veut des liens authentifiés dans les e-mails sans modifier les modèles existants.
* Un partenaire veut que les mises à jour du statut d’abonnement soient déclenchées par le consentement recueilli dans un formulaire d’enrôlement The Wallet Crew.

</details>

### Prérequis

L’accès est requis des deux côtés.

* **The Wallet Crew**: accès à la console d’administration et aux fichiers de configuration avancée.
* **Klaviyo**: accès pour créer des clés API, des segments, des flows et des webhooks.
* Un profil test existe dans Klaviyo avec un e-mail et/ou un numéro de téléphone connus.
* L’environnement cible est identifié (staging vs production).

### La configuration The Wallet Crew

The Wallet Crew utilise le connecteur Klaviyo pour envoyer les événements du cycle de vie du wallet vers Klaviyo, maintenir les propriétés de profil et, optionnellement, gérer les abonnements aux listes en fonction du consentement recueilli dans les flux d’enrôlement.

<details>

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

* Un formulaire d’enrôlement fidélité collecte l’e-mail + le consentement, puis abonne le client à une liste de newsletters.
* Un événement d’installation de pass devient une métrique Klaviyo utilisée pour déclencher un flow de bienvenue.

</details>

#### Configurer le connecteur dans The Wallet Crew

Ouvrez les paramètres d’intégration Klaviyo dans la console d’administration The Wallet Crew.

<p align="center"><a href="https://admin.thewalletcrew.io/tenant/~/integrations/klaviyo" class="button secondary" data-icon="chevrons-right">Ouvrir les paramètres du connecteur Klaviyo</a></p>

<div data-with-frame="true"><figure><img src="https://3097111101-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2F5xpNnkcqGMPDxCOJOFOS%2Fimage.png?alt=media&#x26;token=7049b0c4-9a1d-4e7f-8314-d07f842972a0" alt="The Wallet Crew Klaviyo connector: general configuration screen"><figcaption><p>Les paramètres généraux stockent le Klaviyo Site ID et la clé API privée Klaviyo.</p></figcaption></figure></div>

**Valeurs Klaviyo requises**

Les valeurs Klaviyo sont disponibles à `https://www.klaviyo.com/settings/account/api-keys`.

* `siteId` correspond à **Clé API publique / Site ID**.
* `privateApiKey` est une **nouvelle** clé privée créée pour The Wallet Crew.

**Permissions requises sur la clé privée Klaviyo**

Les permissions minimales dépendent des fonctionnalités activées.

* Toujours requis
  * Événements : **Accès complet**
* Requis lorsque la synchronisation des abonnements de liste est activée
  * Listes : **Accès complet**
  * Profils : **Accès complet**
  * Abonnements : **Accès complet**

<div data-with-frame="true"><figure><img src="https://3097111101-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2F7esJQV498SFtEu7Eqed6%2Fimage.png?alt=media&#x26;token=b081b64a-a0cb-49c2-8282-db8f25094c53" alt="Klaviyo API keys screen showing permissions for a private key"><figcaption><p>Assurez-vous que les permissions de la clé privée correspondent aux capacités attendues.</p></figcaption></figure></div>

{% hint style="warning" %}
Si les événements n’apparaissent pas dans Klaviyo, la première vérification concerne les permissions de la clé privée Klaviyo.
{% endhint %}

#### Activez l’étape Klaviyo dans `server/flows.yml`

Le connecteur envoie des événements lorsqu’un flow inclut une `klaviyo` étape.

{% hint style="info" %}
L’ `klaviyo` étape peut être ajoutée à tout flow qui doit émettre des événements du cycle de vie.
{% endhint %}

{% code title="server/flows.yml" %}

```yaml
flows :
  - type: userRegistration
    name: user
    steps :
      - type: shopify
      - type: pass
        passType: user
      - type: klaviyo
      - type: mail
        mailTemplate: downloadPass
```

{% endcode %}

{% hint style="warning" %}
Si les événements n’apparaissent pas dans Klaviyo, confirmez que `klaviyo` l’étape est présente dans le flow exécuté.
{% endhint %}

#### Configuration du consentement et des abonnements de liste

Le consentement peut être recueilli dans le formulaire d’enrôlement The Wallet Crew. Le connecteur Klaviyo peut convertir cela en mises à jour d’abonnement de liste.

**Configuration d’une seule liste**

L’ `listId` la valeur est disponible dans les paramètres de la liste Klaviyo.

Lorsqu’un `listId` est configuré dans les paramètres Klaviyo de The Wallet Crew :

* lorsque `email` est présent, `consents_email` contrôle le statut d’abonnement par e-mail
* lorsque `phoneNumber` est présent, `consents_sms` contrôle le statut d’abonnement SMS

**Listes multiples (avancé)**

Le routage vers plusieurs listes peut être mis en œuvre avec des scripts.

Créer ou modifier `/server/script/klaviyo.js` et implémenter `GetSubscriptions`.

{% code title="/server/script/klaviyo.js" %}

```javascript
function getSubscriptions(account) {
  var subscriptions = [];

  var newsletterSubscription;
  if (account["email"] && account["consents_email"] !== undefined) {
    newsletterSubscription = newsletterSubscription || { ListId: "WnP7MK" };
    newsletterSubscription.Email = !!account["consents_email"];
  }

  if (account["phoneNumber"] && account["consents_sms"] !== undefined) {
    newsletterSubscription = newsletterSubscription || { ListId: "WnP7MK" };
    newsletterSubscription.Sms = !!account["consents_sms"];
  }

  if (newsletterSubscription) {
    subscriptions.push(newsletterSubscription);
  }

  return subscriptions;
}

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

{% endcode %}

{% hint style="warning" %}
Si les mises à jour d’abonnement ne fonctionnent pas, confirmez que **Listes** et **Abonnements** les permissions sont accordées à la clé privée Klaviyo.
{% endhint %}

### Configuration Klaviyo

`neostore.authenticationToken` est la pierre angulaire de l’identité pour les liens authentifiés.

Lorsque cette propriété existe sur un profil Klaviyo, les e-mails et les SMS peuvent inclure des liens qui ouvrent la bonne page de wallet pour ce client.

<details>

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

* Un e-mail de réactivation ouvre la page du pass sans demander de connexion.
* Un e-mail de rappel ouvre le formulaire d’enregistrement lorsqu’un pass n’est pas installé.

</details>

#### Créer le segment “TWC unsynced profiles”

Ce segment cible les profils auxquels il manque le token.

1. Aller à `https://www.klaviyo.com/lists/create` et sélectionner **Segment**.
2. Nom : `TWC unsynced profiles`.
3. Définition :
   * `Propriétés à propos de quelqu’un`
   * `neostore.authenticationToken`
   * `n’est pas défini`

{% hint style="warning" %}
Une faute de frappe dans cette règle empêche la rétro-population. C’est l’erreur de configuration la plus courante.
{% endhint %}

#### Créer le flow de synchronisation de profil

Ce flow appelle le webhook The Wallet Crew pour synchroniser le token des profils entrant dans le segment.

{% stepper %}
{% step %}
**Créer un flow**

* Aller à `https://www.klaviyo.com/flows/create`.
* Créer à partir de zéro.
* Nom : `sync TWC unsynced profiles`.
* Déclencheur : “Quand quelqu’un rejoint TWC unsynced profiles”.
  {% endstep %}

{% step %}
**Ajouter une action webhook**

Klaviyo exige un **compte conforme 2FA** pour activer les webhooks.

Définir l’URL de destination du webhook :

`https://app.neostore.cloud/api/<tenantId>/webhooks/listeners/klaviyo/profiles/sync`

`<tenantId>` est l’identifiant du tenant The Wallet Crew.

{% hint style="info" %}
`<tenantId>` est le même identifiant utilisé dans les URL et les routes API The Wallet Crew pour un tenant donné.
{% endhint %}

Ajouter un en-tête :

* Clé : `X-API-KEY`
* Valeur : une clé API The Wallet Crew qui inclut `tenant.klaviyo.listener` permission d’écriture

Corps (JSON) :

```json
{
  "email": "{{ person.email }}",
  "phone_number": "{{ person.phone_number }}"
}
```

{% endstep %}

{% step %}
**Activer, puis rétro-populer les profils passés**

* Activez le flow.
* Dans le menu du flow, utilisez **Ajouter des profils passés**.
* Sélectionnez “depuis le début”.
* Lancer la rétro-population.

Cela force l’évaluation et la synchronisation des profils existants.
{% endstep %}
{% endstepper %}

#### Dépannage : le token manque toujours après la rétro-population

* Confirmez que le segment est correct : `neostore.authenticationToken` **n’est pas défini**.
* Confirmez que le flow est **activé**.
* Confirmez que l’action webhook affiche des exécutions réussies dans l’historique du flow Klaviyo.
* Confirmez que l’en-tête webhook utilise `X-API-KEY`.
* Confirmez que la clé API The Wallet Crew a `tenant.klaviyo.listener` la permission d’écriture.
* Confirmez que l’URL de destination utilise le `<tenantId>`.

### Erreurs courantes de configuration

Ces problèmes expliquent la plupart des situations “c’est configuré mais rien ne se passe”.

* La clé privée Klaviyo n’a pas les permissions requises (événements uniquement vs événements + profils + abonnements).
* L’URL du webhook utilise le mauvais identifiant de tenant.
* La clé API The Wallet Crew utilisée par le webhook manque `tenant.klaviyo.listener` la permission d’écriture.
* La règle de segment Klaviyo contient une faute de frappe, souvent autour de `neostore.authenticationToken` “n’est pas défini”.
* Le flow wallet exécuté manque l’ `klaviyo` étape, donc aucun événement n’est envoyé.
* Les webhooks ne sont pas activés dans Klaviyo parce que le compte n’est pas conforme 2FA.
* Le flow de synchronisation Klaviyo est désactivé, donc la rétro-population ne s’exécute jamais.

### FAQ

<details>

<summary><strong>Quel environnement doit être configuré en premier ?</strong></summary>

L’environnement de staging est généralement configuré en premier.

Cela facilite la validation des événements, de la synchronisation des profils et du comportement des abonnements avant la production.

</details>

<details>

<summary><strong>Quelles équipes gèrent généralement la configuration ?</strong></summary>

Les paramètres du connecteur et les clés API sont généralement gérés par l’informatique ou un partenaire d’implémentation.

Les segments, flows et campagnes sont généralement gérés par le CRM ou les opérations marketing.

</details>

<details>

<summary><strong>The Wallet Crew a-t-il besoin d’un accès Klaviyo pour gérer les campagnes ?</strong></summary>

Non. Klaviyo conserve la propriété des flows, campagnes et modèles.

The Wallet Crew ne synchronise que les signaux du wallet et les propriétés de profil.

</details>

<details>

<summary><strong>L’e-mail est-il requis pour synchroniser <code>neostore.authenticationToken</code>?</strong></summary>

L’e-mail est l’identifiant le plus courant. Le téléphone peut également être fourni.

Le webhook accepte les deux champs. Les règles de correspondance dépendent de la configuration du tenant.

</details>