Skip to content

Connecteur HTTP personnalisé

Découvrez comment intégrer un connecteur Currents personnalisé afin de recevoir les données d’événements de Braze en temps réel, pour des analyses, des rapports et une automatisation plus personnalisés.

Conditions préalables

Pour intégrer un connecteur Currents personnalisé dans Braze, vous devrez fournir une URL d’endpoint et un jeton d’authentification facultatif.

De plus, si vous avez plusieurs groupes d’applications dans Braze, vous devrez configurer un connecteur Currents personnalisé pour chaque groupe. Cependant, vous pouvez diriger tous les groupes d’applications vers le même endpoint, ou vers un endpoint avec un paramètre GET supplémentaire, tel que your_app_group_key="Brand A".

Intégration

Étape 1 : Configurer votre endpoint

Vous aurez besoin d’une URL d’endpoint pour configurer cette intégration. Votre endpoint doit être capable de recevoir des requêtes HTTP POST et de renvoyer un code de statut 2XX pour confirmer la bonne réception des événements. Si vous souhaitez authentifier les requêtes provenant de Braze, vous aurez également besoin d’un jeton bearer.

Étape 2 : Configurer Braze Currents

Dans Braze, accédez à Partner Integrations > Data Export, cliquez sur Create New Current et sélectionnez Custom Currents Export.

Donnez un nom à votre export ainsi qu’un e-mail de contact, puis passez à la page Current Details. Sur cette page, saisissez l’URL de votre endpoint et le jeton bearer facultatif.

Après avoir configuré vos identifiants, cochez tous les événements d’engagement de messages, de comportement client et d’utilisateur que vous souhaitez exporter, puis cliquez sur Launch Current.

Événements Currents pris en charge

Braze prend en charge l’exportation des données suivantes vers votre connecteur HTTP personnalisé :

Pour la structure du payload de chaque événement, sélectionnez l’onglet Custom HTTP Connector dans le glossaire des événements.

Prévention de la perte de données

Surveillance des erreurs

Pour éviter la perte de données et les interruptions de service, il est essentiel de surveiller vos endpoints en permanence et de traiter rapidement toute erreur ou temps d’arrêt.

Pour la plupart des types d’erreurs (telles que les erreurs serveur et les erreurs de connexion réseau), Braze réessaiera activement la transmission des événements. Si le problème persiste pendant plus de 5 jours, l’intégration sera automatiquement désactivée. Les nouveaux événements entrants seront abandonnés et définitivement perdus.

Résilience aux changements

Il arrive que nous apportions des modifications non disruptives aux schémas de Braze Currents. Les modifications non disruptives sont de nouvelles colonnes nullables ou de nouveaux types d’événements.

Nous donnons généralement un préavis de deux semaines pour ces changements, mais ce n’est pas toujours possible. Il est essentiel que vous conceviez votre intégration pour gérer les champs ou types d’événements non reconnus, sinon cela entraînera probablement une perte de données.

Mise en lots et sérialisation

Le format de données cible est JSON via HTTPS. Par défaut, les événements sont envoyés à votre endpoint par lots de 100 événements maximum.

Les événements sont envoyés à l’endpoint sous forme de tableau JSON contenant tous les événements, dans le format suivant :

1

{"events": [event1, event2, event3, etc...]}

Il y aura un objet JSON de niveau supérieur avec la clé "events" qui correspond à un tableau d’autres objets JSON, chacun représentant un événement unique. Chaque événement contient deux sous-objets :

Si un endpoint en aval reçoit un payload avec zéro événement ou un corps de requête vide, le résultat doit être considéré comme un no-op, ce qui signifie qu’aucun effet en aval ne doit résulter de cet appel. Cependant, vous devez toujours vérifier l’en-tête Authorization (comme vous le feriez pour un appel API normal) et renvoyer une réponse HTTP appropriée pour les identifiants invalides, telle que 401 ou 403. Cela permet à Braze de savoir que les identifiants du connecteur sont valides.

Authentification

Les jetons d’authentification dans votre payload sont facultatifs. Ils peuvent être transmis via un en-tête HTTP Authorization en utilisant le schéma d’autorisation Bearer, tel que spécifié dans la RFC 6750. Bien que facultatif, si un jeton d’authentification est transmis, Braze le validera toujours en premier—même si aucun événement ne figure dans le payload.

Conformément à la RFC 6750, les jetons doivent être des valeurs encodées en Base64 comportant au moins un caractère. Gardez à l’esprit que la RFC 6750 autorise les jetons à contenir les caractères suivants en plus des caractères Base64 normaux : -, ., _ et ~. Vous pouvez choisir d’inclure ou non ces caractères dans votre jeton—cependant, il doit être au format Base64.

De plus, si l’en-tête Authorization est présent, il sera construit selon le format suivant :

1

"Authorization: Bearer " + <token>

Par exemple, si votre jeton d’authentification est 0p3n5354m3==, votre en-tête Authorization devrait ressembler à ceci :

1

Authorization: Bearer 0p3n5354m3==

Versionnage

Toutes les requêtes provenant de notre intégration de connecteur HTTP seront envoyées avec un en-tête personnalisé indiquant la version de la requête Currents effectuée :

1

Braze-Currents-Version: 1

La version sera toujours 1, car nous ne prévoyons pas d’incrémenter ce numéro très souvent, voire jamais.

Tout comme nos schémas de stockage d’entrepôt de données, chaque champ d’événement dans un événement individuel est garanti rétrocompatible avec les versions précédentes du payload d’événement, selon la définition de rétrocompatibilité d’Apache Avro :

  1. Les champs d’événement spécifiques sont garantis de toujours avoir le même type de données au fil du temps.
  2. Tout nouveau champ ajouté au payload au fil du temps doit être considéré comme facultatif par toutes les parties.
  3. Les champs requis ne seront jamais supprimés.

Gestion des erreurs et mécanisme de réessai

Si une erreur survient, Braze mettra en file d’attente et réessaiera la requête en fonction du code de retour HTTP reçu. Si le problème persiste pendant plus de 5 jours, l’intégration sera automatiquement désactivée : les nouveaux événements entrants seront abandonnés et définitivement perdus, et les événements déjà en file d’attente seront définitivement supprimés après une rétention de 7 jours. Si des données sont bloquées pendant plus de 24 heures, nos ingénieurs d’astreinte seront automatiquement alertés. Pour un détail complet de la gestion de chaque code de statut, consultez le tableau ci-dessous.

Si votre intégration Currents renvoie des erreurs d’authentification, Braze vous enverra automatiquement un e-mail de notification.

Tout code d’erreur HTTP non répertorié ci-dessous sera traité comme une erreur HTTP 5XX.

Les codes de statut HTTP suivants seront reconnus par notre client connecteur :
New Stuff!