Configuration

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

Cette configuration relie Klaviyo (segmentation, flux, campagnes) à L'équipe Wallet (l’exécution du Wallet et les signaux du cycle de vie).

Klaviyo a besoin de deux choses :

• des identifiants pour que The Wallet Crew puisse envoyer des événements et mettre à jour les propriétés de profil Klaviyo
• un flux de webhook pour que Klaviyo puisse demander une rétropopulation 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 des mises à jour du statut d’abonnement pilotées par le consentement collecté dans un formulaire d’inscription The Wallet Crew.

Prérequis

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

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

La configuration de The Wallet Crew

The Wallet Crew utilise le connecteur Klaviyo pour envoyer des événements du cycle de vie du Wallet dans Klaviyo, maintenir les propriétés de profil et, éventuellement, gérer les abonnements aux listes en fonction du consentement collecté dans les flux d’inscription.

Exemples concrets

• Un formulaire d’inscription au programme de fidélité collecte l’e-mail + le consentement, puis inscrit le client à une liste de newsletter.
• Un événement d’installation de carte devient une métrique Klaviyo utilisée pour déclencher un flux de bienvenue.

Configurez 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 l’ID du site Klaviyo 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 / ID du site.
• privateApiKey est une nouvelle clé privée créée pour The Wallet Crew.

Autorisations requises sur la clé privée Klaviyo

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

• Toujours requis

  • Événements : Accès complet
• Requis lorsque la synchronisation des abonnements aux listes est activée

  • Listes : Accès complet
  • Profils : Accès complet
  • Abonnements : Accès complet

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

Si les événements n’apparaissent pas dans Klaviyo, le premier contrôle concerne les autorisations de la clé privée Klaviyo.

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

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

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

server/flows.yml

flux :
  - type: inscriptionUtilisateur
    nom: utilisateur
    étapes :
      - type: Shopify
      - type: Carte
        passType: user
      - type: klaviyo
      - type: courriel
        modèle d’e-mail : downloadPass

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

Configuration du consentement et de l'abonnement à une liste

Le consentement peut être collecté dans le formulaire d’inscription The Wallet Crew. Le connecteur Klaviyo peut le convertir en mises à jour des abonnements aux listes.

Configuration d’une seule liste

La listId la valeur est disponible dans les paramètres de liste Klaviyo.

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

• quand e-mail est présent, consents_email contrôle le statut d’abonnement par e-mail
• quand numéro de téléphone est présent, consents_sms contrôle le statut d’abonnement SMS

Plusieurs listes (avancé)

Le routage vers plusieurs listes peut être mis en œuvre avec du script.

Créer ou modifier /server/script/klaviyo.js et implémentez 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 Listes et Abonnements que les autorisations sont accordées à la clé privée Klaviyo.

Configuration Klaviyo

neostore.authenticationToken est la pierre angulaire d’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 Wallet pour ce client.

Exemples concrets

• Un e-mail de réactivation ouvre la page de carte sans demander de connexion.
• Un e-mail de rappel ouvre le formulaire d’inscription lorsqu’une carte n’est pas installée.

Créez le segment « TWC unsynced profiles »

Ce segment cible les profils auxquels le jeton manque.

1. Allez à https://www.klaviyo.com/lists/create et sélectionnez Segment.
2. Nom : Profils non synchronisés TWC.
3. Définition :

   • Propriétés concernant quelqu’un
   • neostore.authenticationToken
   • n’est pas définie

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

Créez le flux de synchronisation des profils

Ce flux appelle le webhook The Wallet Crew pour synchroniser le jeton des profils entrant dans le segment.

1

Créer un flux

• Allez à https://www.klaviyo.com/flows/create.
• Créer à partir de zéro.
• Nom : synchroniser les profils TWC non synchronisés.
• Déclencheur : « Lorsqu’une personne rejoint TWC unsynced profiles ».

2

Ajouter une action webhook

Klaviyo nécessite un conforme à la 2FA compte pour activer les webhooks.

Définissez 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 The Wallet Crew URLs et les routes d’API pour un locataire donné.

Ajoutez un en-tête :

• Clé : X-API-KEY
• Valeur : une clé API The Wallet Crew qui inclut tenant.klaviyo.listener l’autorisation d’écriture

Corps (JSON) :

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

3

Activez, puis rétroalimentez les profils passés

• Activez le flux.
• Dans le menu du flux, utilisez Ajouter des profils passés.
• Sélectionnez « from beginning ».
• Lancez la rétropopulation.

Cela force l’évaluation et la synchronisation des profils existants.

Dépannage : le jeton est toujours manquant après la rétropopulation

• Confirmez que le segment est correct : neostore.authenticationToken n’est pas définie.
• Confirmez que le flux est activé.
• Confirmez que l’action de webhook affiche des exécutions réussies dans l’historique des flux Klaviyo.
• Confirmez que l’en-tête du webhook utilise X-API-KEY.
• Confirmez que la clé API The Wallet Crew possède tenant.klaviyo.listener l'autorisation d'écriture.
• Confirmez que l’URL de destination utilise le bon <tenantId>.

Erreurs de configuration courantes

Ces problèmes expliquent la plupart des situations du type « c’est configuré mais rien ne se passe ».

• La clé privée Klaviyo ne dispose pas des autorisations requises (événements uniquement vs événements + profils + abonnements).
• L’URL du webhook utilise le mauvais identifiant de locataire.
• La clé API The Wallet Crew utilisée par le webhook ne dispose pas de tenant.klaviyo.listener l'autorisation d'écriture.
• La règle du segment Klaviyo comporte une faute de frappe, souvent autour de neostore.authenticationToken « is not set ».
• Le flux Wallet exécuté ne contient pas 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 à la 2FA.
• Le flux de synchronisation Klaviyo est désactivé, donc la rétropopulation ne s’exécute jamais.

FAQ

Quel environnement doit être configuré en premier ?

Le 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 prennent généralement en charge la configuration ?

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

Les segments, les flux et les 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 flux, des campagnes et des 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 locataire.