Effectuer un appel API

Utilisez le contenu connecté pour insérer toute information accessible via API directement dans les messages que vous envoyez aux utilisateurs. Vous pouvez extraire du contenu directement à partir de votre serveur Web ou des API accessibles au public.

Balise Contenu connecté

Pour envoyer un appel de contenu connecté, utilisez la balise {% connected_content %}. Cette balise vous permet d’attribuer et de déclarer des variables en utilisant :save. Certains aspects de ces variables peuvent être référencés plus loin dans le message avec Liquid.

Par exemple, le corps de message suivant va accéder à l’URL http://numbersapi.com/random/trivia et inclure une histoire amusante dans votre message :

1
2
{% connected_content http://numbersapi.com/random/trivia :save result %}
Hi there, here is fun some trivia for you!: {{result.text}}

Ajouter des variables

Vous pouvez également inclure des attributs de profil utilisateur comme variables dans la chaîne de caractères d’URL lors de la création de requêtes de contenu connecté.

Par exemple, vous pouvez disposer d’un service Web qui renvoie le 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, tels que le signe (@), assurez-vous d’utiliser le filtre Liquid url_param_escape pour remplacer les caractères non autorisés dans les URL avec leurs versions d’échappement compatibles avec les URL, comme indiqué dans l’attribut d’e-mail suivant.

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

Les requêtes de contenu connecté prennent uniquement en charge les requêtes GET et POST.

Gestion des erreurs

Si l’URL n’est pas disponible et qu’elle atteint une page 404, Braze renvoie une chaîne de caractères vide à sa place. Si l’URL atteint une page HTTP 500 ou 502, l’URL échoue à la nouvelle tentative de logique.

Si l’endpoint renvoie du JSON, vous pouvez le détecter en vérifiant si la valeur de connected est nulle, puis abandonnez le message sous condition. Braze autorise uniquement les URL qui communiquent sur le port 80 (HTTP) et 443 (HTTPS).

Performance

Étant donné que Braze délivre des messages à un débit très rapide, assurez-vous que votre serveur peut gérer des milliers de connexions simultanées afin que les serveurs ne soient pas surchargés lors de la récupération de contenus. Lorsque vous utilisez des API publiques, assurez-vous que votre utilisation n’enfreint aucune limite de débit que le fournisseur API peut employer. Braze exige que le temps de réponse du serveur soit inférieur à 2 secondes pour des raisons de performance ; si le serveur prend plus de 2 secondes pour répondre, le contenu ne sera pas inséré.

Les systèmes Braze peuvent effectuer le même appel API de contenu connecté plusieurs fois par destinataire. En effet, Braze peut avoir besoin d’un appel API de contenu connecté pour renvoyer une charge utile de message, et les charges utiles de message peuvent être renvoyées plusieurs fois par destinataire pour validation, logique de nouvelle tentative ou autres objectifs internes. Vos systèmes doivent être en mesure de tolérer le même appel de contenu connecté plus qu’une fois par destinataire.

Choses à savoir

• Braze ne facture pas les appels à l’API et ceux-ci ne sont pas pris en compte dans le calcul des points de données qui vous sont alloués.
• Les réponses au contenu connecté sont limitées à 1 Mo.
• Les appels de contenu connectés se produisent lorsque le message est envoyé, à l’exception des messages dans l’application, qui effectueront cet appel lorsque le message est affiché.
• Les appels de contenu connectés ne suivent pas les redirections.

Types d’authentifications

Utilisation de l’authentification de base

Si l’URL nécessite une authentification de base, Braze peut générer des informations d’authentification de base pour que vous puissiez l’utiliser dans votre appel API. Vous pouvez gérer les identifiants d’authentification de base existants et en ajouter de nouveaux à partir de Paramètres > Contenu connecté.

Pour ajouter un nouvel identifiant, cliquez sur Ajouter un identifiant. Nommez vos identifiants et saisissez le nom d’utilisateur et le mot de passe.

Vous pouvez alors utiliser ces informations d’identification de base pour l’authentification dans vos appels API en faisant référence au nom du jeton :

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

Utilisation de l’authentification par jeton

Lorsque vous utilisez le contenu connecté de Braze, vous pouvez constater que certaines API nécessitent un jeton au lieu d’un nom d’utilisateur et d’un mot de passe. L’appel suivant est un extrait de code qui vous permet de référencer et de modéliser vos messages.

1
2
3
4
5
6
7
8
9
10
11
12
{% assign campaign_name="New Year Sale" %}
{% connected_content
     https://your_API_link_here/
     :method post
     :headers {
       "X-App-Id": "YOUR-APP-ID",
       "X-App-Token": "YOUR-APP-TOKEN"
  }
     :body campaign={{campaign_name}}&customer={{${user_id}}}&channel=Braze
     :content_type application/json
     :save publication
%}

Utilisation de l’authentification ouverte (OAuth)

Certaines configurations API nécessitent la récupération d’un jeton d’accès qui peut ensuite être utilisé pour authentifier l’endpoint API auquel vous souhaitez accéder.

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 à une variable locale qui peut ensuite être utilisée pour authentifier l’appel API suivant. Un paramètre :cache_max_age peut être ajouté pour correspondre à l’heure à laquelle le jeton d’accès est valide et réduire le nombre d’appels de contenu connecté sortant. Pour plus d’informations, voir Mise en cache configurable.

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

Autoriser l’API à l’aide du jeton d’accès récupéré

Maintenant que le jeton est enregistré, il peut être placé dynamiquement dans l’appel de Contenu connecté suivant pour autoriser la demande :

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

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

Lorsqu’un message utilisant le Contenu connecté est envoyé par Braze, les serveurs Braze font automatiquement des requêtes réseau aux serveurs de nos clients ou tiers pour extraire des données. Grâce à la liste d’adresses IP autorisées, vous pouvez vérifier que les demandes de contenu connecté proviennent bien de Braze, ce qui ajoute une couche de sécurité supplémentaire.

Braze envoie des demandes de Contenu connecté à partir des plages IP suivantes. Les plages répertoriées sont automatiquement et dynamiquement ajoutées à toutes les clés API qui ont fait l’objet d’un abonnement à allowlisting.

Braze dispose d’un ensemble d’IP réservé pour tous les services, qui ne sont pas tous actifs à un moment donné. Ce système est personnalisé pour permettre à Braze d’envoyer des données à partir d’un autre centre de données ou d’effectuer des travaux de maintenance, si nécessaire, sans que les clients ne soient affectés. Braze peut utiliser un IP, un sous-ensemble d’IP ou tous les IP suivants répertoriés lors de la création de requêtes de contenu connecté.

Résolution des problèmes

Utilisez Webhook.site pour résoudre les problèmes liés à vos appels au contenu connecté.

1. Changez l’URL de votre appel de contenu connecté avec l’URL unique générée sur le site.
2. Prévisualisez et testez votre campagne ou votre étape Canvas pour voir les requêtes arriver sur ce site Internet.

À l’aide de cet outil, vous pouvez diagnostiquer les problèmes avec les en-têtes et le corps des requêtes, ainsi que d’autres informations envoyées lors de l’appel.