Passer au contenu

Cours d’apprentissage BrazeEffectuer un appel API de contenu connecté

Utilisez le contenu connecté pour insérer toute information accessible par API directement dans les messages que vous envoyez aux utilisateurs. Vous pouvez extraire du contenu directement depuis votre serveur web ou depuis des API accessibles publiquement.

Cette page explique comment effectuer des appels API de contenu connecté, et présente les cas d’usage avancés du contenu connecté, la gestion des erreurs, et plus encore.

Comprendre le volume d’appels de contenu connecté

Braze peut effectuer le même appel API de contenu connecté plus d’une fois par destinataire. Les raisons courantes incluent :

  • E-mail avec plusieurs parties : Un seul e-mail peut déclencher des passes de rendu distinctes pour le corps HTML, le corps en texte brut et la version pages mobiles accélérées (AMP) (si présente). Chaque passe peut déclencher le contenu connecté dans cette partie, de sorte qu’un destinataire peut générer plusieurs appels identiques ou similaires.
  • Validation et nouvelles tentatives : Les payloads de messages peuvent être rendus plusieurs fois par destinataire pour la validation, la logique de nouvelles tentatives ou d’autres raisons internes.
  • Comportement par canal : Le contenu connecté s’exécute lorsque le message est rendu. Pour les messages in-app, le message est rendu au moment de l’impression.

Si vous constatez plus d’appels de contenu connecté dans vos journaux que d’envois ou de destinataires, ce comportement est attendu. Pour des conseils sur la réduction de la charge et la planification de la montée en charge, consultez Bonnes pratiques pour les endpoints à haut volume.

Envoyer un appel de contenu connecté

Pour envoyer un appel de contenu connecté, utilisez l’étiquette {% connected_content %}. Avec cette étiquette, vous pouvez attribuer ou déclarer des variables à l’aide de :save. Vous pourrez ensuite faire référence à certains éléments de ces variables plus loin dans le message avec Liquid.

Décomposer l’appel API

L’exemple suivant utilise l’API Sunrise-Sunset et ajoute l’heure du lever du soleil du jour dans un message :

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

Voici le rôle de chaque élément :

Composant Rôle
Étiquette connected_content Indique à Braze d’effectuer une requête HTTP pendant le rendu du message.
https://api.sunrise-sunset.org/v2 L’endpoint de l’API appelé par Braze.
lat=40.7128&lng=-74.0060 Paramètres de requête correspondant aux coordonnées de New York.
date=today Demande les données du jour pour ces coordonnées.
:save result Enregistre la réponse de l’API dans une variable locale nommée result.

Fonctionnement de la réponse de l’API Sunrise-Sunset

Cet endpoint renvoie du JSON avec des champs de premier niveau tels que sunrise, sunset et tzid. Par défaut, les heures sont renvoyées dans le fuseau horaire de l’emplacement (dans cet exemple, l’heure de New York).

Par exemple, la structure de la réponse ressemble à ceci :

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

Mapper la réponse de l’API dans Liquid

La réponse étant enregistrée sous le nom result, vous pouvez faire référence à chaque champ directement à partir de cet objet.

{{result.sunrise}}
{{result.sunset}}
{{result.tzid}}

Suivez ce modèle chaque fois que vous enregistrez du JSON issu du contenu connecté :

  1. Enregistrez la réponse de l’API avec :save.
  2. Repérez le champ souhaité dans la réponse JSON.
  3. Faites-y référence dans Liquid sous la forme saved_variable.field_name.

Ajouter des variables

Vous pouvez également inclure des attributs du profil utilisateur comme variables dans la chaîne de caractères de l’URL lorsque vous effectuez des requêtes de contenu connecté.

Par exemple, vous disposez peut-être d’un service web qui renvoie du contenu en fonction de l’adresse e-mail et de l’ID d’un utilisateur. Si vous transmettez des attributs contenant des caractères spéciaux, comme l’arobase (@), veillez à utiliser le filtre Liquid url_param_escape pour remplacer les caractères non autorisés dans les URL par leur version échappée compatible, comme dans l’attribut d’adresse e-mail ci-dessous.

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

Les requêtes de contenu connecté prennent uniquement en charge GET et POST. Pour les bannières, seules les requêtes GET sont prises en charge. Pour en savoir plus, consultez Contenu connecté pour les bannières.

Gestion des erreurs

Si l’URL est indisponible et renvoie une page 404, Braze affiche une chaîne vide à sa place. Si l’URL renvoie une page HTTP 500 ou 502, elle échoue selon la logique de nouvelle tentative.

Si l’endpoint renvoie du JSON, vous pouvez le détecter en vérifiant si la valeur connected est nulle, puis interrompre le message de manière conditionnelle. Braze n’autorise que les URL qui communiquent via le port 80 (HTTP) et le port 443 (HTTPS).

Détection des hôtes défaillants

Le contenu connecté utilise un mécanisme de détection des hôtes défaillants. Ce mécanisme repère les cas où l’hôte cible subit fréquemment des ralentissements importants ou une surcharge, avec pour résultat des délais d’attente dépassés, un trop grand nombre de requêtes ou d’autres problèmes qui empêchent Braze de communiquer avec l’endpoint cible. Il sert de garde-fou pour réduire une charge inutile qui pourrait mettre l’hôte cible en difficulté. Il contribue aussi à stabiliser l’infrastructure de Braze et à maintenir une vitesse d’envoi des messages élevée.

Si l’hôte cible subit fréquemment des ralentissements importants ou une surcharge, Braze suspend temporairement les requêtes vers cet hôte pendant une minute et simule à la place des réponses signalant l’échec. Au bout d’une minute, Braze vérifie l’état de l’hôte à l’aide d’un petit nombre de requêtes. Si l’hôte est jugé opérationnel, Braze reprend les requêtes à pleine vitesse. Si l’hôte est toujours défaillant, Braze attend une minute de plus avant de réessayer.

Si le détecteur d’hôtes défaillants suspend les requêtes vers l’hôte cible, Braze continue d’afficher les messages et de suivre votre logique Liquid comme s’il avait reçu un code de réponse d’erreur. Pour que ces requêtes de contenu connecté soient retentées lorsqu’elles sont suspendues par le détecteur, utilisez l’option :retry. Pour en savoir plus sur l’option :retry, consultez la page Nouvelles tentatives du contenu connecté.

Si vous pensez que la détection des hôtes défaillants est à l’origine de problèmes, contactez l’assistance Braze.

Limites de débit (429) et détection des hôtes défaillants

Il s’agit de deux mécanismes distincts :

  • 429 Too Many Requests : C’est votre endpoint (ou un service en amont) qui renvoie cette réponse. Elle signifie que votre serveur ou votre middleware refuse le trafic, souvent parce qu’il applique sa propre limite de débit. Braze n’applique pas de limite de débit distincte au contenu connecté. Le volume de requêtes de contenu connecté évolue directement en fonction de votre limite de débit de la vitesse d’envoi des messages. Un message pouvant être rendu plusieurs fois par destinataire (par exemple pour la version HTML, la version texte brut et la version AMP d’un e-mail), le nombre de requêtes de contenu connecté peut dépasser cette limite de débit. Ne partez donc pas du principe qu’il sera inférieur ou égal au nombre de messages par minute que vous avez défini. Si vous recevez des erreurs 429, adaptez votre endpoint ou votre middleware au volume de requêtes attendu, ou abaissez la limite de débit de la vitesse d’envoi de la campagne ou du Canvas afin d’envoyer moins de messages par minute, et donc moins d’appels de contenu connecté.
  • Détection des hôtes défaillants : Ce garde-fou côté Braze se déclenche lorsque le taux et le volume d’échecs sont élevés sur une fenêtre d’une minute. Le décompte des échecs inclut les codes de statut 408, 429, 502, 503, 504 et 529. Une fois le mécanisme déclenché, Braze suspend temporairement les requêtes vers cet hôte et simule une réponse d’échec. Ce mécanisme est indépendant de votre propre limitation du débit. Pour connaître les seuils de détection et obtenir plus de détails, consultez la page Résolution des problèmes liés aux requêtes de webhook et de contenu connecté. Pour éviter de déclencher la détection des hôtes défaillants, assurez-vous que votre endpoint peut gérer le volume d’appels décrit dans les sections Comprendre le volume d’appels du contenu connecté et Bonnes pratiques pour les endpoints à fort volume.

Permettre des performances efficaces

Comme Braze distribue les messages à un rythme très rapide, assurez-vous que votre serveur peut gérer des milliers de connexions simultanées afin qu’il ne soit pas surchargé lors de l’extraction de contenu. Lorsque vous utilisez des API publiques, vérifiez que votre utilisation ne viole pas les limites de débit que le fournisseur d’API peut appliquer. Braze exige que le temps de réponse du serveur soit inférieur à deux secondes pour des raisons de performance ; si le serveur met plus de deux secondes à répondre, le contenu n’est pas inséré.

Pour en savoir plus sur la planification de la capacité des endpoints et la réduction du volume d’appels, consultez Bonnes pratiques pour les endpoints à haut volume.

Ce qu’il faut savoir

  • Braze ne facture pas les appels API, et ceux-ci ne sont pas décomptés de votre consommation de points de données.
  • Les réponses du contenu connecté sont limitées à 1 Mo.
  • Le contenu connecté s’exécute au moment du rendu du message. Pour les messages in-app, le rendu a lieu au moment de l’impression.
  • Les appels de contenu connecté ne suivent pas les redirections. Seules les réponses 2xx sont considérées comme réussies. Si votre endpoint renvoie une redirection 3xx (par exemple 301 ou 302), Braze ne suit pas la redirection vers l’URL finale. Pour connaître les symptômes et les étapes de résolution des problèmes, consultez Pourquoi le contenu connecté échoue-t-il lorsque mon endpoint renvoie une redirection ?.

Traitement des appels de contenu connecté

Au sein d’un même modèle de message, les appels de contenu connecté s’exécutent de manière séquentielle (de haut en bas) lors du rendu Liquid. Les appels suivants peuvent donc faire référence aux variables définies par les appels précédents. Dans cet exemple, le premier appel récupère les données de l’utilisateur, puis le second utilise ces données pour obtenir ses préférences :

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

Envoi global et volume de requêtes

Si les appels de contenu connecté s’exécutent de manière séquentielle au sein d’un même message, les messages sont en revanche envoyés en parallèle sur l’ensemble de vos Campaigns et Canvas. Les envois à volume élevé peuvent générer un trafic de requêtes important vers vos endpoints pendant les pics d’envoi. Pour gérer et réguler ce trafic (notamment grâce aux limites de débit d’envoi de messages de l’espace de travail, à la limitation du débit de distribution et à la mise en cache), consultez la section Bonnes pratiques pour les endpoints à volume élevé.

Bonnes pratiques pour les endpoints à volume élevé

Si vos messages utilisent le contenu connecté et que vous envoyez des volumes importants, prévoyez plus de requêtes que de destinataires ou d’envois :

  • Estimez la charge maximale : Appliquez un multiplicateur prudent pour dimensionner votre endpoint ou votre middleware, car les requêtes de contenu connecté peuvent dépasser le nombre de destinataires ou de messages envoyés. Par exemple, pour l’e-mail, un seul destinataire peut générer plusieurs appels (HTML, texte brut et AMP). On utilise donc souvent une estimation prudente de destinataires × 2 ou × 3.
  • Utilisez la mise en cache lorsque c’est pertinent : Les requêtes GET sont mises en cache par défaut. Pour les requêtes POST, ajoutez :cache_max_age lorsque la réponse peut être réutilisée pendant un certain temps (par exemple, un jeton ou un contenu qui ne change pas d’une requête à l’autre). Consultez Mise en cache des réponses ainsi que la FAQ sur la mise en cache des requêtes POST dans la section suivante.
  • Définissez des limites de débit pour les messages : Les limites de débit des messages de l’espace de travail et la limitation du débit de la vitesse de distribution appliquées aux Campaigns ou aux Canvas limitent indirectement le volume de requêtes de contenu connecté. Braze n’applique en effet aucune limite de débit au contenu connecté lui-même. Ces limites ne sont qu’une approximation imparfaite, car les requêtes de contenu connecté ne correspondent pas une à une aux messages. Utilisez-les pour maintenir le volume de messages (et donc de contenu connecté) dans les limites de ce que votre endpoint peut gérer.
  • Prévoyez l’idempotence et les nouvelles tentatives : Braze peut appeler votre endpoint plusieurs fois par destinataire. Assurez-vous que votre endpoint tolère les requêtes en double sans provoquer d’effets secondaires indésirables.

Types d’authentification

Gérez vos identifiants enregistrés dans Paramètres > Gestion des identifiants. Vous pouvez utiliser ces identifiants pour le Contenu connecté et les webhooks. Pour la configuration des webhooks, consultez Utiliser un identifiant enregistré.

Utiliser l’authentification de base

Si l’URL nécessite une authentification de base, Braze peut stocker un nom d’utilisateur et un mot de passe que vous pourrez utiliser dans votre appel API.

Les paramètres du Contenu connecté dans le tableau de bord de Braze.

Pour ajouter un nouvel identifiant, sélectionnez Ajouter un identifiant > Authentification de base.

Menu déroulant « Ajouter un identifiant » avec l’option d’utiliser l’authentification de base ou l’authentification par jeton.

Donnez un nom à votre identifiant, puis saisissez le nom d’utilisateur et le mot de passe.

Le champ Domaine autorisé est facultatif pour l’authentification de base utilisée avec le Contenu connecté, mais obligatoire pour une utilisation avec les webhooks. Si vous le laissez vide, le Contenu connecté ne limite pas l’identifiant à un domaine particulier. Les identifiants d’authentification de base existants sans domaine conservent ce comportement.

Si vous saisissez un domaine, Braze limite l’identifiant à ce domaine et à tous ses sous-domaines, y compris pour les appels de Contenu connecté. Avant d’ajouter un domaine à un identifiant existant, vérifiez les destinations des appels qui l’utilisent déjà. Pour plus d’informations, consultez Choisir un domaine autorisé.

La fenêtre « Créer un nouvel identifiant » permettant de saisir un nom, un nom d’utilisateur et un mot de passe.

Vous pouvez ensuite utiliser cet identifiant d’authentification de base dans vos appels API en faisant référence au nom du jeton :

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

Faire référence à un identifiant dans une étiquette {% connected_content %} authentifie la requête de Contenu connecté lorsque Braze effectue le rendu du message. Pour authentifier la requête principale du webhook, sélectionnez un identifiant séparément dans l’éditeur de webhook. Consultez Authentification et identifiants de Contenu connecté.

Utiliser l’authentification par jeton

Lorsque vous utilisez le Contenu connecté de Braze, il est possible que certaines API exigent un jeton plutôt qu’un nom d’utilisateur et un mot de passe. Braze peut également stocker des identifiants contenant les valeurs d’en-tête d’authentification par jeton.

Pour ajouter un identifiant contenant des valeurs de jeton, sélectionnez Ajouter un identifiant > Authentification par jeton. Ajoutez ensuite les paires clé-valeur des en-têtes de votre appel API ainsi que le Domaine autorisé. Un domaine est obligatoire pour l’authentification par jeton. L’identifiant peut être utilisé avec ce domaine et tous ses sous-domaines. Consultez Choisir un domaine autorisé avant d’enregistrer.

Un exemple de jeton « token_credential_abc » avec les détails d’authentification par jeton.

Vous pouvez ensuite utiliser cet identifiant dans vos appels API en faisant référence au nom de l’identifiant :

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

Choisir un domaine autorisé

Saisissez un nom d’hôte, tel que api.example.com, sans http://, https://, port, chemin ni caractère générique. La correspondance de domaine n’est pas sensible à la casse. Le domaine autorisé inclut le nom d’hôte saisi et tous les sous-domaines qui en dépendent, aussi bien pour l’authentification de base que pour l’authentification par jeton.

Ces exemples montrent comment le domaine autorisé détermine les destinations vers lesquelles un identifiant peut être envoyé :

Domaine autorisé Exemple de nom d’hôte de la requête Autorisé ?
example.com example.com Oui
example.com api.example.com ou store.example.com Oui
example.com eu.api.example.com Oui
api.example.com api.example.com ou eu.api.example.com Oui
api.example.com example.com ou store.example.com Non
example.com example.com.other-domain.com Non

L’ajout ou la modification d’une restriction de domaine affecte les appels existants qui utilisent l’identifiant. Le Contenu connecté interrompt le message si un appel utilise l’identifiant avec un nom d’hôte situé en dehors de son domaine autorisé.

Gérer les identifiants enregistrés

Les mots de passe et les valeurs de jeton enregistrés ne sont pas affichés. Pour enregistrer vos modifications, saisissez de nouveau le mot de passe pour l’authentification de base, ou chaque valeur d’en-tête de jeton que vous conservez, même si vous modifiez uniquement le domaine autorisé. La marque substitutive masquée ne conserve pas le secret lorsque vous soumettez une modification.

Accédez à Paramètres > Gestion des identifiants. Vous devez disposer de l’autorisation « View Credential Management » pour accéder à cette page, et de l’autorisation « Edit Credential Management » pour créer, modifier ou supprimer des identifiants. Si nécessaire, demandez à l’administrateur de votre espace de travail de vous accorder ces autorisations.

Les identifiants appartiennent à un seul espace de travail. Si vous utilisez des espaces de travail distincts pour le développement, la préproduction et la production, créez les identifiants dans chaque espace de travail qui en a besoin.

La colonne Disponible dans indique où vous pouvez utiliser chaque identifiant :

  • Contenu connecté : un identifiant d’authentification de base sans domaine autorisé. Ajoutez un domaine autorisé pour l’utiliser avec les webhooks.
  • Contenu connecté, Webhooks : un identifiant avec un domaine autorisé. Il prend en charge le Contenu connecté et les webhooks, dans les limites de cette restriction de domaine.

Modifier un identifiant

Sélectionnez le nom de l’identifiant pour modifier, selon vos besoins, son nom d’utilisateur, son mot de passe, ses en-têtes de jeton ou son domaine autorisé. Le nom de l’identifiant ne peut pas être modifié après sa création.

Sélectionnez Modifier l’identifiant pour enregistrer.

Les identifiants sont partagés par les appels et les webhooks qui y font référence. Avant de modifier les informations d’authentification ou le domaine autorisé, vérifiez ces utilisations, puis testez les requêtes concernées après l’enregistrement.

Supprimer un identifiant

La boîte de dialogue de suppression vérifie l’utilisation de l’identifiant dans les campagnes de webhook, les Canvas et les modèles de webhook. Retirez ou remplacez l’identifiant dans chaque webhook répertorié avant de le supprimer. Les brouillons enregistrés et les objets en pause peuvent également bloquer la suppression.

La liste des utilisations ne couvre que les webhooks. Les références de Contenu connecté dans Liquid et dans les Content Blocks ne sont pas détectées. Vérifiez et mettez à jour ces références avant de supprimer l’identifiant. Retirez les utilisations de webhook répertoriées, confirmez l’avertissement relatif au Contenu connecté, puis sélectionnez Supprimer l’identifiant.

Utiliser l’authentification ouverte (OAuth)

Certaines configurations d’API nécessitent de récupérer un jeton d’accès, qui peut ensuite servir à authentifier l’endpoint de l’API auquel vous souhaitez accéder.

Étape 1 : Récupérer le jeton d’accès

L’exemple suivant illustre la récupération et l’enregistrement d’un jeton d’accès dans une variable locale, qui peut ensuite servir à authentifier l’appel API suivant. Vous pouvez ajouter un paramètre :cache_max_age correspondant à la durée de validité du jeton d’accès afin de réduire le nombre d’appels sortants de Contenu connecté. Pour plus d’informations, consultez Mise en cache configurable.

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

Étape 2 : Autoriser l’API à l’aide du jeton d’accès récupéré

Une fois le jeton enregistré, il peut être inséré dynamiquement dans l’appel de Contenu connecté suivant pour autoriser la requête :

{% connected_content
     https://your_API_endpoint_here/
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE",
       "Authorization": "{{token_response}}"
     }
     :body key1=value1&key2=value2
     :save response
%}

Modifier des identifiants

Vous pouvez modifier le nom de l’identifiant pour les différents types d’authentification.

  • Pour l’authentification de base, vous pouvez mettre à jour le nom d’utilisateur et le mot de passe. Notez que le mot de passe saisi précédemment ne sera pas visible.
  • Pour l’authentification par jeton, vous pouvez mettre à jour les paires clé-valeur des en-têtes ainsi que le domaine autorisé. Notez que les valeurs d’en-tête définies précédemment ne seront pas visibles.

Liste d’adresses IP autorisées pour le Contenu connecté

Lorsqu’un message utilisant le Contenu connecté est envoyé depuis Braze, les serveurs de Braze adressent automatiquement des requêtes réseau aux serveurs de nos clients ou de tiers afin de récupérer des données. La liste d’adresses IP autorisées vous permet de vérifier que les requêtes de Contenu connecté proviennent bien de Braze, ce qui ajoute une couche de sécurité.

Braze envoie les requêtes de Contenu connecté à partir des plages d’adresses IP suivantes. Ces plages sont ajoutées automatiquement et dynamiquement à toutes les clés API pour lesquelles la liste d’autorisation a été activée.

Braze dispose d’un ensemble réservé d’adresses IP utilisées pour tous ses services, qui ne sont pas toutes actives en même temps. Ce dispositif permet à Braze d’effectuer des envois depuis un autre centre de données ou de réaliser des opérations de maintenance, si nécessaire, sans impact pour les clients. Braze peut utiliser une seule, une partie ou l’ensemble des adresses IP suivantes pour effectuer des requêtes de Contenu connecté.

Si les requêtes de Contenu connecté renvoient systématiquement 403 Forbidden alors que l’authentification est correctement configurée, ajoutez ces adresses IP à la liste d’autorisation du serveur qui reçoit la requête. Une erreur 403 peut aussi signaler des autorisations insuffisantes ou des identifiants non valides : vérifiez donc à la fois les paramètres réseau et d’authentification. Pour des conseils spécifiques aux webhooks, consultez la section 403 Forbidden et liste d’adresses IP autorisées.

Pour les instances US-01, US-02, US-03, US-04, US-05, US-06, US-07, voici les adresses IP correspondantes :

  • 23.21.118.191
  • 34.206.23.173
  • 50.16.249.9
  • 52.4.160.214
  • 54.87.8.34
  • 54.156.35.251
  • 52.54.89.238
  • 18.205.178.15

Pour l’instance US-08, voici les adresses IP correspondantes :

  • 52.151.246.51
  • 52.170.163.182
  • 40.76.166.157
  • 40.76.166.170
  • 40.76.166.167
  • 40.76.166.161
  • 40.76.166.156
  • 40.76.166.166
  • 40.76.166.160
  • 40.88.51.74
  • 52.154.67.17
  • 40.76.166.80
  • 40.76.166.84
  • 40.76.166.85
  • 40.76.166.81
  • 40.76.166.71
  • 40.76.166.144
  • 40.76.166.145

Pour l’instance US-10, voici les adresses IP correspondantes :

  • 100.25.232.164
  • 35.168.86.179
  • 52.7.44.117
  • 3.92.153.18
  • 35.172.3.129
  • 50.19.162.19

Pour les instances EU-01 et EU-02, voici les adresses IP correspondantes :

  • 52.58.142.242
  • 52.29.193.121
  • 35.158.29.228
  • 18.157.135.97
  • 3.123.166.46
  • 3.64.27.36
  • 3.65.88.25
  • 3.68.144.188
  • 3.70.107.88

Pour l’instance AU-01, voici les adresses IP correspondantes :

  • 13.210.1.145
  • 13.211.70.159
  • 13.238.45.54
  • 52.65.73.167
  • 54.153.242.239
  • 54.206.45.213

Pour l’instance ID-01, voici les adresses IP correspondantes :

  • 108.136.157.246
  • 108.137.30.207
  • 16.78.128.71
  • 16.78.14.134
  • 16.78.162.208
  • 43.218.73.35

Pour l’instance JP-01, voici les adresses IP correspondantes :

  • 13.159.155.212
  • 54.199.221.241
  • 13.192.23.16
  • 54.250.120.139
  • 18.181.114.232
  • 3.114.38.100

Pour l’instance KR-01, voici les adresses IP correspondantes :

  • 43.200.215.4
  • 52.79.67.175
  • 52.79.113.60
  • 3.34.212.92
  • 54.116.134.231
  • 3.37.197.225

Utiliser la liste d’adresses IP autorisées avec Amazon S3

Lorsque vous utilisez le Contenu connecté pour récupérer des fichiers depuis Amazon S3, configurez votre compartiment pour autoriser les requêtes HTTP GET non authentifiées provenant des adresses IP de Braze.

  1. Ajoutez une politique de compartiment avec des conditions d’IP : Accordez s3:GetObject sur les objets de votre compartiment avec Principal: "*" et une condition IpAddress qui utilise les plages d’adresses IP de Braze correspondant à votre instance. Il n’est pas nécessaire de définir des ACL de lecture publique sur chaque objet.
{
  "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}"]
        }
      }
    }
  ]
}

Remplacez {YOUR_BRAZE_IP_RANGE} par les plages d’adresses IP de Braze correspondant à votre instance, indiquées dans la section Liste d’adresses IP autorisées pour le Contenu connecté. Vous pouvez ajouter une ou plusieurs plages sous forme de valeurs distinctes dans le tableau aws:SourceIp.

  1. Vérifiez les paramètres S3 Block Public Access : AWS considère les politiques de compartiment qui utilisent Principal: "*" comme un accès public, même avec des conditions d’IP. Vous devrez peut-être autoriser l’accès public basé sur les politiques de compartiment tout en continuant à bloquer l’accès public basé sur les ACL.

  2. Utilisez l’URL de l’objet S3 dans votre étiquette de Contenu connecté : Référencez l’objet avec son URL S3 standard (par exemple, https://your-bucket.s3.amazonaws.com/path/to/object.json).

Pour en savoir plus sur les politiques de compartiment et les clés de condition, consultez la documentation AWS.

En-têtes des requêtes sortantes

Braze ajoute les en-têtes suivants aux requêtes de contenu connecté sortantes. La plupart ne sont définis que si vous ne les avez pas déjà fournis dans l’étiquette. Les en-têtes que vous fournissez avec :headers, des identifiants ou des options d’étiquette sont envoyés tels quels.

En-tête Quand Braze le définit
User-Agent Si vous ne l’avez pas déjà défini, Braze envoie Braze Sender <version>. La chaîne de version peut changer. Si vous filtrez le trafic par User-Agent, autorisez toutes les valeurs commençant par Braze Sender. Pour envoyer une valeur constante, définissez User-Agent dans :headers.
X-Braze-Sender-Version Toujours défini sur la version de l’expéditeur de contenu connecté.
Accept-Encoding Si vous ne l’avez pas déjà défini, Braze envoie gzip.
Authorization Si l’URL contient un nom d’utilisateur et un mot de passe (user:pass@host), Braze ajoute un en-tête Basic Authorization dérivé de ces identifiants. Un en-tête Authorization explicite le remplace. Préférez :basic_auth ou :headers plutôt que de placer les identifiants dans l’URL.
Host Nom d’hôte extrait de l’URL de la requête (par exemple, www.example.com pour https://www.example.com/abc/123), sauf si vous définissez un en-tête Host.
Content-Length Taille du corps de la requête en octets lorsqu’un corps est présent.
BrazeToBraze Défini sur true uniquement pour les requêtes vers les endpoints REST de Braze. Omis pour les autres destinations.

Les requêtes de webhook envoient également un en-tête User-Agent qui commence par Braze Sender lorsque vous n’avez pas défini cet en-tête.

Résolution des problèmes

Si votre appel de contenu connecté ne s’affiche pas correctement, ou pas du tout, vérifiez les points suivants :

  • Inspectez la requête et la réponse en direct : Utilisez le débogueur de contenu connecté dans Aperçu et test.
  • Confirmez qu’un appel de contenu connecté a bien été effectué : Vous pouvez le vérifier dans l’onglet Historique des messages. Vous pouvez également effectuer un envoi test d’une seule requête de contenu connecté.
  • Vérifiez avec Postman ou une requête CURL si la requête idéale aboutit : Si la requête fonctionne et renvoie une réponse, comparez la requête en détail (y compris les en-têtes). Confirmez que les en-têtes sont saisis sous forme de paires clé-valeur entre guillemets doubles.
  • Validez l’authentification : Confirmez que l’identifiant est enregistré sous Paramètres > Gestion des identifiants et référencé avec l’option :basic_auth ou :auth_credentials. Il arrive que l’URL du contenu connecté nécessite d’autres en-têtes en plus de l’authentification.
  • Vérifiez que les données sont au format attendu : Pour le corps de la réponse, Braze analyse le JSON valide en tant qu’objet Liquid ; sinon, la réponse est traitée comme du texte brut (y compris le HTML). L’option :content_type définit les en-têtes sortants Content-Type et Accept de votre requête et n’a aucune incidence sur l’analyse de la réponse. Pour le :body de la requête, si votre JSON contient des espaces, suivez les indications de la section Fournir un corps JSON.
  • Confirmez que les données ont été correctement analysées : Vérifiez que le Liquid référence bien le champ attendu. Pour un JSON imbriqué, utilisez {{sampleresult.data[0].sample_field}} afin de cibler le champ imbriqué souhaité. Vous pouvez contrôler les propriétés du JSON imbriqué en affichant le résultat attendu avec RESPONSE:{{sampleresult.data}}.
  • Vérifiez le code de statut de la réponse : Le code de statut de la réponse doit être un code 2XX. Le contenu connecté ne peut pas exploiter la réponse lorsque le code n’est pas 2XX.

Générez un aperçu dans Aperçu et test, puis sélectionnez Voir les détails pour ouvrir le débogueur de contenu connecté. Le débogueur répertorie les en-têtes de votre étiquette de contenu connecté. Pour les en-têtes que Braze ajoute à la requête sortante, consultez la section En-têtes de requête sortante.

Vous pouvez également vérifier que l’étiquette Liquid inclut les paramètres attendus par votre endpoint (par exemple, :method, :headers, :content_type, :body et :basic_auth si nécessaire). Si vous vous appuyez sur la clé du code de statut HTTP dans un objet JSON enregistré, l’endpoint doit renvoyer un objet JSON et un statut 2XX.

En cas de taux d’erreur élevé de la part de votre hôte, consultez les sections Détection d’hôte défaillant et Volume d’appels de contenu connecté.

Encodage des esperluettes dans les requêtes POST des e-mails

Dans les e-mails, l’analyse HTML convertit automatiquement les esperluettes (&) situées dans les blocs {% capture %} en &amp;. Pour les requêtes POST application/x-www-form-urlencoded, la requête envoie alors des noms de paramètres précédés du préfixe amp; (par exemple, amp;username), ce qui peut faire échouer l’appel d’API.

Pour contourner ce problème, utilisez le filtre replace afin de supprimer le préfixe amp; avant de transmettre le corps à :body :

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

Questions fréquentes

Pourquoi le contenu connecté échoue-t-il lorsque mon endpoint renvoie une redirection (301 ou 302) ?

Une redirection peut entraîner un rendu vide du contenu connecté lors de l’aperçu ou de l’envoi, ou générer une erreur dans le journal d’activité des messages avec le code de statut HTTP 301 ou 302. Postman et d’autres clients suivent souvent les redirections automatiquement : une URL peut donc fonctionner dans Postman, mais échouer dans Braze.

Configurez votre endpoint pour qu’il renvoie une réponse 2xx (généralement 200) avec le corps de la réponse à l’URL appelée par Braze. Si cette URL renvoie elle-même une redirection, remplacez-la par l’URL de destination finale.

Pour d’autres vérifications lorsque le contenu s’affiche vide, consultez Le contenu connecté ne renvoie aucun corps de réponse.

Pourquoi y a-t-il plus d’appels de contenu connecté que d’utilisateurs ou d’envois ?

Braze peut effectuer le même appel API de contenu connecté plusieurs fois par destinataire pour générer le payload d’un message. Les payloads de message peuvent être générés plusieurs fois par destinataire à des fins de validation, de logique de nouvelle tentative ou pour d’autres besoins internes. Notez toutefois qu’un seul des appels de contenu connecté alimente le message.

Il est normal qu’un appel API de contenu connecté soit effectué plus d’une fois par destinataire, même si la logique de nouvelle tentative n’est pas utilisée dans l’appel. Nous vous recommandons de définir une limite de débit pour tous les messages contenant du contenu connecté, ou de configurer vos serveurs pour qu’ils puissent mieux absorber le volume attendu, en tenant compte des multiples appels de contenu connecté effectués par envoi de message.

Consultez Comprendre le volume d’appels de contenu connecté et Bonnes pratiques pour les endpoints à volume élevé pour plus de détails et des solutions d’atténuation.

Comment fonctionne la limitation du débit avec le contenu connecté ?

Le contenu connecté ne dispose pas de sa propre limite de débit. La limite de débit repose plutôt sur le rythme d’envoi des messages. Si le nombre d’appels de contenu connecté dépasse celui des messages envoyés, nous vous recommandons de définir une limite de débit d’envoi de messages supérieure à la limite de débit souhaitée pour le contenu connecté.

Quel est le comportement de mise en cache ?

Les requêtes GET sont mises en cache par défaut (voir Mise en cache des réponses). Les requêtes POST ne sont pas mises en cache par défaut, mais vous pouvez activer la mise en cache en ajoutant :cache_max_age à l’appel de contenu connecté. Cela peut réduire la charge sur l’endpoint lorsque la même requête POST (par exemple, une demande de jeton ou de contenu) serait effectuée à plusieurs reprises pendant la période de mise en cache.

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

La mise en cache peut contribuer à réduire les appels de contenu connecté en double, mais ne garantit pas un seul appel par utilisateur. La durée de mise en cache est comprise entre cinq minutes et quatre heures. Pour plus de détails, consultez Mise en cache des réponses.

Quel est le comportement HTTP par défaut du contenu connecté ?

Par défaut, le contenu connecté définit un en-tête Content-Type sur la requête HTTP GET qu’il effectue à application/json avec Accept: */*. Si vous avez besoin d’un autre type de contenu, spécifiez-le explicitement en ajoutant :content_type your/content-type à l’étiquette. Braze définira alors l’en-tête Content-Type et l’en-tête Accept selon le type que vous spécifiez.

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

Par défaut, le contenu connecté effectue une requête HTTP GET vers l’URL spécifiée. Pour effectuer une requête POST à la place, spécifiez :method post.

Vous pouvez également fournir un payload POST en spécifiant :body suivi d’une chaîne de caractères de requête au format key1=value1&key2=value2&... ou d’une référence à des valeurs capturées. Le Content-Type par défaut est application/x-www-form-urlencoded. Si vous spécifiez :content_type application/json et fournissez un corps encodé en URL tel que key1=value1&key2=value2, Braze encodera automatiquement le corps en JSON avant l’envoi.

Par défaut, le contenu connecté ne met pas non plus en cache les appels POST. Vous pouvez modifier ce comportement en ajoutant :cache_max_age à l’appel POST du contenu connecté.

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

Que se passe-t-il si j’utilise le même appel de contenu connecté à plusieurs endroits ?

Chaque étiquette de contenu connecté est évaluée séparément, même si plusieurs étiquettes utilisent la même URL et les mêmes paramètres. Lorsque l’URL et les paramètres de cache le permettent, des requêtes identiques peuvent être servies depuis le cache au lieu de déclencher une nouvelle requête sortante (consultez Mise en cache des réponses pour plus de détails).

New Stuff!