Passer au contenu

Créer une transformation

La Transformation des données de Braze vous permet de créer et de gérer des intégrations webhook pour automatiser le flux de données depuis des plateformes externes vers Braze. Ces intégrations webhook peuvent ensuite alimenter des cas d’usage marketing encore plus sophistiqués. Vous pouvez créer votre Transformation des données à partir d’un code par défaut, ou utiliser notre bibliothèque de modèles dédiée pour bien démarrer avec certaines plateformes externes.

Conditions préalables

Condition Description
Authentification à deux facteurs ou authentification unique L’authentification à deux facteurs (2FA) ou l’authentification unique (SSO) doit être activée pour votre compte.
Autorisations appropriées Vous devez être administrateur du compte ou administrateur de l’espace de travail, ou disposer de l’autorisation utilisateur « Manage Transformations ».

Étape 1 : Identifier une plateforme source

Identifiez une plateforme externe que vous souhaitez connecter à Braze et vérifiez qu’elle prend en charge les webhooks. Ces paramètres sont parfois appelés « notifications API » ou « requêtes de service web ».

Voici un exemple de webhook Typeform, que vous pouvez configurer en vous connectant à leur plateforme :

Exemple de payload de webhook Typeform dans les paramètres de la plateforme Typeform.

Étape 2 : Créer une transformation

Dans le tableau de bord de Braze, accédez à Data Settings > Data Transformation.

Sélectionnez Create Transformation pour nommer votre transformation, puis choisissez votre expérience de modification.

Détails de la transformation avec la possibilité de choisir « Use a template » ou « Start from scratch » pour votre expérience de modification.

Sélectionnez Use a template pour parcourir une bibliothèque de modèles, y compris les cas d’usage de Data Transformation. Vous pouvez également sélectionner Start from scratch pour charger un modèle de code par défaut.

Si vous démarrez de zéro, choisissez une destination pour votre transformation. Vous pouvez toujours insérer un modèle de code à partir de la bibliothèque de modèles.

Plus d’informations sur les destinations
  • POST : Track users : Transforme les webhooks d’une plateforme source en mises à jour du profil utilisateur, telles que les attributs, les événements ou les achats.
  • PUT : Update multiple catalog items : Transforme les webhooks d’une plateforme source en mises à jour d’éléments du catalogue.
  • DELETE : Delete multiple catalog items : Transforme les webhooks d’une plateforme source en suppressions d’éléments du catalogue.
  • PATCH : Edit multiple catalog items : Transforme les webhooks d’une plateforme source en modifications d’éléments du catalogue.
  • POST : Send messages immediately via API Only : Transforme les webhooks d’une plateforme source pour envoyer des messages immédiats à des utilisateurs désignés.

Après avoir créé votre transformation, vous verrez la vue détaillée de celle-ci. Vous pouvez consulter le dernier webhook reçu pour cette transformation sous Webhook details, ainsi qu’un espace pour écrire votre code de transformation sous Transformation code.

Copiez votre Webhook URL pour l’utiliser à l’étape suivante.

Cette étape est facultative, mais nous vous recommandons d’envoyer un webhook de test depuis votre plateforme source vers votre nouvelle transformation.

  1. Copiez l’URL de votre transformation.
  2. Dans votre plateforme source, recherchez une fonctionnalité « Envoyer un test » pour générer un exemple de webhook à envoyer vers cette URL.
    • Si votre plateforme source vous demande un type de requête, sélectionnez POST.
    • Si votre plateforme source propose des options d’authentification, sélectionnez Aucune authentification.
    • Si votre plateforme source vous demande des secrets, sélectionnez Aucun secret.
  3. Actualisez votre page dans le tableau de bord de Braze pour vérifier si le webhook a bien été reçu. Si c’est le cas, un payload de webhook devrait apparaître sous Webhook le plus récent.

Voici ce que cela donne pour Typeform :

Exemple de code Data Transformation qui associe le webhook aux profils utilisateurs Braze.

Étape 4 : Écrire le code de transformation

Si vous avez peu ou pas d’expérience avec le code JavaScript, ou si vous préférez des instructions plus détaillées, suivez l’onglet Débutant - POST : Suivre les utilisateurs ou Débutant - PUT : Mettre à jour plusieurs articles de catalogue pour écrire votre code de transformation.

Si vous êtes développeur ou si vous avez une solide expérience du code JavaScript, suivez l’onglet Avancé - POST : Suivre les utilisateurs pour obtenir des instructions générales sur l’écriture de votre code de transformation.

Ici, écrivez le code de transformation qui définit comment associer les différentes valeurs du webhook aux profils utilisateurs de Braze.

  1. Les nouvelles transformations contiennent ce modèle par défaut dans la section Code de transformation :
// Here, we will define a variable, "brazecall", to build up a `/users/track` request
// Everything from the incoming webhook is accessible via the special variable "payload"
// So you can template in desired values in your `/users/track` request with dot notation, such as payload.x.y.z

let brazecall = {
  "attributes": [
    {
      "external_id": payload.user_id,
      "_update_existing_only": true,
      "attribute_1": payload.attribute_1
    }
  ],
  "events": [
    {
      "external_id": payload.user_id,
      "_update_existing_only": true,
      "name": payload.event_1,
      "time": new Date(),
      "properties": {
        "property_1": payload.event_1.property_1
      }
    }
  ],
  "purchases": [
    {
      "external_id": payload.user_id,
      "_update_existing_only": true,
      "product_id": payload.product_id,
      "currency": payload.currency,
      "price": payload.price,
      "quantity": payload.quantity,
      "time": payload.timestamp,
      "properties": {
        "property_1": payload.purchase_1.property_1
      }
    }
  ]
};

// After the /users/track request is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;
  1. Pour inclure des attributs personnalisés, des événements personnalisés et des achats dans vos appels de transformation, passez directement à l’étape 3. Sinon, supprimez les sections dont vous n’avez pas besoin.

  2. Chaque objet d’attribut, d’événement et d’achat nécessite un identifiant utilisateur : external_id, user_alias, braze_id, email ou phone. Repérez l’identifiant utilisateur dans le payload du webhook entrant, puis insérez cette valeur dans votre code de transformation à l’aide d’une ligne payload. Utilisez la notation par points pour accéder aux propriétés de l’objet payload.

  3. Repérez les valeurs du webhook que vous souhaitez représenter sous forme d’attributs, d’événements ou d’achats, puis insérez ces valeurs dans votre code de transformation à l’aide d’une ligne payload. Utilisez la notation par points pour accéder aux propriétés de l’objet payload.

  4. Pour chaque objet d’attribut, d’événement et d’achat, examinez la valeur _update_existing_only. Le modèle par défaut la définit sur true, ce qui signifie que seuls les profils utilisateurs existants seront mis à jour. Pour créer de nouveaux utilisateurs lorsqu’ils n’existent pas, définissez cette valeur sur false. Si vous omettez complètement ce champ dans un objet, le comportement est identique à false (de nouveaux utilisateurs seront créés).

  5. Cliquez sur Valider pour obtenir un aperçu du résultat de votre code et vérifier qu’il s’agit d’une requête /users/track acceptable.

  6. Activez votre transformation. Si vous avez besoin d’aide supplémentaire avec votre code avant de l’activer, contactez votre gestionnaire de compte Braze.

  7. Faites en sorte que votre plateforme source commence à envoyer des webhooks. Votre code de transformation s’exécutera pour chaque webhook entrant, et les profils utilisateurs commenceront à se mettre à jour.

Votre intégration de webhook est maintenant terminée !

Ici, vous pouvez écrire le code de transformation qui définit comment associer les différentes valeurs du webhook aux mises à jour des articles de catalogue de Braze.

  1. Les nouvelles transformations incluent ce modèle par défaut dans la section Code de transformation :
// This is a default template that you can use as a starting point
// Feel free to delete this entirely and create a new transformation, or edit specific components

// First, this code defines a variable, "brazecall", to build a PUT /catalogs/{catalog_name}/items request
// Everything from the incoming webhook is accessible via the special variable "payload"
// As such, you can template in desired values in your request with JS dot notation, such as payload.x.y.z

let brazecall = {
  // For Braze Data Transformation to update Catalog items, the special variable "catalog_name" is required
  // This variable is used to specify the catalog name which would otherwise go in the request URL
  "catalog_name": "catalog_name",

  // After defining "catalog name", construct the Update Multiple Catalog Items request as usual below
  // Documentation for the destination endpoint: /docs/fr/api/endpoints/catalogs/catalog_items/asynchronous/put_update_catalog_items/
  "items": [
    {
      "id": payload.item_id_1,
      "catalog_column1": "string",
      "catalog_column2": 1,
      "catalog_column3": true,
      "catalog_column4": "2021-09-03T09:03:19.967+00:00",
      "catalog_column5": {
        "Latitude": 33.6112,
        "Longitude": -117.8711
      }
    },
    {
      "id": payload.item_id_2,
      "catalog_column1": "string",
      "catalog_column2": 1,
      "catalog_column3": true,
      "catalog_column4": "2021-09-03T09:03:19.967+00:00",
      "catalog_column5": {
        "Latitude": 33.6112,
        "Longitude": -117.8711
      }
    },
    {
      "id": payload.item_id_3,
      "catalog_column1": "string",
      "catalog_column2": 1,
      "catalog_column3": true,
      "catalog_column4": "2021-09-03T09:03:19.967+00:00",
      "catalog_column5": {
        "Latitude": 33.6112,
        "Longitude": -117.8711
      }
    }
  ]
};

// After the request body is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;
  1. Les transformations ayant pour destination /catalogs nécessitent un catalog_name pour définir le catalogue à mettre à jour. Vous pouvez coder ce champ en dur ou l’alimenter avec un champ du webhook à l’aide d’une ligne payload. Utilisez la notation par points pour accéder aux propriétés de l’objet payload.

  2. Définissez les articles du catalogue que vous souhaitez mettre à jour avec les champs id du tableau items. Vous pouvez coder ces champs en dur ou les alimenter avec un champ du webhook à l’aide d’une ligne payload.

    Gardez à l’esprit que catalog_column est une marque substitutive. Assurez-vous que les objets d’article ne contiennent que des champs qui existent dans le catalogue.

  3. Sélectionnez Valider pour obtenir un aperçu du résultat de votre code et vérifier qu’il s’agit d’une requête acceptable pour l’endpoint de mise à jour de plusieurs articles de catalogue.

  4. Activez votre transformation. Si vous avez besoin d’aide supplémentaire avec votre code avant de l’activer, contactez votre gestionnaire de compte Braze.

  5. Vérifiez si votre plateforme source dispose d’un paramètre permettant de commencer à envoyer des webhooks. Votre code de transformation s’exécutera pour chaque webhook entrant, et les articles du catalogue commenceront à se mettre à jour.

Votre intégration de webhook est maintenant terminée !

Dans cette étape, vous allez transformer le payload du webhook provenant de la plateforme source en une valeur de retour sous forme d’objet JavaScript. Cette valeur de retour doit respecter le format du corps de requête de l’endpoint /users/track :

  • Le code de transformation est accepté dans le langage de programmation JavaScript. Tout flux de contrôle JavaScript standard, tel que la logique if/else, est pris en charge.
  • Le code de transformation accède au corps de la requête webhook via la variable payload. Cette variable est un objet rempli en analysant le JSON du corps de la requête.
  • Toute fonctionnalité prise en charge par notre endpoint /users/track est prise en charge, notamment :
    • Les objets d’attributs utilisateur, les objets d’événements et les objets d’achat
    • Les attributs imbriqués et les propriétés d’événement personnalisées imbriquées
    • Les mises à jour de groupes d’abonnement
    • L’adresse e-mail comme identifiant

Sélectionnez Valider pour obtenir un aperçu du résultat de votre code et vérifier qu’il s’agit d’une requête /users/track acceptable.

Étape 5 : Surveiller votre transformation

Après avoir activé votre transformation, consultez les analyses de la page principale Transformations pour obtenir un résumé des performances.

  • Requêtes entrantes : Il s’agit du nombre de webhooks reçus à l’URL de cette transformation. Si le nombre de requêtes entrantes est de 0, votre plateforme source n’a envoyé aucun webhook, ou la connexion ne peut pas être établie.
  • Livraisons : Après avoir reçu des requêtes entrantes, Data Transformation applique votre code de transformation pour les envoyer vers la destination Braze que vous avez sélectionnée.

L’idéal est que 100 % des requêtes entrantes aboutissent à des livraisons. Le nombre de livraisons ne dépassera jamais le nombre de requêtes entrantes.

Résolution des problèmes

Pour une surveillance et une résolution des problèmes plus détaillées, consultez la page Logs, qui contient des logs spécifiques. Elle enregistre les 1 000 dernières requêtes entrantes de toutes les transformations de vos espaces de travail. Vous pouvez sélectionner chaque log pour afficher le corps de la requête entrante, la sortie de la transformation et le corps de la réponse de la destination de la transformation.

En l’absence de livraisons, vérifiez que votre code de transformation ne contient aucune erreur de syntaxe et qu’il se compile correctement. Vérifiez ensuite que la sortie constitue une requête de destination valide.

Un nombre de livraisons inférieur au nombre de requêtes entrantes indique qu’au moins une partie des webhooks est livrée avec succès. Consultez les logs de transformation pour trouver des exemples d’erreurs et vérifiez si la sortie de la transformation correspond à ce que vous attendez. Il est possible que votre code de transformation ne prenne pas en compte toutes les variantes de webhooks reçus.

New Stuff!