Configuration

Connectez The Wallet Crew et Klaviyo de manière sécurisée et validez la synchronisation.

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

Exemples concrets

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

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.

Exemples concrets

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

Configurer le connecteur dans The Wallet Crew

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

Ouvrir les paramètres du connecteur Klaviyo

Les paramètres généraux stockent le Klaviyo Site ID et la clé API privée Klaviyo.

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

Assurez-vous que les permissions de la clé privée correspondent aux capacités attendues.

Si les événements n’apparaissent pas dans Klaviyo, la première vérification concerne les permissions de la clé privée Klaviyo.

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

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

L’ klaviyo étape peut être ajoutée à tout flow qui doit émettre des événements du cycle de vie.

server/flows.yml

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

Si les événements n’apparaissent pas dans Klaviyo, confirmez que klaviyo l’étape est présente dans le flow exécuté.

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.

/server/script/klaviyo.js

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,
  });
}

Si les mises à jour d’abonnement ne fonctionnent pas, confirmez que Listes et Abonnements les permissions sont accordées à la clé privée Klaviyo.

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.

Exemples concrets

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

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

Une faute de frappe dans cette règle empêche la rétro-population. C’est l’erreur de configuration la plus courante.

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.

1

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

2

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.

<tenantId> est le même identifiant utilisé dans les URL et les routes API The Wallet Crew pour un tenant donné.

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

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

3

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.

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

Quel environnement doit être configuré en premier ?

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.

Quelles équipes gèrent généralement la configuration ?

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.

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

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.

L’e-mail est-il requis pour synchroniser neostore.authenticationToken?

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.