Connected-Content-API-Aufruf durchführen

Verwenden Sie Connected-Content, um beliebige über eine API zugängliche Informationen direkt in Nachrichten einzufügen, die Sie an Nutzer:innen senden. Sie können Inhalte entweder direkt von Ihrem Webserver oder von öffentlich zugänglichen APIs abrufen.

Diese Seite behandelt, wie Sie Connected-Content-API-Aufrufe durchführen, fortgeschrittene Connected-Content-Anwendungsfälle, Fehlerbehandlung und mehr.

Connected-Content-Aufrufvolumen verstehen

Wichtig

Ein Versand entspricht nicht einem Connected-Content-Aufruf. Braze garantiert kein 1:1-Verhältnis zwischen Nachrichtenversand und Connected-Content-Anfragen. Das System ist darauf ausgelegt, korrektes Nachrichten-Rendering und korrekte Zustellung gegenüber der Minimierung der Anzahl von Aufrufen zu bevorzugen. Ihre Endpunkte müssen so konzipiert sein, dass sie mehr Anfragen verarbeiten können als die Anzahl der Empfänger:innen oder gesendeten Nachrichten.

Braze kann denselben Connected-Content-API-Aufruf pro Empfänger:in mehr als einmal durchführen. Häufige Gründe sind:

• E-Mail mit mehreren Teilen: Eine einzelne E-Mail kann separate Rendering-Durchläufe für den HTML-Body, den Nur-Text-Body und die Accelerated Mobile Pages (AMP)-Version (falls vorhanden) auslösen. Jeder Durchlauf kann Connected-Content in diesem Teil auslösen, sodass eine Empfängerin oder ein Empfänger mehrere identische oder ähnliche Aufrufe erzeugen kann.
• Validierung und Wiederholungsversuche: Nachrichten-Payloads können pro Empfänger:in mehrmals für Validierung, Wiederholungslogik oder andere interne Zwecke gerendert werden.
• Kanalverhalten: Connected-Content wird ausgeführt, wenn die Nachricht gerendert wird. Bei In-App Messages wird die Nachricht zum Zeitpunkt der Impression gerendert.

Wenn Sie in Ihren Logs mehr Connected-Content-Aufrufe als Versendungen oder Empfänger:innen sehen, ist dieses Verhalten erwartungsgemäß. Hinweise zur Reduzierung der Last und zur Skalierungsplanung finden Sie unter Best Practices für Endpunkte mit hohem Volumen.

Einen Connected-Content-Aufruf senden

Um einen Connected-Content-Aufruf zu senden, verwenden Sie den {% connected_content %}-Tag. Mit diesem Tag können Sie Variablen zuweisen oder deklarieren, indem Sie :save verwenden. Aspekte dieser Variablen können später in der Nachricht mit Liquid referenziert werden.

Den API-Aufruf aufschlüsseln

Das folgende Beispiel verwendet die Sunrise-Sunset-API und fügt die heutige Sonnenaufgangszeit in eine Nachricht ein:

1
2
{% connected_content https://api.sunrise-sunset.org/v2?lat=40.7128&lng=-74.0060&date=today :save result %}
Hi there, today's sunrise in NYC is at {{result.sunrise}}.

Hier ist die Funktion jedes Teils:

Wie die Sunrise-Sunset-API-Antwort funktioniert

Dieser Endpunkt gibt JSON mit Feldern auf oberster Ebene wie sunrise, sunset und tzid zurück. Zeiten werden standardmäßig in der Zeitzone des Standorts zurückgegeben (in diesem Beispiel New Yorker Zeit).

Die Antwortstruktur sieht beispielsweise so aus:

1
2
3
4
5
6
{
  "date": "2026-07-23",
  "tzid": "America/New_York",
  "sunrise": "2026-07-23T05:42:11-04:00",
  "sunset": "2026-07-23T20:21:32-04:00"
}

Die API-Antwort auf Liquid abbilden

Da die Antwort als result gespeichert wird, können Sie jedes Feld direkt von diesem Objekt referenzieren.

1
2
3
{{result.sunrise}}
{{result.sunset}}
{{result.tzid}}

Verwenden Sie dieses Muster immer, wenn Sie JSON aus Connected-Content speichern:

1. Speichern Sie die API-Antwort mit :save.
2. Finden Sie das gewünschte Feld in der JSON-Antwort.
3. Referenzieren Sie es in Liquid als saved_variable.field_name.

Variablen hinzufügen

Sie können auch Nutzerprofil-Attribute als Variablen in den URL-String einfügen, wenn Sie Connected-Content-Anfragen stellen.

Beispielsweise könnten Sie einen Webdienst haben, der Inhalte basierend auf der E-Mail-Adresse und ID einer Nutzerin oder eines Nutzers zurückgibt. Wenn Sie Attribute übergeben, die Sonderzeichen enthalten, wie das At-Zeichen (@), stellen Sie sicher, dass Sie den Liquid-Filter url_param_escape verwenden, um alle in URLs nicht zulässigen Zeichen durch ihre URL-freundlichen, escapten Versionen zu ersetzen, wie im folgenden E-Mail-Adress-Attribut gezeigt.

1
2
3
Hi, here are some articles that you might find interesting:

{% connected_content http://www.yourwebsite.com/articles?email={{${email_address} | url_param_escape}}&user_id={{${user_id}}} %}

Hinweis

Attributwerte müssen von ${} umgeben sein, damit sie in unserer Version der Liquid-Syntax korrekt funktionieren.

Connected-Content-Anfragen unterstützen ausschließlich GET- und POST-Anfragen.

Fehlerbehandlung

Wenn die URL nicht erreichbar ist und eine 404-Seite zurückgibt, rendert Braze an deren Stelle einen leeren String. Wenn die URL eine HTTP-500- oder 502-Seite zurückgibt, schlägt die URL bei der Wiederholungslogik fehl.

Wenn der Endpunkt JSON zurückgibt, können Sie dies erkennen, indem Sie prüfen, ob der connected-Wert null ist, und dann die Nachricht bedingt abbrechen. Braze erlaubt nur URLs, die über Port 80 (HTTP) und 443 (HTTPS) kommunizieren.

Erkennung fehlerhafter Hosts

Connected Content verwendet einen Mechanismus zur Erkennung fehlerhafter Hosts, der erkennt, wenn der Zielhost eine hohe Rate an erheblicher Verlangsamung oder Überlastung aufweist, was zu Timeouts, zu vielen Anfragen oder anderen Ergebnissen führt, die Braze daran hindern, erfolgreich mit dem Zielendpunkt zu kommunizieren. Er dient als Schutzmaßnahme, um unnötige Last zu reduzieren, die den Zielhost möglicherweise beeinträchtigt. Außerdem dient er der Stabilisierung der Braze-Infrastruktur und der Aufrechterhaltung schneller Messaging-Geschwindigkeiten.

Wenn der Zielhost eine hohe Rate an erheblicher Verlangsamung oder Überlastung aufweist, stoppt Braze vorübergehend Anfragen an den Zielhost für eine Minute und simuliert stattdessen Antworten, die den Fehler anzeigen. Nach einer Minute prüft Braze den Zustand des Hosts mit einer kleinen Anzahl von Anfragen, bevor die Anfragen mit voller Geschwindigkeit wieder aufgenommen werden, sofern der Host als gesund eingestuft wird. Wenn der Host weiterhin fehlerhaft ist, wartet Braze eine weitere Minute, bevor ein erneuter Versuch unternommen wird.

Wenn Anfragen an den Zielhost durch die Erkennung fehlerhafter Hosts gestoppt werden, rendert Braze weiterhin Nachrichten und folgt Ihrer Liquid-Logik, als hätte es einen Fehlerantwortcode erhalten. Wenn Sie sicherstellen möchten, dass diese Connected-Content-Anfragen erneut versucht werden, wenn sie durch die Erkennung fehlerhafter Hosts gestoppt werden, verwenden Sie die Option :retry. Weitere Informationen zur Option :retry finden Sie unter Connected-Content-Wiederholungen.

Wenn Sie vermuten, dass die Erkennung fehlerhafter Hosts Probleme verursacht, wenden Sie sich an den Braze-Support.

Hinweis

Sie können bestimmte URLs auf eine Zulassungsliste setzen, die für Connected Content verwendet werden sollen. Um auf dieses Feature zuzugreifen, wenden Sie sich an Ihren Customer-Success-Manager.

Tipp

Weitere Informationen zu häufigen Fehlercodes finden Sie unter Fehlerbehebung bei Webhook- und Connected-Content-Anfragen.

Rate-Limits (429) im Vergleich zur Erkennung fehlerhafter Hosts

Die folgenden Mechanismen sind unterschiedlich:

• 429 Too Many Requests: Ihr Endpunkt (oder ein vorgelagerter Dienst) gibt diese Antwort zurück. Das bedeutet, dass Ihr Server oder Ihre Middleware den Datenverkehr ablehnt, häufig weil ein eigenes Rate-Limit vorhanden ist. Braze wendet kein separates Rate-Limit auf Connected Content an; das Anfragevolumen von Connected Content skaliert direkt mit Ihrem Rate-Limit für die Zustellgeschwindigkeit. Da Nachrichten pro Empfänger:in mehrfach gerendert werden können (zum Beispiel für E-Mail-HTML, Nur-Text und AMP), kann die Anzahl der Connected-Content-Anfragen dieses Rate-Limit überschreiten – gehen Sie nicht davon aus, dass sie kleiner oder gleich der von Ihnen festgelegten Nachrichten pro Minute ist. Wenn Sie 429-Fehler sehen, skalieren Sie Ihren Endpunkt oder Ihre Middleware, um das erwartete Anfragevolumen zu bewältigen, oder senken Sie das Rate-Limit für die Zustellgeschwindigkeit der Campaign oder des Canvas, damit weniger Nachrichten (und somit weniger Connected-Content-Aufrufe) pro Minute gesendet werden.
• Erkennung fehlerhafter Hosts: Eine Braze-seitige Schutzmaßnahme, die nach einer hohen Rate und einem hohen Volumen an Fehlern innerhalb eines Einminutenfensters ausgelöst wird. Die Fehleranzahl umfasst die Statuscodes 408, 429, 502, 503, 504 und 529. Wenn sie ausgelöst wird, stoppt Braze vorübergehend Anfragen an diesen Host und simuliert eine Fehlerantwort. Dies ist unabhängig von Ihrem eigenen Rate-Limiting. Informationen zu Erkennungsschwellenwerten und weitere Details finden Sie unter Fehlerbehebung bei Webhook- und Connected-Content-Anfragen. Um die Erkennung fehlerhafter Hosts zu vermeiden, stellen Sie sicher, dass Ihr Endpunkt das unter Aufrufvolumen von Connected Content verstehen und Best Practices für Endpunkte mit hohem Volumen beschriebene Aufrufvolumen bewältigen kann.

Effiziente Performance ermöglichen

Da Braze Nachrichten mit sehr hoher Geschwindigkeit zustellt, stellen Sie sicher, dass Ihr Server Tausende gleichzeitiger Verbindungen verarbeiten kann, damit er beim Abrufen von Inhalten nicht überlastet wird. Wenn Sie öffentliche APIs verwenden, bestätigen Sie, dass Ihre Nutzung keine Rate-Limits verletzt, die der API-Anbieter möglicherweise einsetzt. Braze erfordert aus Performance-Gründen, dass die Serverantwortzeit weniger als zwei Sekunden beträgt; wenn der Server länger als zwei Sekunden für die Antwort benötigt, wird der Inhalt nicht eingefügt.

Weitere Informationen zur Planung der Endpunktkapazität und zur Reduzierung des Aufrufvolumens finden Sie unter Best Practices für Endpunkte mit hohem Volumen.

Wissenswertes

• Braze berechnet keine Gebühren für API-Aufrufe und zählt diese nicht zu Ihrer Datenpunkt-Nutzung.
• Für Connected-Content-Antworten gilt ein Limit von 1 MB.
• Connected Content wird ausgeführt, wenn die Nachricht gerendert wird. Bei In-App-Nachrichten wird die Nachricht zum Zeitpunkt der Impression gerendert.
• Connected-Content-Aufrufe folgen keinen Weiterleitungen. Nur 2xx-Antworten werden als erfolgreich behandelt. Wenn Ihr Endpunkt eine 3xx-Weiterleitung zurückgibt (z. B. 301 oder 302), folgt Braze der Weiterleitung nicht zur endgültigen URL. Informationen zu Symptomen und Schritten zur Fehlerbehebung finden Sie unter Warum schlägt Connected Content fehl, wenn mein Endpunkt eine Weiterleitung zurückgibt?.

Wie Connected-Content-Aufrufe verarbeitet werden

Connected-Content-Aufrufe innerhalb eines einzelnen Nachrichten-Templates werden während des Liquid-Renderings sequenziell (von oben nach unten) ausgeführt. Das bedeutet, dass nachfolgende Aufrufe auf Variablen zugreifen können, die von vorherigen Aufrufen gesetzt wurden. In diesem Beispiel ruft der erste Aufruf Nutzerdaten ab, und der zweite Aufruf verwendet diese Daten, um Präferenzen abzurufen:

1
2
{% connected_content https://api.example.com/user :save user_data %}
{% connected_content https://api.example.com/preferences?user_id={{user_data.id}} :save preferences %}

Globaler Versand und Anfragevolumen

Während Connected-Content-Aufrufe innerhalb einer einzelnen Nachricht sequenziell ausgeführt werden, werden Nachrichten über Ihre Campaigns und Canvases hinweg parallel gesendet. Versendungen mit hohem Volumen können während Spitzenzeiten erheblichen Anfrage-Traffic an Ihre Endpunkte erzeugen. Informationen zur Verwaltung und Drosselung dieses Traffics – einschließlich Workspace-Messaging-Rate-Limits, Rate-Limiting für die Zustellgeschwindigkeit und Caching – finden Sie unter Best Practices für Endpunkte mit hohem Volumen.

Best Practices für Endpunkte mit hohem Volumen

Wenn Ihre Nachrichten Connected-Content verwenden und Sie in hohem Volumen senden, planen Sie mehr Anfragen ein als die Anzahl der Empfänger:innen oder Sends:

• Spitzenlast abschätzen: Verwenden Sie einen konservativen Multiplikator, wenn Sie Ihren Endpunkt oder Ihre Middleware dimensionieren – Connected-Content-Anfragen können die Anzahl der Empfänger:innen oder gesendeten Nachrichten übersteigen. Bei E-Mails kann beispielsweise eine einzelne Empfängerin oder ein einzelner Empfänger mehrere Aufrufe erzeugen (HTML, Nur-Text und AMP), sodass Empfänger:innen × 2 oder × 3 häufig als konservative Schätzung verwendet wird.
• Caching nutzen, wo es sinnvoll ist: GET-Anfragen werden standardmäßig gecacht. Fügen Sie bei POST-Anfragen :cache_max_age hinzu, wenn die Antwort für einen bestimmten Zeitraum wiederverwendet werden kann (zum Beispiel Token oder Inhalte, die sich nicht pro Anfrage ändern). Siehe Antworten cachen und die FAQ zum POST-Caching im folgenden Abschnitt.
• Rate-Limits für Nachrichten festlegen: Workspace-Messaging-Rate-Limits und Zustellgeschwindigkeits-Rate-Limiting für Campaigns oder Canvases begrenzen indirekt das Volumen der Connected-Content-Anfragen – Braze selbst wendet kein Rate-Limiting auf Connected Content an. Diese Einstellungen sind Näherungswerte, keine exakten Steuerungen, da Connected-Content-Anfragen nicht im Verhältnis 1:1 zu Nachrichten stehen. Nutzen Sie sie, um das Nachrichten- (und damit Connected-Content-)Volumen innerhalb der Kapazität Ihres Endpunkts zu halten.
• Idempotenz und Wiederholungsversuche einplanen: Braze kann Ihren Endpunkt pro Empfänger:in mehr als einmal aufrufen. Stellen Sie sicher, dass Ihr Endpunkt doppelte Anfragen ohne unerwünschte Nebeneffekte verarbeiten kann.

Authentifizierungstypen

Einfache Authentifizierung verwenden

Wenn die URL eine einfache Authentifizierung erfordert, kann Braze Zugangsdaten für die einfache Authentifizierung speichern, die Sie in Ihrem API-Aufruf verwenden können. Sie können bestehende Zugangsdaten für die einfache Authentifizierung verwalten und neue hinzufügen unter Einstellungen > Connected-Content.

Um neue Zugangsdaten hinzuzufügen, wählen Sie Zugangsdaten hinzufügen > Einfache Authentifizierung.

Geben Sie Ihren Zugangsdaten einen Namen und tragen Sie den Benutzernamen und das Passwort ein.

Sie können diese Zugangsdaten für die einfache Authentifizierung dann in Ihren API-Aufrufen verwenden, indem Sie den Namen des Tokens referenzieren:

1
Hi there, here is some fun trivia for you!: {% connected_content https://yourwebsite.com/random/trivia :basic_auth credential_name %}

Hinweis

Wenn Sie Zugangsdaten löschen, beachten Sie, dass alle Connected-Content-Aufrufe, die versuchen, diese zu verwenden, abgebrochen werden.

Gespeicherte Zugangsdaten gelten für {% connected_content %}-Anfragen, während Braze eine Nachricht rendert. Sie werden nicht auf die primäre HTTP-Anfrage angewendet, die in einem Webhook-Schritt konfiguriert ist. Verwenden Sie Anfrage-Header oder ein {% connected_content %}-Tag innerhalb eines Webhook-Header- oder Body-Felds, wenn Sie Secrets für diesen Aufruf abrufen müssen.

Token-Authentifizierung verwenden

Bei der Verwendung von Braze Connected-Content kann es vorkommen, dass bestimmte APIs anstelle eines Benutzernamens und Passworts ein Token erfordern. Braze kann auch Zugangsdaten speichern, die Token-Authentifizierungs-Header-Werte enthalten.

Um Zugangsdaten hinzuzufügen, die Token-Werte enthalten, wählen Sie Zugangsdaten hinzufügen > Token-Authentifizierung. Fügen Sie dann die Schlüssel-Wert-Paare für Ihre API-Aufruf-Header und die zulässige Domain hinzu.

Sie können diese Zugangsdaten dann in Ihren API-Aufrufen verwenden, indem Sie den Namen der Zugangsdaten referenzieren:

1
2
3
4
5
6
7
8
9
{% assign campaign_name="New Year Sale" %}
{% connected_content
     https://api.endpoint.com/your_path
     :method post
     :auth_credentials token_credential_abc
     :body campaign={{campaign_name}}&customer={{${user_id}}}&channel=Braze
     :content_type application/json
     :save publication
%}

Open Authentication (OAuth) verwenden

Einige API-Konfigurationen erfordern das Abrufen eines Zugriffstokens, das dann zur Authentifizierung des API-Endpunkts verwendet werden kann, auf den Sie zugreifen möchten.

Schritt 1: Zugriffstoken abrufen

Das folgende Beispiel zeigt das Abrufen und Speichern eines Zugriffstokens in einer lokalen Variablen, die dann zur Authentifizierung des nachfolgenden API-Aufrufs verwendet werden kann. Ein :cache_max_age-Parameter kann hinzugefügt werden, um die Gültigkeitsdauer des Zugriffstokens abzugleichen und die Anzahl der ausgehenden Connected-Content-Aufrufe zu reduzieren. Weitere Informationen finden Sie unter Konfigurierbares Caching.

1
2
3
4
5
6
7
8
9
10
{% connected_content
     https://your_API_access_token_endpoint_here/
     :method post
     :auth_credentials access_token_credential_abc
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE"
     }
     :cache_max_age 900
     :save token_response
%}

Hinweis

Wenn der Token-Endpunkt application/x-www-form-urlencoded erwartet und Sie Zugangsdaten in :body übergeben, URL-kodieren Sie alle Sonderzeichen in Parameterwerten. Zum Beispiel werden Schrägstriche (/) zu %2F und Pluszeichen (+) zu %2B. Nicht kodierte Sonderzeichen können dazu führen, dass OAuth-Token-Anfragen fehlschlagen.

Schritt 2: API mit dem abgerufenen Zugriffstoken autorisieren

Nachdem das Token gespeichert wurde, kann es dynamisch in den nachfolgenden Connected-Content-Aufruf eingebunden werden, um die Anfrage zu autorisieren:

1
2
3
4
5
6
7
8
9
{% connected_content
     https://your_API_endpoint_here/
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE",
       "Authorization": "{{token_response}}"
     }
     :body key1=value1&key2=value2
     :save response
%}

Zugangsdaten bearbeiten

Sie können den Namen der Zugangsdaten für Authentifizierungstypen bearbeiten.

• Bei der einfachen Authentifizierung können Sie den Benutzernamen und das Passwort aktualisieren. Beachten Sie, dass das zuvor eingegebene Passwort nicht sichtbar sein wird.
• Bei der Token-Authentifizierung können Sie die Header-Schlüssel-Wert-Paare und die zulässige Domain aktualisieren. Beachten Sie, dass die zuvor festgelegten Header-Werte nicht sichtbar sein werden.

Connected-Content-IP-Allowlisting

Wenn eine Nachricht mit Connected Content von Braze gesendet wird, stellen die Braze-Server automatisch Netzwerkanfragen an die Server unserer Kund:innen oder Drittanbieter, um Daten abzurufen. Mit IP-Allowlisting können Sie überprüfen, ob Connected-Content-Anfragen tatsächlich von Braze stammen, und so eine zusätzliche Sicherheitsebene hinzufügen.

Braze sendet Connected-Content-Anfragen aus den folgenden IP-Bereichen. Die aufgeführten Bereiche werden automatisch und dynamisch zu allen API-Schlüsseln hinzugefügt, die für das Allowlisting aktiviert wurden.

Braze verfügt über einen reservierten Satz von IPs, die für alle Dienste verwendet werden, wobei nicht alle zu einem bestimmten Zeitpunkt aktiv sind. Dies ist so konzipiert, dass Braze bei Bedarf von einem anderen Rechenzentrum aus senden oder Wartungsarbeiten durchführen kann, ohne Kund:innen zu beeinträchtigen. Braze kann eine, eine Teilmenge oder alle der folgenden aufgeführten IPs verwenden, wenn Connected-Content-Anfragen gestellt werden.

Wenn Connected-Content-Anfragen durchgehend 403 Forbidden zurückgeben und die Authentifizierung korrekt konfiguriert ist, nehmen Sie diese IPs auf dem Server, der die Anfrage empfängt, in die Allowlist auf. Ein 403-Fehler kann auch auf unzureichende Berechtigungen oder ungültige Zugangsdaten hinweisen – überprüfen Sie daher sowohl die Netzwerk- als auch die Authentifizierungseinstellungen. Webhook-spezifische Hinweise finden Sie unter 403 Forbidden und IP-Allowlisting.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)
• south korea (kr)

IP-Allowlisting mit Amazon S3 verwenden

Wenn Sie Connected Content zum Abrufen von Dateien aus Amazon S3 verwenden, konfigurieren Sie Ihren Bucket so, dass nicht authentifizierte HTTP-GET-Anfragen von Braze-IP-Adressen zugelassen werden.

1. Fügen Sie eine Bucket-Richtlinie mit IP-Bedingungen hinzu: Gewähren Sie s3:GetObject für Ihre Bucket-Objekte mit Principal: "*" und einer IpAddress-Bedingung, die die Braze-IP-Bereiche für Ihre Instanz verwendet. Sie müssen keine öffentlichen Lese-ACLs für einzelne Objekte festlegen.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-bucket-name/*",
      "Condition": {
        "IpAddress": {
          "aws:SourceIp": ["{YOUR_BRAZE_IP_RANGE}"]
        }
      }
    }
  ]
}

Ersetzen Sie {YOUR_BRAZE_IP_RANGE} durch die Braze-IP-Bereiche für Ihre Instanz, die unter Connected-Content-IP-Allowlisting aufgeführt sind. Sie können einen oder mehrere Bereiche als separate Werte im aws:SourceIp-Array hinzufügen.

2. Überprüfen Sie die S3-Block-Public-Access-Einstellungen: Bucket-Richtlinien, die Principal: "*" verwenden, werden von AWS als öffentlicher Zugriff behandelt, auch mit IP-Bedingungen. Möglicherweise müssen Sie den auf Bucket-Richtlinien basierenden öffentlichen Zugriff zulassen, während der ACL-basierte öffentliche Zugriff blockiert bleibt.

3. Verwenden Sie die S3-Objekt-URL in Ihrem Connected-Content-Tag: Referenzieren Sie das Objekt mit seiner Standard-S3-URL (zum Beispiel https://your-bucket.s3.amazonaws.com/path/to/object.json).

Weitere Informationen zu Bucket-Richtlinien und Bedingungsschlüsseln finden Sie in der AWS-Dokumentation.

User-Agent-Header

Braze fügt allen Connected-Content- und Webhook-Anfragen einen User-Agent-Header hinzu, der dem folgenden ähnelt:

1
Braze Sender 75e404755ae1270441f07eb238f0faf25e44dfdc

Tipp

Beachten Sie, dass sich der Hash-Wert regelmäßig ändert. Wenn Sie den Datenverkehr nach User-Agent filtern, lassen Sie alle Werte zu, die mit Braze Sender beginnen.

Fehlerbehebung

Wenn Ihr Connected-Content-Aufruf nicht korrekt oder gar nicht gerendert wird, überprüfen Sie die folgenden Details:

• Bestätigen Sie, dass ein Connected-Content-Aufruf durchgeführt wurde: Sie können im Tab „Messaging-Verlauf“ überprüfen, ob ein Aufruf durchgeführt wurde. Sie können auch einen einzelnen Connected-Content-Request als Testversand senden.
• Überprüfen Sie über Postman oder einen CURL-Request, ob der gewünschte Request erfolgreich ist: Wenn der Request funktioniert und eine Antwort zurückgibt, vergleichen Sie den Request im Detail (einschließlich Header). Bestätigen Sie, dass die Header in Schlüssel-Wert-Paaren mit doppelten Anführungszeichen erfasst sind.
• Stellen Sie sicher, dass die Autorisierung korrekt gehandhabt wird: Bestätigen Sie, dass die Option :basic_auth/:auth_credentials verwendet wird und die Connected-Content-Autorisierung zu den Connected-Content-Workspace-Einstellungen hinzugefügt wurde. Manchmal erfordert die Connected-Content-URL Header über die Authentifizierung hinaus, die eingegeben werden müssen.
• Überprüfen Sie, ob die Daten im erwarteten Format vorliegen: Für den Antwort-Body parst Braze gültiges JSON in ein Liquid-Objekt; andernfalls wird die Antwort als Klartext behandelt (einschließlich HTML). Die Option :content_type setzt die ausgehenden Content-Type- und Accept-Header Ihres Requests und beeinflusst nicht das Parsen der Antwort. Wenn Ihr JSON für den Request-:body Leerzeichen enthält, folgen Sie der Anleitung im Abschnitt JSON-Body bereitstellen.
• Bestätigen Sie, dass die Daten korrekt geparst wurden: Überprüfen Sie, ob das Liquid korrekt auf das erwartete Feld verweist. Verwenden Sie für verschachteltes JSON {{sampleresult.data[0].sample_field}}, um auf das gewünschte verschachtelte Feld zu verweisen. Sie können die verschachtelten JSON-Eigenschaften überprüfen, indem Sie das erwartete Ergebnis mit RESPONSE:{{sampleresult.data}} ausgeben.
• Überprüfen Sie den Antwort-Statuscode: Der Antwort-Statuscode muss ein 2XX-Code sein. Connected Content bietet keine Möglichkeit, die Antwort zu verarbeiten, wenn der Code nicht 2XX ist.

Sie können auch Webhook.site verwenden, um Ihre Connected-Content-Aufrufe zu debuggen und Probleme mit den Request-Headern, dem Request-Body und anderen Informationen zu diagnostizieren, die im Aufruf gesendet werden.

1. Ersetzen Sie die URL in Ihrem Connected-Content-Aufruf durch die eindeutige URL, die auf der Website generiert wurde.
2. Zeigen Sie eine Vorschau an und testen Sie Ihre Campaign oder Ihren Canvas-Schritt, um die Requests auf dieser Website einzusehen.

Sie können auch überprüfen, ob der Liquid-Tag die Parameter enthält, die Ihr Endpunkt erwartet (zum Beispiel :method, :headers, :content_type, :body und :basic_auth, wenn erforderlich). Wenn Sie sich auf den HTTP-Statuscode-Schlüssel in einem gespeicherten JSON-Objekt verlassen, muss der Endpunkt ein JSON-Objekt und einen 2XX-Status zurückgeben.

Bei hohen Fehlerraten von Ihrem Host lesen Sie Erkennung fehlerhafter Hosts und Connected-Content-Aufrufvolumen.

Ampersand-Kodierung in E-Mail-POST-Requests

In E-Mail-Nachrichten konvertiert das HTML-Parsing automatisch kaufmännische Und-Zeichen (&) innerhalb von {% capture %}-Blöcken zu &. Bei application/x-www-form-urlencoded-POST-Requests führt dies dazu, dass der Request Parameternamen mit einem amp;-Präfix sendet (zum Beispiel amp;username), was den API-Aufruf unterbrechen kann.

Um dieses Problem zu umgehen, verwenden Sie den replace-Filter, um das amp;-Präfix zu entfernen, bevor Sie den Body an :body übergeben:

1
2
3
4
5
6
7
8
9
{% capture body_with_amps %}
grant_type=client_credentials&username=test&password=test
{% endcapture %}
{% connected_content https://api.example.com/token
   :method post
   :body {{body_with_amps | replace: "amp;", ""}}
   :content_type application/x-www-form-urlencoded
   :save token
%}

Häufig gestellte Fragen

Warum schlägt Connected Content fehl, wenn mein Endpunkt eine Weiterleitung (301 oder 302) zurückgibt?

Eine Weiterleitung kann dazu führen, dass Connected Content in der Vorschau oder beim Versand leer gerendert wird oder im Message Activity Log ein Fehler mit dem HTTP-Statuscode 301 oder 302 protokolliert wird. Postman und andere Clients folgen Weiterleitungen oft automatisch, sodass eine URL in Postman funktionieren kann, aber in Braze fehlschlägt.

Konfigurieren Sie Ihren Endpunkt so, dass er eine 2xx-Antwort (typischerweise 200) mit dem Antworttext unter der URL zurückgibt, die Braze aufruft. Wenn diese URL selbst eine Weiterleitung zurückgibt, ersetzen Sie sie durch die endgültige Ziel-URL.

Für verwandte Prüfungen, wenn Inhalte leer gerendert werden, siehe Connected Content gibt keinen Antworttext zurück.

Warum gibt es mehr Connected-Content-Aufrufe als Nutzer:innen oder Sendungen?

Braze kann denselben Connected-Content-API-Aufruf pro Empfänger:in mehr als einmal durchführen, um einen Nachrichten-Payload zu rendern. Nachrichten-Payloads können pro Empfänger:in mehrfach gerendert werden – für Validierung, Wiederholungslogik oder andere interne Zwecke. Beachten Sie jedoch, dass nur einer der Connected-Content-Aufrufe eine Nachricht befüllt.

Es ist zu erwarten, dass ein Connected-Content-API-Aufruf pro Empfänger:in mehr als einmal durchgeführt werden kann, auch wenn die Wiederholungslogik im Aufruf nicht verwendet wird. Wir empfehlen, das Rate-Limit aller Nachrichten, die Connected Content enthalten, festzulegen oder Ihre Server so zu konfigurieren, dass sie das erwartete Volumen besser bewältigen können, das mehrere Connected-Content-Aufrufe pro Nachrichtenversand berücksichtigt.

Weitere Informationen und Maßnahmen finden Sie unter Aufrufvolumen von Connected Content verstehen und Best Practices für Endpunkte mit hohem Volumen.

Wie funktioniert Rate-Limiting mit Connected Content?

Connected Content hat kein eigenes Rate-Limit. Stattdessen basiert das Rate-Limit auf der Nachrichtenversandrate. Wir empfehlen, das Messaging-Rate-Limit höher als Ihr beabsichtigtes Connected-Content-Rate-Limit festzulegen, wenn es mehr Connected-Content-Aufrufe als gesendete Nachrichten gibt.

Wie verhält sich das Caching?

GET-Anfragen werden standardmäßig gecacht (siehe Antworten cachen). POST-Anfragen werden standardmäßig nicht gecacht, aber Sie können das Caching aktivieren, indem Sie :cache_max_age zum Connected-Content-Aufruf hinzufügen. Dies kann die Endpunkt-Last reduzieren, wenn derselbe POST (zum Beispiel eine Token- oder Inhaltsanfrage) innerhalb des Cache-Fensters wiederholt durchgeführt würde.

1
{% connected_content https://api.example.com/token :method post :body grant_type=client_credentials :cache_max_age 900 :save token %}

Caching kann dazu beitragen, doppelte Connected-Content-Aufrufe zu reduzieren, garantiert aber nicht, dass nur ein einziger Aufruf pro Nutzer:in erfolgt. Die Cache-Dauer liegt zwischen fünf Minuten und vier Stunden. Alle Details finden Sie unter Antworten cachen.

Was ist das HTTP-Standardverhalten von Connected Content?

Standardmäßig setzt Connected-Content einen Content-Type-Header bei einer GET-HTTP-Anfrage auf application/json mit Accept: */*. Wenn Sie einen anderen Content-Typ benötigen, geben Sie ihn explizit an, indem Sie dem Tag :content_type your/content-type hinzufügen. Braze setzt dann sowohl den Content-Type- als auch den Accept-Header auf den von Ihnen angegebenen Typ.

1
{% connected_content https://api.sunrise-sunset.org/v2?lat=40.7128&lng=-74.0060&date=today :content_type application/json %}

Standardmäßig stellt Connected-Content eine HTTP-GET-Anfrage an die angegebene URL. Um stattdessen eine POST-Anfrage zu stellen, geben Sie :method post an.

Sie können optional einen POST-Body bereitstellen, indem Sie :body angeben, gefolgt von entweder einem Query-String im Format key1=value1&key2=value2&... oder einem Verweis auf erfasste Werte. Der Content-Typ ist standardmäßig auf application/x-www-form-urlencoded eingestellt. Wenn Sie :content_type application/json angeben und einen formular-URL-codierten Body wie key1=value1&key2=value2 bereitstellen, codiert Braze den Body vor dem Senden automatisch in JSON.

Connected-Content speichert POST-Aufrufe standardmäßig nicht im Cache. Sie können dieses Verhalten ändern, indem Sie :cache_max_age zum Connected-Content-POST-Aufruf hinzufügen.

• standard-content-typ
• application/json-content-typ

1
{% connected_content https://example.com/api/endpoint :method post :body key1=value1&key2=value2 %}

1
{% connected_content https://example.com/api/endpoint :method post :body key1=value1&key2=value2 :content_type application/json %}

Was passiert, wenn ich denselben Connected-Content-Aufruf an mehreren Stellen verwende?

Jeder Connected-Content-Tag wird separat ausgewertet, auch wenn mehrere Tags dieselbe URL und dieselben Parameter verwenden. Wenn URL und Cache-Einstellungen es zulassen, können identische Anfragen aus dem Cache bedient werden, anstatt eine neue ausgehende Anfrage auszulösen (siehe Antworten cachen für Details).