Convercus

Convercus ist eine SaaS-Loyalty- und Coupon-Plattform, die Marken und Händlern hilft, Kundenfrequenz, Warenkorbwert und Wiederkaufsraten durch Omnichannel-Kundenbindungs-Programme und personalisierte Coupon-Kampagnen zu steigern.

Diese Integration wird von Convercus gepflegt.

Über die Integration

Die Integration von Braze und Convercus ist bidirektional: Kundenbindungsdaten fließen in Echtzeit als angepasste Attribute, angepasste Events und Käufe in Braze, und Braze-Canvases und Campaigns können über Webhooks Aktionen im Kundenbindungs-Programm in Convercus auslösen. Verwenden Sie synchronisierte Mitgliedsstufen, Punktestände, Käufe und Coupon-Aktivitäten in Segments, Liquid und Connected-Content. Aus Braze-Journeys heraus können Sie außerdem Coupons zuweisen, Punktetransaktionen buchen, sammeln und einlösen sowie E-Mail-Abo-Einstellungen in Convercus aktualisieren.

Convercus hostet die Integration, sodass Sie keine zusätzliche Infrastruktur installieren müssen. Während die meisten Konnektoren für Kundenbindungs-Programme Daten nur in eine Richtung übertragen, schließt Convercus den Kreislauf: Reagieren Sie in Braze auf ein Kundenbindungs-Event, führen Sie eine Aktion in Convercus aus und messen Sie das Ergebnis wieder in Braze.

Anwendungsfälle

• Aufstiegsfeier bei Stufenwechsel: Wenn ein Mitglied in Convercus eine höhere Treuestufe erreicht, lösen Sie ein personalisiertes Braze-Canvas mit einer Willkommensnachricht, einem stufenexklusiven Vorteil sowie der neuen Stufe und dem Punktestand des Mitglieds aus.
• Geburtstags- und Meilenstein-Boni: Buchen Sie aus einer Braze-Journey heraus Bonuspunkte in Convercus zum Geburtstag oder Jubiläum eines Mitglieds und senden Sie anschließend eine Glückwunschnachricht mit Bestätigung des neuen Kontostands.
• Rückgewinnung inaktiver Mitglieder: Lassen Sie Braze bei inaktiven Mitgliedern per Webhook einen personalisierten Coupon in Convercus zuweisen und über E-Mail, Push und In-App Messages zustellen.
• Realtime-Punktestand in Nachrichten: Nutzen Sie Connected-Content, um den aktuellen Punktestand eines Mitglieds in Echtzeit in Braze Liquid abzurufen – ideal für Kampagnen wie „Sie sind nur noch X Punkte von Ihrer nächsten Prämie entfernt“.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie Folgendes:

Sie benötigen einen konsistenten Bezeichner für Nutzer:innen zwischen den Systemen: Der Wert, der in Braze als external_id (oder der gewählte Bezeichnertyp) verwendet wird, muss mit dem entsprechenden Mitgliederbezeichner in Convercus übereinstimmen. Andernfalls werden Events nicht dem korrekten Profil zugeordnet.

Integration

Schritt 1: Braze in Convercus Selfservice konfigurieren

Öffnen Sie in Convercus Selfservice (der kundenorientierten Admin-Oberfläche – öffnen Sie sie über die URL, die Ihr Convercus Account Manager:in bereitstellt) das Programm, das Sie mit Braze verbinden möchten, und verwenden Sie die Braze-Integrationskarte, um:

1. Die Braze-Verbindung zu konfigurieren, indem Sie das Integrationsformular ausfüllen:

   Feld	Beschreibung
   apiKey	Ihr Braze-REST-API-Schlüssel (mit der Berechtigung users.track).
   apiEndpoint	Ihr Braze-REST-Endpunkt, zum Beispiel https://rest.iad-01.braze.com.
   Bezeichnertyp	Entweder external_id oder user_alias. Bestimmt, wie Convercus-Mitglieder mit Braze-Nutzerprofilen abgeglichen werden.
   defaultOptins	Mehrfachauswahl der Opt-in-Kanäle des Programms (aus membershipOptins). Wird als Standard für den E-Mail-Abo-Webhook verwendet, wenn die Anfrage optins nicht enthält. Die Braze-Konfiguration gilt als unvollständig, bis mindestens einer ausgewählt ist.

2. Einen API-Schlüssel für eingehende Aufrufe erstellen. Erstellen Sie pro Programm eine X-Convercus-Key-Zugangsdaten. Der Rohschlüssel wird bei der Erstellung einmalig angezeigt, mit dem Präfix cvc_ (Format: cvc_<base64url>). Speichern Sie ihn in Braze, wenn Sie die Webhook-Campaigns und Connected-Content-Blöcke in Schritt 2 konfigurieren. Schlüssel können jederzeit über dieselbe Karte widerrufen werden; der Widerruf wird sofort wirksam.

Nachdem Sie die Braze-Verbindung gespeichert haben, beginnt Convercus sofort mit dem Streaming von Loyalty-Events für dieses Programm an Braze. Es ist kein zusätzlicher Infrastrukturaufbau erforderlich.

Hinweis

Jedes Convercus-Programm wird unabhängig konfiguriert. Ein einzelner Convercus-Mandant kann verschiedene Programme mit verschiedenen Braze-Workspaces verbinden, jeweils mit eigenem API-Schlüssel.

Schritt 2: Webhooks in Braze konfigurieren

Um Convercus-Aktionen aus einem Canvas oder einer Campaign auszulösen, erstellen Sie Braze-Webhook-Aktionen, die den Convercus-Integrationsdienst aufrufen. Alle Anfragen müssen die folgenden Header enthalten:

• X-Convercus-Key: cvc_… – der in Schritt 1 generierte API-Schlüssel.
• Content-Type: application/json

Alle Endpunkte befinden sich unter der Basis-URL <SERVICE_HOST>/v1/programs/{programId}. Ersetzen Sie <SERVICE_HOST> durch den von Ihrem Convercus Account Manager:in bereitgestellten Host und {programId} durch Ihre Convercus-Programm-ID.

Beispiel — einem Mitglied einen Coupon zuweisen:

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}}}"
}

Die anderen Aktionen folgen demselben Muster und ändern nur den Endpunkt und den Body. Beispielsweise sendet eine Punktebuchung an /members/{accountId}/bookings mit booking_type (EARNBOOKING oder BURNBOOKING), booking_type_code, points und reason; der E-Mail-Abo-Webhook sendet an /subscriptions/email mit account_id und status (allowed oder declined).

Fehlerantworten und Wiederholungsversuche

Warnung

5xx-Antworten sind nicht sicher für Wiederholungsversuche ohne Erfolgsbestätigung — diese Operationen sind nicht idempotent, und Wiederholungen können Coupons doppelt zuweisen oder Punktebuchungen doppelt gutschreiben. Deaktivieren Sie die automatische Wiederholung von Braze bei 5xx für diese Webhooks oder konfigurieren Sie eine sehr niedrige maximale Anzahl von Wiederholungsversuchen.

Schritt 3: Daten in Braze überprüfen

1. Lösen Sie ein Loyalty-Event in Convercus aus — zum Beispiel eine Statusstufenänderung, eine Punkte-Transaktion oder eine Coupon-Einlösung.
2. Öffnen Sie die:den entsprechende:n Nutzer:in in Braze und bestätigen Sie, dass das erwartete angepasste Attribut, angepasste Event oder der Kauf im Profil erscheint. Nutzer:innen werden über external_id (oder den in Schritt 1 gewählten Bezeichnertyp) abgeglichen.
3. Um die Gegenrichtung zu überprüfen, führen Sie einen Braze-Testversand durch, der einen der Webhooks aus Schritt 2 aufruft, und bestätigen Sie die Aktion in Convercus (Coupon zugewiesen, Punkte gebucht oder Abo aktualisiert).

Convercus mit Braze verwenden

Schritt 1: Nachrichten mit synchronisierten Treue-Daten personalisieren

Sobald die Integration aktiv ist, treffen Convercus-Events über den /users/track-Endpunkt auf jedem Kundenprofil in Braze ein und können wie alle anderen nativen Daten verwendet werden:

1. Verwenden Sie angepasste Attribute für die Kundenbindung (zum Beispiel convercus_status_level, convercus_balance) in Segments, um Stufeninhaber:innen, Mitglieder mit hohem Punktestand oder kürzlich herabgestufte Nutzer:innen anzusprechen.
2. Verwenden Sie angepasste Events (zum Beispiel convercus_status_level_changed, Gutschein- und Mitgliedschafts-Events) als Trigger-Schritte in Canvas oder als Filter in Campaigns zur erneuten Interaktion.
3. Referenzieren Sie beliebige dieser Felder in Liquid für die Personalisierung in Nachrichten (Betreffzeilen, Textkörper, Push-Titel).
4. Verwenden Sie purchase-Events, die von Convercus gestreamt werden, um produktbezogene Journeys auszulösen (Nachbestellung, Kategorie-Upselling, Bewertungsanfragen nach dem Kauf).

Angepasste Attribute

Hinweis

Innerhalb eines Braze-Workspace werden Mitglieder eindeutig durch convercus_account_id identifiziert. convercus_user_id identifiziert die zugrunde liegende Person über mehrere Convercus-Programme hinweg und wird für programmübergreifende Analytics bereitgestellt; verwenden Sie für die Segmentierung innerhalb von Braze convercus_account_id.

email_subscribe-Abbildung

Angepasste Events

Käufe

Convercus-Transaktionen vom Typ EARNTRANSACTION (Punkte, die durch Kundenausgaben verdient werden) werden an Braze als Käufe gemeldet und in Braze-Umsatzanalysen, RFM-Segmentierung und prädiktiven Features gezählt – unter Verwendung der Transaktions-ID als Produktbezeichner sowie des Transaktionsbetrags und der Währung als Preis und Währung.

Transaktionen vom Typ PAYWITHPOINTSTRANSACTION (Punkte einlösen) werden nicht als Käufe gemeldet – sie fließen als das angepasste Event convercus_account_transaction ein, damit sie für die Segmentierung verfügbar bleiben. Stornierungen und Aufhebungen von Verdienst-Transaktionen werden als Käufe mit negativem Preis gemeldet, sodass der Braze-Umsatz mit Convercus übereinstimmt.

Schritt 2: Live-Kundenbindungsdaten mit Connected Content abrufen

Für Werte, die zum Sendezeitpunkt aktuell sein müssen – aktueller Punktestand, aktive Gutscheine, aktuelle Stufe – rufen Sie Convercus aus Braze über Connected Content auf, anstatt sich auf das zuletzt synchronisierte Attribut zu verlassen. Beide Endpunkte befinden sich unter derselben Basis-URL wie die Webhooks und erfordern den X-Convercus-Key-Header.

Connected-Content-Endpunkte geben bei erwarteten Fehlern immer HTTP 200 zurück, damit Liquid-Templates auf das Feld error verzweigen können:

Beispiel – den Kundenbindungsstatus eines Mitglieds rendern (Stufe, Punkte und aktive Angebote):

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 %}

Umschließen Sie Connected Content immer mit Bedingungen (prüfen Sie member.error und leere coupons), damit ein vorübergehender Lookup-Fehler niemals eine fehlerhafte Nachricht versendet. Cachen Sie das Profil (cache_max_age 300), aber nicht die Gutscheine (cache_max_age 0), da sich der Gutscheinstatus zwischen Sendungen ändern kann.

Überlegungen

• Latenz: Convercus-zu-Braze-Events werden über Kafka übertragen und erreichen Braze unter normaler Last innerhalb von Sekunden.
• Braze-Rate-Limits: Die Integration führt bei 429-Antworten automatisch Wiederholungsversuche durch und berücksichtigt dabei den x-ratelimit-retry-after-Header von Braze mit exponentiellem Backoff.
• Connected-Content-Caching: Braze speichert Connected-Content-Antworten standardmäßig für mehrere Minuten im Cache. Für Werte, die zum Sendezeitpunkt exakt sein müssen (z. B. Punktestand), verkürzen oder umgehen Sie das Cache-Fenster im Connected-Content-Aufruf.
• Eine Konfiguration pro Programm: Jedes Kundenbindungs-Programm wird einem einzelnen Braze-Workspace zugeordnet. Um einen zweiten Workspace zu verbinden, konfigurieren Sie ihn in einem separaten Programm.
• Observability: API-Aufrufstatistiken und Fehlerverlauf pro Programm (in beide Richtungen) werden 90 Tage lang aufbewahrt und sind über die Braze-Integrationskarte im Selfservice verfügbar.

Fehlerbehebung

• Events erscheinen nicht in Braze: Überprüfen Sie, ob der als Bezeichner verwendete Wert (ausgewählt in Schritt 1) mit der external_id (oder dem gewählten Bezeichnertyp) der Nutzer:innen in Braze übereinstimmt. Nicht übereinstimmende Bezeichner führen dazu, dass Events dem falschen Profil zugeordnet oder verworfen werden.
• Webhook gibt 401 zurück: Der X-Convercus-Key-Header fehlt oder der cvc_…-API-Schlüssel wurde widerrufen. Generieren Sie den Schlüssel im Selfservice neu und aktualisieren Sie die Webhook-Aktion in Braze.
• Webhook gibt 400 zurück: In der Anfrage fehlt Content-Type: application/json, oder der Payload entspricht nicht dem dokumentierten Schema. Beim E-Mail-Abo-Webhook bedeutet ein 400 auch, dass die angeforderten Opt-ins dem Programm unbekannt sind oder keine konfiguriert wurden.
• Weitergehende Fehleranalyse: Überprüfen Sie die API-Aufrufstatistiken und den Fehlerverlauf pro Programm auf der Braze-Integrationskarte im Selfservice, oder kontaktieren Sie Ihre Convercus-Vertretung.