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-Campaigns zu steigern.

Diese Integration wird von Convercus gepflegt.

Über die Integration

Die Integration von Braze und Convercus ist bidirektional: Loyalty-Daten fließen in Echtzeit als angepasste Attribute, angepasste Events und Käufe in Braze, und Braze-Canvases und -Campaigns können über Webhooks Loyalty-Aktionen 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, Punkte-Transaktionen buchen, verdienen 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 Loyalty-Konnektoren Daten nur in eine Richtung übertragen, schließt Convercus den Kreislauf: Reagieren Sie in Braze auf ein Loyalty-Event, führen Sie eine Aktion in Convercus aus und messen Sie das Ergebnis zurück in Braze.

Anwendungsfälle

1. Stufenaufstiegs-Feier: Wenn ein Mitglied in Convercus eine Loyalty-Stufe aufsteigt, lösen Sie einen personalisierten Braze-Canvas mit einer Willkommensnachricht, einem stufenexklusiven Vorteil und der neuen Stufe sowie dem Punktestand des Mitglieds aus.
2. Geburtstags- und Meilenstein-Boni: Buchen Sie aus einer Braze-Journey heraus Bonuspunkte in Convercus zum Geburtstag oder Jubiläum eines Mitglieds und senden Sie dann eine Glückwunschnachricht, die den neuen Kontostand bestätigt.
3. Rückgewinnung inaktiver Mitglieder: Lassen Sie Braze für inaktive Mitglieder über einen Webhook einen personalisierten Coupon in Convercus zuweisen und diesen per E-Mail, Push und In-App-Nachrichten zustellen.
4. Live-Punktestand in Nachrichten: Verwenden Sie Connected-Content, um den Echtzeit-Punktestand eines Mitglieds in Braze-Liquid abzurufen und so Kadenzen wie „Sie sind nur noch X Punkte von Ihrer nächsten Prämie entfernt“ zu ermöglichen.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie Folgendes:

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

Integration

1. Schritt: 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 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.

2. Schritt: 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 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.

3. Schritt: 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

1. Schritt: Nachrichten mit synchronisierten Loyalty-Daten personalisieren

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

1. Verwenden Sie angepasste Loyalty-Attribute (zum Beispiel convercus_status_level, convercus_balance) in Segments, um Stufeninhaber:innen, Mitglieder mit hohem Kontostand oder kürzlich herabgestufte Nutzer:innen anzusprechen.
2. Verwenden Sie angepasste Events (zum Beispiel convercus_status_level_changed, Coupon- und Mitgliedschafts-Events) als Trigger-Schritte in Canvas oder als Filter in Campaigns zur erneuten Interaktion.
3. Referenzieren Sie jedes dieser Felder in Liquid für die Personalisierung innerhalb von Nachrichten (Betreffzeilen, Textkörper, Push-Titel).
4. Verwenden Sie purchase-Events, die von Convercus gestreamt werden, um produktbezogene Journeys zu steuern (Nachbestellung, Kategorie-Upsell, 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; für die Segmentierung innerhalb von Braze verwenden Sie convercus_account_id.

email_subscribe-Zuordnung

Angepasste Events

Käufe

Convercus-Transaktionen vom Typ EARNTRANSACTION (durch Kundenausgaben verdiente Punkte) werden an Braze als Käufe gemeldet und in Braze-Umsatz-Analytics, RFM-Segmentierung und prädiktiven Features gezählt — wobei die Transaktions-ID als Produktbezeichner und der Transaktionsbetrag sowie die Währung als Preis und Währung verwendet werden.

Transaktionen vom Typ PAYWITHPOINTSTRANSACTION (Punkteeinlösung) werden nicht als Käufe gemeldet — sie fließen als angepasstes Event convercus_account_transaction ein, sodass sie für die Segmentierung verfügbar bleiben. Stornierungen und Rückbuchungen von Earn-Transaktionen werden als Käufe mit negativem Preis gemeldet, um den Braze-Umsatz mit Convercus abzugleichen.

2. Schritt: Live-Loyalty-Daten mit Connected-Content abrufen

Für Werte, die zum Sendezeitpunkt aktuell sein müssen — aktueller Punktestand, aktive Coupons, neueste 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, sodass Liquid-Templates auf das Feld error verzweigen können:

Beispiel — den Loyalty-Status 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 Coupons (cache_max_age 0), da sich der Coupon-Status zwischen den Sendungen ändern kann.

Hinweise

• Latenz: Convercus-zu-Braze-Events werden über Kafka propagiert und erreichen Braze unter normaler Last innerhalb von Sekunden.
• Braze-Rate-Limits: Die Integration wiederholt automatisch bei 429-Antworten und berücksichtigt den x-ratelimit-retry-after-Header von Braze mit exponentiellem Backoff.
• Connected-Content-Caching: Braze cached Connected-Content-Antworten standardmäßig für mehrere Minuten. Für Werte, die zum Sendezeitpunkt exakt sein müssen (wie der 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.
• Beobachtbarkeit: Pro-Programm-API-Aufrufstatistiken und Fehlerverlauf (in beide Richtungen) werden 90 Tage lang aufbewahrt und sind über die Braze-Integrationskarte in 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:des Nutzer:in 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 in Selfservice neu und aktualisieren Sie die Webhook-Aktion in Braze.
• Webhook gibt 400 zurück: 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.
• Tiefergehende Fehlersuche: Überprüfen Sie die Pro-Programm-API-Aufrufstatistiken und den Fehlerverlauf auf der Braze-Integrationskarte in Selfservice oder kontaktieren Sie Ihre Convercus-Vertretung.