# Guide utilisateur

Klaviyo reste la couche d'orchestration.

The Wallet Crew fournit deux blocs de construction clés à l'intérieur de Klaviyo :

* propriétés de profil pour cibler les clients en fonction de l'état du Wallet
* liens de téléchargement de Carte personnalisés avec `neostore.authenticationToken`

<details>

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

* Une campagne de rappel cible les clients qui n'ont pas installé la Carte.
* Un flux post-installation accueille les clients avec un message spécifique au Wallet.
* Un flux post-installation déclenche une notification Wallet avec un message d'intégration.
* Une mise à jour d'abonnement à une liste dans le formulaire d'inscription de The Wallet Crew alimente la messagerie basée sur le consentement dans Klaviyo.

</details>

### Envoyer un e-mail aux clients sans Carte installée

Ce modèle cible les profils où le token existe, mais où le statut du Wallet indique « non installé ».&#x20;

{% stepper %}
{% step %}

#### Construire le segment

Un segment dynamique peut être créé qui correspond à :

* `neostore.authenticationToken` est défini
* et au moins un statut de fournisseur de Wallet n'est pas installé

Le statut du Wallet est généralement exposé sous forme de propriétés de profil similaires à :

* `neostore.wallet.loyaltyCard.Apple`
* `neostore.wallet.loyaltyCard.Google`

La logique de segment utilise souvent :

* Le statut Apple n'est pas égal à `Installé`
* OU le statut Google n'est pas égal à `Installé`

{% hint style="info" %}
Les propriétés de statut du Wallet dépendent du type de Carte et de la configuration du locataire.

La validation la plus sûre consiste à inspecter un profil synchronisé dans Klaviyo et à copier le chemin de la propriété.
{% endhint %}

{% hint style="info" %}
La validation peut commencer en prévisualisant quelques profils correspondants et en vérifiant leurs propriétés de statut Wallet.
{% endhint %}
{% endstep %}

{% step %}

#### Créer la campagne

Une campagne peut ensuite cibler ce segment.

Cela permet de concentrer la messagerie sur les clients qui n'ont pas encore adopté le Wallet.
{% endstep %}

{% step %}

#### Insérer un lien de téléchargement de Carte

Les modèles Klaviyo peuvent insérer le token avec :

`{{person | lookup:'neostore.authenticationToken' }}`

Deux destinations courantes existent.

* Mise en page de téléchargement / d'enregistrement de la Carte

```
https://app.neostore.cloud/<tenantId>/mail?neo.authToken={{person | lookup:'neostore.authenticationToken' }}
```

* Page de la Carte (confirmation)

```
https://app.neostore.cloud/<tenantId>/mail/confirm?neo.authToken={{person | lookup:'neostore.authenticationToken' }}
```

`<tenantId>` est l'identifiant du locataire.

{% hint style="info" %}
Le nom d'hôte peut différer lorsqu'un domaine personnalisé est configuré pour le locataire.

La validation peut commencer en mode aperçu Klaviyo en confirmant que l'URL rendue contient une `neo.authToken` valeur non vide.
{% endhint %}
{% endstep %}
{% endstepper %}

### Envoyer un e-mail après l'installation de la Carte

Ce modèle démarre un flux après l'enregistrement d'une métrique d'installation.

{% stepper %}
{% step %}

#### Confirmer que la métrique d'installation existe

La métrique apparaît dans Klaviyo dès que le premier événement d'installation est reçu.
{% endstep %}

{% step %}

#### Créer un flux déclenché par une métrique

1. Créer un nouveau flux.
2. Utiliser un **déclencheur de métrique**.
3. Sélectionner la métrique d'installation du Wallet (exemple : « Wallet Installed »).
   {% endstep %}

{% step %}

#### Ajouter le contenu du message

Le modèle de lien de la page de la Carte peut être réutilisé pour la messagerie post-installation. Cela est utile pour les messages de « bienvenue » et les « étapes suivantes ».&#x20;

Dans de nombreux cas, l'URL de confirmation (`/mail/confirm`) est préférée ici car la Carte existe déjà.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Le nom exact de la métrique dépend de la configuration du connecteur.

La métrique apparaît dans Klaviyo dès que le premier événement est reçu.

Voir [Événements et modèle de données](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/connect/marketing-automation/klaviyo/events-and-data-model).
{% endhint %}

### Envoyer une notification Wallet

Les notifications Wallet peuvent être déclenchées depuis un flux Klaviyo en utilisant une action webhook appelant le listener Klaviyo de The Wallet Crew.

<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%2F4n7PSi88zC4n24uuiDdc%2Fimage.png?alt=media&#x26;token=2b7f0372-eb9f-44bc-93a0-c824b0e00e69" alt="" width="262"><figcaption><p>Exemple de notification Wallet pour un anniversaire</p></figcaption></figure></div>

Ce modèle correspond à tout moment d'intention forte dans le parcours client. Les événements du cycle de vie Wallet, les commandes, les visites en magasin et les étapes importantes peuvent devenir des déclencheurs. L'orchestration Klaviyo peut ensuite combiner la segmentation, le timing et les règles de fréquence pour garder les messages Wallet opportuns et pertinents.

{% columns %}
{% column %}

<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%2F36YbuKMy4aZh6RG8jfMo%2Fimage.png?alt=media&#x26;token=b8ba522c-b099-4f67-9abe-c18e26c35ca5" alt="Klaviyo flow: webhook action configuration for a wallet notification" width="211"><figcaption><p>Flux webhook post-installation Wallet.</p></figcaption></figure></div>
{% endcolumn %}

{% column %}

<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%2F1HTqcxHuuB0girhdFXwM%2Funknown.png?alt=media&#x26;token=36cfa1b4-fa24-44bb-a2fc-d5a8534496c5" alt="Klaviyo flow: webhook payload example used to trigger a wallet notification" width="219"><figcaption><p>Flux webhook post-commande</p></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% hint style="info" %}
Le comportement des notifications diffère entre Apple Wallet et Google Wallet.

Détails : [Notifications push](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/engage-and-animate/push-notification).
{% endhint %}

{% stepper %}
{% step %}

#### Créer le flux

Exemple de configuration :

* Nom du flux : `Post installation (tag neostore)`
* Déclencheur : « when someone wallet installed »
  {% endstep %}

{% step %}

#### Ajouter une action webhook

Utiliser le endpoint listener Klaviyo de The Wallet Crew :

`https://app.neostore.cloud/api/<tenantId>/webhooks/listeners/klaviyo/passes/pushUpdate`

Le webhook doit inclure l'en-tête `X-API-KEY` avec une clé API The Wallet Crew qui inclut `tenant.klaviyo.listener` permission d'écriture.
{% endstep %}

{% step %}

#### Utiliser la charge JSON ci-dessous

La charge identifie la Carte et ajoute un message de notification dans `additionalData`.

{% code title="Corps du webhook Klaviyo (JSON)" %}

```json
{
  "identifiers": {
    "id": "{{ person| lookup:'neostore.wallet.loyaltyCard.passId' }}"
  },
  "additionalData": {
    "message_body": "Bienvenue dans la famille MINISO {{ person.first_name }} ! 🤗\nDes points à chaque achat et des cadeaux à la clé. C'est le moment de profiter de vos avantages ! 💖"
  }
}
```

{% endcode %}

{% hint style="info" %}
La propriété utilisée pour résoudre l'id de la Carte peut différer selon le type de Carte et la configuration du locataire.

La validation peut commencer en inspectant un profil Klaviyo et en confirmant quelle propriété stocke l'identifiant de la Carte.
{% endhint %}
{% endstep %}
{% endstepper %}

### Comportement d'abonnement et de désabonnement

Les mises à jour d'abonnement à une liste peuvent être pilotées par les champs de consentement de The Wallet Crew.

Cela nécessite :

* une clé privée Klaviyo avec permissions Listes + Abonnements
* une liste unique `listId` configurée, ou une implémentation de script multi-listes

Détails de la configuration : [Configuration du consentement et de l'abonnement à la liste](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/connect/marketing-automation/klaviyo/setup#consent-and-list-subscription-configuration).

Lorsque le consentement est capturé lors de l'inscription, le connecteur peut abonner le profil à la liste configurée. Lorsque le consentement est retiré, le connecteur peut mettre à jour le statut d'abonnement en conséquence.

### Dépannage lors de la création des campagnes

#### Le lien se rend mais le token est vide

* Confirmer `neostore.authenticationToken` existe sur le profil.
* Confirmer que le profil est passé par le flux de synchronisation utilisé pour la rétro-population.
* Confirmer que le modèle utilise `lookup:'neostore.authenticationToken'`.
* Confirmer que le profil quitte le segment utilisé pour la rétro-population du token (exemple : `TWC unsynced profiles`) après l'exécution du flux de synchronisation.
* Si le token manque sur de nombreux profils, revoir [Configuration](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/connect/marketing-automation/klaviyo/setup#klaviyo-configuration).

#### Les clients arrivent sur la mauvaise page

Deux URL existent.

* `/mail` ouvre la mise en page d'enregistrement.
* `/mail/confirm` ouvre la page de la Carte.

#### La logique du segment pour le statut installé est incorrecte

* Confirmer que le segment vérifie à la fois les propriétés Apple et Google.
* Confirmer que la casse de la valeur stockée correspond à la condition du segment (exemple : `Installé`).

### FAQ

<details>

<summary><strong>Qui possède généralement les campagnes ?</strong></summary>

Les campagnes, segments et flux sont détenus dans Klaviyo.

The Wallet Crew possède l'exécution du Wallet et les événements du cycle de vie du Wallet.

</details>

<details>

<summary><strong>Quel lien doit être utilisé : <code>/mail</code> ou <code>/mail/confirm</code>?</strong></summary>

`/mail` est généralement utilisé pour les parcours de téléchargement et d'enregistrement de la Carte.

`/mail/confirm` est généralement utilisé lorsqu'une Carte existe déjà et que l'objectif est d'ouvrir directement la page de la Carte.

</details>

<details>

<summary><strong>Une notification Wallet peut-elle être envoyée si la Carte n'est pas installée ?</strong></summary>

Non. Les notifications Wallet requièrent au moins une installation active sur un appareil.

Une solution de repli courante utilise d'abord l'e-mail ou le SMS pour distribuer un lien de téléchargement de Carte, puis déclenche les notifications Wallet après un événement d'installation.

</details>

<details>

<summary><strong>Comment valider que la personnalisation fonctionne avant d'envoyer une campagne ?</strong></summary>

La validation peut commencer en mode aperçu Klaviyo en vérifiant que l'URL rendue contient une `neo.authToken`.

valeur non vide. `neostore.authenticationToken` La validation du profil peut être effectuée en confirmant que [Configuration](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/connect/marketing-automation/klaviyo/setup#klaviyo-configuration).

</details>

<details>

<summary><strong>existe sur quelques profils de test. Détails de la configuration :</strong></summary>

Quelle est la façon la plus sûre de tester les notifications Wallet ?

La plupart des équipes utilisent d'abord l'environnement de staging et conservent une petite liste de Cartes de test internes installées sur de vrais appareils. [Notifications push](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/engage-and-animate/push-notification).

</details>

<details>

<summary><strong>Le comportement et les limites des notifications dépendent des règles d'Apple Wallet et de Google Wallet. Référence :</strong></summary>

Comment éviter d'envoyer trop de notifications Wallet ?

Les notifications Wallet sont très visibles. Une utilisation excessive peut entraîner des désabonnements et de la fatigue chez les utilisateurs.  \
Klaviyo peut appliquer des plafonds de fréquence et des segments d'éligibilité. Une garde courante cible uniquement les profils avec un statut de Carte installée et une activité récente.

</details>