Convercus

Convercus est une plateforme SaaS de fidélité et de coupons qui aide les marques et les enseignes à augmenter la fréquence d’achat, la valeur du panier et les taux de réachat grâce à des programmes de fidélité omnicanaux et des campagnes de coupons personnalisées.

Cette intégration est maintenue par Convercus.

À propos de l’intégration

L’intégration entre Braze et Convercus est bidirectionnelle : les données de fidélité sont transmises dans Braze en temps réel sous forme d’attributs personnalisés, d’événements personnalisés et d’achats, et les Canvas et Campaigns Braze peuvent déclencher des actions de fidélité dans Convercus via des webhooks. Utilisez le niveau de membre synchronisé, le solde de points, les achats et l’activité des coupons dans les Segments, Liquid et le contenu connecté. Depuis les parcours Braze, vous pouvez également attribuer des coupons, enregistrer, accumuler et utiliser des transactions de points, et mettre à jour les préférences d’abonnement e-mail dans Convercus.

Convercus héberge l’intégration, vous n’avez donc pas besoin d’installer d’infrastructure supplémentaire. Là où la plupart des connecteurs de fidélité ne transmettent les données que dans un seul sens, Convercus boucle la boucle : réagissez dans Braze à un événement de fidélité, effectuez une action dans Convercus et mesurez le résultat dans Braze.

Cas d’usage

• Célébration de montée de niveau : Lorsqu’un membre monte d’un niveau de fidélité dans Convercus, déclenchez un Canvas Braze personnalisé avec un message de bienvenue, un avantage exclusif au niveau, ainsi que le nouveau niveau et le solde de points du membre.
• Bonus d’anniversaire et jalons : Depuis un parcours Braze, créditez des points bonus dans Convercus pour l’anniversaire ou la date anniversaire d’inscription d’un membre, puis envoyez un message de célébration confirmant le nouveau solde.
• Reconquête des membres inactifs : Pour les membres inactifs, faites en sorte que Braze attribue un coupon personnalisé dans Convercus via un webhook et le diffuse par e-mail, notification push et messages in-app.
• Solde de points en temps réel dans les messages : Utilisez le contenu connecté pour récupérer le solde de points en temps réel d’un membre dans Braze via Liquid, alimentant des cadences telles que « il ne vous reste que X points avant votre prochaine récompense ».

Prérequis

Avant de commencer, vous avez besoin des éléments suivants :

Vous avez besoin d’un identifiant utilisateur cohérent entre les systèmes : la valeur utilisée comme external_id (ou le type d’identifiant choisi) dans Braze doit correspondre à l’identifiant membre correspondant dans Convercus. Dans le cas contraire, les événements ne sont pas attribués au bon profil.

Intégration

Étape 1 : Configurer Braze dans Convercus Selfservice

Dans Convercus Selfservice (l’interface d’administration destinée aux clients — ouvrez-la à l’aide de l’URL fournie par votre gestionnaire de compte Convercus), ouvrez le programme que vous souhaitez connecter à Braze et utilisez la carte d’intégration Braze pour :

1. Configurer la connexion Braze en remplissant le formulaire d’intégration :

   Champ	Description
   apiKey	Votre clé API REST Braze (avec la permission users.track).
   apiEndpoint	Votre endpoint REST Braze, par exemple https://rest.iad-01.braze.com.
   Type d’identifiant	external_id ou user_alias. Détermine comment les membres Convercus sont associés aux profils utilisateur Braze.
   defaultOptins	Sélection multiple des canaux d’abonnement du programme (issus de membershipOptins). Utilisé comme valeur par défaut pour le webhook d’abonnement e-mail lorsque la requête omet optins. La configuration Braze est considérée comme incomplète tant qu’au moins un canal n’est pas sélectionné.

2. Créer une clé API pour les appels entrants. Créez un identifiant X-Convercus-Key par programme. La clé brute est affichée une seule fois lors de la création, préfixée cvc_ (format : cvc_<base64url>). Enregistrez-la dans Braze lorsque vous configurez les Campaigns webhook et les blocs de contenu connecté à l’étape 2. Les clés peuvent être révoquées à tout moment depuis la même carte ; la révocation prend effet immédiatement.

Après avoir enregistré la connexion Braze, Convercus commence immédiatement à transmettre les événements de fidélité de ce programme vers Braze. Aucune configuration d’infrastructure supplémentaire n’est requise.

Remarque

Chaque programme Convercus est configuré indépendamment. Un même tenant Convercus peut connecter différents programmes à différents espaces de travail Braze, chacun avec sa propre clé API.

Étape 2 : Configurer les webhooks dans Braze

Pour déclencher des actions Convercus depuis un Canvas ou une Campaign, créez des actions webhook Braze qui appellent le service d’intégration Convercus. Toutes les requêtes doivent inclure les en-têtes suivants :

• X-Convercus-Key: cvc_… — la clé API générée à l’étape 1.
• Content-Type: application/json

Tous les endpoints se trouvent sous l’URL de base <SERVICE_HOST>/v1/programs/{programId}. Remplacez <SERVICE_HOST> par l’hôte fourni par votre gestionnaire de compte Convercus et {programId} par l’identifiant de votre programme Convercus.

Exemple — attribuer un coupon à un membre :

1
2
3
4
5
6
7
8
POST <SERVICE_HOST>/v1/programs/{programId}/campaigns/{couponId}/assign
X-Convercus-Key: cvc_…
Content-Type: application/json

{
  "account_id": "{{custom_attribute.${convercus_account_id}}}",
  "braze_campaign_id": "{{campaign.${api_id}}}"
}

Les autres actions suivent le même schéma, en modifiant uniquement l’endpoint et le corps de la requête. Par exemple, une comptabilisation de points envoie une requête POST vers /members/{accountId}/bookings avec booking_type (EARNBOOKING ou BURNBOOKING), booking_type_code, points et reason ; le webhook d’abonnement e-mail envoie une requête POST vers /subscriptions/email avec account_id et status (allowed ou declined).

Réponses d’erreur et nouvelles tentatives

Avertissement

Les réponses 5xx ne peuvent pas être relancées en toute sécurité sans confirmation de succès — ces opérations ne sont pas idempotentes, et les nouvelles tentatives peuvent entraîner une double attribution de coupons ou un double crédit de points. Désactivez la relance automatique de Braze sur les erreurs 5xx pour ces webhooks, ou configurez un nombre maximal de tentatives très faible.

Étape 3 : Vérifier les données dans Braze

1. Déclenchez un événement de fidélité dans Convercus — par exemple, un changement de niveau de statut, une transaction de points ou un échange de coupon.
2. Ouvrez l’utilisateur correspondant dans Braze et confirmez que l’attribut personnalisé, l’événement personnalisé ou l’achat attendu apparaît sur le profil. Les utilisateurs sont associés par external_id (ou le type d’identifiant choisi à l’étape 1).
3. Pour vérifier le sens inverse, effectuez un envoi test depuis Braze qui appelle l’un des webhooks de l’étape 2 et confirmez l’action dans Convercus (coupon attribué, points comptabilisés ou abonnement mis à jour).

Utiliser Convercus avec Braze

Étape 1 : Personnaliser les messages avec les données de fidélité synchronisées

Une fois l’intégration en place, les événements Convercus arrivent sur chaque profil utilisateur dans Braze via l’endpoint /users/track et peuvent être utilisés comme n’importe quelle autre donnée native :

1. Utilisez les attributs personnalisés de fidélité (par exemple, convercus_status_level, convercus_balance) dans les Segments pour cibler les détenteurs de paliers, les membres à solde élevé ou les utilisateurs récemment rétrogradés.
2. Utilisez les événements personnalisés (par exemple, convercus_status_level_changed, événements de coupons et d’adhésion) comme étapes de déclenchement dans Canvas ou comme filtres dans les Campaigns de réengagement.
3. Référencez n’importe lequel de ces champs dans Liquid pour la personnalisation des messages (lignes d’objet, corps du message, titres de notifications push).
4. Utilisez les événements purchase transmis depuis Convercus pour piloter des parcours orientés produit (réapprovisionnement, montée en gamme par catégorie, demandes d’avis post-achat).

Attributs personnalisés

Remarque

Au sein d’un espace de travail Braze, les membres sont identifiés de manière unique par convercus_account_id. convercus_user_id identifie la personne sous-jacente à travers plusieurs programmes Convercus et est fourni pour l’analyse inter-programmes ; pour la segmentation dans Braze, utilisez convercus_account_id.

Mappage de email_subscribe

Événements personnalisés

Achats

Les transactions Convercus de type EARNTRANSACTION (points gagnés à partir des dépenses client) sont transmises à Braze en tant qu’achats et comptabilisées dans l’analyse des revenus Braze, la segmentation RFM et les fonctionnalités prédictives — en utilisant l’identifiant de transaction comme identifiant produit, et le montant et la devise de la transaction comme prix et devise.

Les transactions de type PAYWITHPOINTSTRANSACTION (utilisation de points) ne sont pas transmises en tant qu’achats — elles sont envoyées sous forme d’événement personnalisé convercus_account_transaction afin de rester disponibles pour la segmentation. Les annulations et les remboursements de transactions de gain sont transmis comme des achats à prix négatif, maintenant ainsi l’alignement des revenus Braze avec Convercus.

Étape 2 : Récupérer les données de fidélité en temps réel avec le contenu connecté

Pour les valeurs qui doivent être à jour au moment de l’envoi — solde de points actuel, coupons actifs, dernier palier — appelez Convercus depuis Braze en utilisant le contenu connecté au lieu de vous appuyer sur l’attribut synchronisé le plus récent. Les deux endpoints utilisent la même URL de base que les webhooks et nécessitent l’en-tête X-Convercus-Key.

Les endpoints de contenu connecté retournent toujours HTTP 200 en cas d’échecs attendus, afin que les templates Liquid puissent effectuer un branchement conditionnel sur le champ error :

Exemple — afficher le statut de fidélité d’un membre (palier, points et offres actives) :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{% connected_content
  https://<SERVICE_HOST>/v1/programs/{programId}/members/{{custom_attribute.${convercus_account_id}}}/profile
  :headers { "X-Convercus-Key": "cvc_…" }
  :content_type application/json
  :cache_max_age 300
  :retry
  :save member
%}

{% connected_content
  https://<SERVICE_HOST>/v1/programs/{programId}/members/{{custom_attribute.${convercus_account_id}}}/coupons?lang=en
  :headers { "X-Convercus-Key": "cvc_…" }
  :content_type application/json
  :cache_max_age 0
  :retry
  :save coupon_data
%}

{% unless member.error %}
  <h2>Your Loyalty Status</h2>
  <p>Hi {{member.first_name}}, you're a <strong>{{member.tier_name}}</strong> member.</p>
  <p>Points balance: <strong>{{member.points_balance}}</strong></p>

  {% if coupon_data.coupons.size > 0 %}
    <h3>Your Active Offers</h3>
    {% for coupon in coupon_data.coupons %}
      <p><strong>{{coupon.title}}</strong> — valid until {{coupon.valid_to}}</p>
    {% endfor %}
  {% endif %}
{% endunless %}

Encadrez toujours le contenu connecté dans des conditions (vérifiez member.error et un tableau coupons vide) afin qu’un échec temporaire de recherche n’envoie jamais un message incomplet. Mettez en cache le profil (cache_max_age 300) mais pas les coupons (cache_max_age 0), car le statut des coupons peut changer entre les envois.

Considérations

• Latence : Les événements Convercus vers Braze transitent par Kafka et atteignent Braze en quelques secondes en conditions de charge normale.
• Limites de débit Braze : L’intégration effectue automatiquement de nouvelles tentatives en cas de réponses 429, en respectant l’en-tête x-ratelimit-retry-after de Braze avec des délais exponentiels.
• Mise en cache du contenu connecté : Braze met en cache les réponses du contenu connecté pendant plusieurs minutes par défaut. Pour les valeurs qui doivent être exactes au moment de l’envoi (comme le solde de points), réduisez ou contournez la fenêtre de cache dans l’appel de contenu connecté.
• Une configuration par programme : Chaque programme de fidélité correspond à un seul espace de travail Braze. Pour connecter un second espace de travail, configurez-le sur un programme distinct.
• Observabilité : Les statistiques d’appels API par programme et l’historique des erreurs (dans les deux sens) sont conservés pendant 90 jours et accessibles depuis la carte d’intégration Braze dans Selfservice.

Résolution des problèmes

• Les événements n’apparaissent pas dans Braze : Vérifiez que la valeur utilisée comme identifiant (sélectionnée à l’étape 1) correspond à l’external_id de l’utilisateur (ou au type d’identifiant choisi) dans Braze. Des identifiants non concordants entraînent l’attribution des événements au mauvais profil ou leur suppression.
• Le webhook renvoie 401 : L’en-tête X-Convercus-Key est manquant ou la clé API cvc_… a été révoquée. Régénérez la clé dans Selfservice et mettez à jour l’action webhook dans Braze.
• Le webhook renvoie 400 : La requête ne contient pas Content-Type: application/json, ou le payload ne correspond pas au schéma documenté. Pour le webhook d’abonnement e-mail, un 400 signifie également que les opt-ins demandés sont inconnus du programme ou qu’aucun n’est configuré.
• Débogage approfondi : Consultez les statistiques d’appels API par programme et l’historique des erreurs sur la carte d’intégration Braze dans Selfservice, ou contactez votre conseiller Convercus.