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, 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, créditer et débiter 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 d’infrastructure supplémentaire à installer. Là où la plupart des connecteurs de fidélité ne transmettent les données que dans un 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’utilisation

1. Célébration de montée en 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 et le nouveau niveau et solde de points du membre.
2. Bonus d’anniversaire et de jalon : Depuis un parcours Braze, créditez des points bonus dans Convercus pour l’anniversaire ou la date anniversaire d’un membre, puis envoyez un message de célébration confirmant le nouveau solde.
3. Reconquête de 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.
4. 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 Liquid, alimentant des cadences telles que « il ne vous manque que X points pour votre prochaine récompense ».

Conditions préalables

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. Sinon, 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	Soit external_id, soit 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 (depuis 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 à Braze. Aucune configuration d’infrastructure supplémentaire n’est requise.

Remarque

Chaque programme Convercus est configuré indépendamment. Un seul 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’ID 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 changeant uniquement l’endpoint et le corps. Par exemple, un enregistrement de points est envoyé à /members/{accountId}/bookings avec booking_type (EARNBOOKING ou BURNBOOKING), booking_type_code, points et reason ; le webhook d’abonnement e-mail est envoyé à /subscriptions/email avec account_id et status (allowed ou declined).

Réponses d’erreur et nouvelles tentatives

Avertissement

Les réponses 5xx ne sont pas sûres pour une nouvelle tentative 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 nouvelle tentative automatique de Braze sur les 5xx pour ces webhooks, ou configurez un nombre maximum 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 la direction opposée, effectuez un envoi test Braze qui appelle l’un des webhooks de l’étape 2 et confirmez l’action dans Convercus (coupon attribué, points enregistré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 active, 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 niveaux, 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 notification push).
4. Utilisez les événements purchase transmis depuis Convercus pour alimenter des parcours orientés produit (réapprovisionnement, vente incitative 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 signalées à Braze en tant qu’achats et comptabilisées dans l’analyse du chiffre d’affaires Braze, la segmentation RFM et les fonctionnalités prédictives — en utilisant l’ID de transaction comme identifiant produit et le montant et la devise de la transaction comme prix et devise.

Les transactions de type PAYWITHPOINTSTRANSACTION (débit de points) ne sont pas signalées comme des achats — elles sont transmises en tant qu’événement personnalisé convercus_account_transaction afin de rester disponibles pour la segmentation. Les annulations et les inversions de transactions de crédit sont signalées comme des achats à prix négatif, maintenant l’alignement du chiffre d’affaires 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 niveau — appelez Convercus depuis Braze en utilisant le Contenu connecté au lieu de vous fier à l’attribut synchronisé le plus récent. Les deux endpoints se trouvent sous 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 (niveau, 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 les coupons vides) afin qu’un échec temporaire de recherche n’envoie jamais un message cassé. 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 effectue automatiquement de nouvelles tentatives sur les 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 disponibles 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 abonnements 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.