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 à Braze en temps réel sous forme d’attributs personnalisés, d’événements personnalisés et d’achats, tandis que les Canvas et les 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 dépenser des transactions de points, et mettre à jour les préférences d’abonnement par 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 directement dans Braze.

Cas d’usage

• Célébration de montée en gamme : Lorsqu’un membre progresse vers un niveau de fidélité supérieur dans Convercus, déclenchez un Canvas Braze personnalisé avec un message de bienvenue, un avantage exclusif lié 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, utilisez Braze pour attribuer un coupon personnalisé dans Convercus via un webhook et le distribuer par e-mail, notification push et messages in-app.
• Solde de points en direct dans les messages : Utilisez le contenu connecté pour récupérer le solde de points en temps réel d’un membre dans Braze 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 complétant 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 la façon dont les membres Convercus sont mis en correspondance avec les profils utilisateur Braze.
   defaultOptins	Sélection multiple des canaux d’abonnement du programme (à partir de membershipOptins). Utilisé comme valeur par défaut pour le webhook d’abonnement e-mail lorsque la requête ne fournit pas optins. La configuration Braze est considérée comme incomplète tant qu’au moins un canal n’a pas été sélectionné.

2. Créer une clé API pour les appels entrants. Créez un identifiant X-Convercus-Key propre à chaque programme. La clé brute n’est affichée qu’une seule fois lors de la création, préfixée cvc_ (format : cvc_<base64url>). Enregistrez-la dans Braze lorsque vous configurez les Campaigns de 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 l’enregistrement de la connexion Braze, Convercus commence immédiatement à diffuser 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é de manière indépendante. 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 de 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 ne modifiant que l’endpoint et le corps de la requête. Par exemple, une comptabilisation de points envoie un POST vers /members/{accountId}/bookings avec booking_type (EARNBOOKING ou BURNBOOKING), booking_type_code, points et reason ; le webhook d’abonnement e-mail envoie un 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 réessayées en toute sécurité sans confirmer le 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 les nouvelles tentatives automatiques de Braze en cas de 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 l’utilisation d’un 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 mis en correspondance par external_id (ou le type d’identifiant choisi à l’étape 1).
3. Pour vérifier le sens inverse, lancez un envoi de test 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 service, 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 d’un palier, 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 en Liquid pour la personnalisation dans les messages (lignes d’objet, corps du message, titres de notification push).
4. Utilisez les événements purchase transmis depuis Convercus pour alimenter 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 email_subscribe

Événements personnalisés

Achats

Les transactions Convercus de type EARNTRANSACTION (points gagnés à partir des dépenses du 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 des transactions de gain sont transmis comme des achats à prix négatif, ce qui maintient 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 le dernier attribut synchronisé. Les deux endpoints partagent la même URL de base que les webhooks et nécessitent l’en-tête X-Convercus-Key.

Les endpoints de contenu connecté renvoient toujours HTTP 200 en cas d’échecs attendus afin que les modèles Liquid puissent se brancher 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 %}

Enveloppez toujours le contenu connecté dans des conditions (vérifiez member.error et coupons vide) afin qu’un échec temporaire de la recherche n’envoie jamais un message défectueux. 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 se propagent via Kafka et atteignent Braze en quelques secondes en charge normale.
• Limites de débit Braze : L’intégration réessaie automatiquement en cas de réponse 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 (ou au type d’identifiant choisi) de l’utilisateur dans Braze. Des identifiants non concordants entraînent l’attribution des événements au mauvais profil ou leur rejet.
• 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.