Créer une transformation

La Transformation des données 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 faciliter des cas d’utilisation marketing encore plus sophistiqués. Vous pouvez créer votre Transformation des données à partir d’un code par défaut, ou en utilisant notre bibliothèque de modèles dédiée pour vous aider à démarrer avec certaines plateformes externes.

Conditions préalables

Étape 1 : Identifier une plateforme source

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

Voici un exemple de webhook Typeform, configurable en se connectant à leur plateforme :

Étape 2 : Créer une transformation

Dans le tableau de bord de Braze, sélectionnez Paramètres des données > Transformation des données.

Sélectionnez Créer une transformation pour nommer votre transformation, puis choisissez votre expérience de modification.

Sélectionnez Utiliser un modèle pour parcourir une bibliothèque de modèles, y compris les cas d’utilisation de la transformation des données. Vous pouvez également choisir de partir de zéro 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.

Remarque

Vous souhaitez demander des modèles ou des destinations supplémentaires ? Pensez à donner votre avis sur le produit.

Après avoir créé votre transformation, vous verrez la vue détaillée de la transformation. Ici, vous pouvez voir le webhook le plus récent reçu pour cette transformation sous Détails du webhook et un espace pour écrire votre code de transformation sous Code de transformation.

Capturez l’URL de votre webhook pour l’utiliser à l’étape suivante.

Étape 3 : Envoyer un webhook de test (recommandé)

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

1. Copiez l’URL de votre transformation.
2. Dans votre plateforme source, trouvez une fonctionnalité « Envoyer un test » pour générer un exemple de webhook à envoyer à 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 No authentication.
   • Si votre plateforme source demande des secrets, sélectionnez No secrets.
3. Actualisez votre page dans le tableau de bord de Braze pour voir si le webhook a été reçu. S’il a été reçu, vous devriez voir un payload de webhook sous Most recent webhook.

Voici à quoi cela ressemble pour Typeform :

Remarque

Il se peut que la Transformation des données Braze ne prenne pas encore en charge les plateformes externes qui exigent une vérification ou une authentification spéciale pour les webhooks. N’hésitez pas à laisser un commentaire sur le produit si vous souhaitez utiliser ce type de plateforme avec la Transformation des données 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 éléments du catalogue pour écrire votre code de transformation.

Si vous êtes développeur ou si vous avez une expérience significative avec le 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.

Conseil

La Transformation des données Braze dispose d’un copilote d’intelligence artificielle qui utilise ChatGPT pour vous aider à écrire votre code. Pour accéder au copilote d’intelligence artificielle, sélectionnez Generate transformation code. Pour l’utiliser, un webhook doit être envoyé à votre transformation. Vous pouvez également accéder à la bibliothèque de modèles en sélectionnant Insert code > Insert template.

• débutant - suivre les utilisateurs
• débutant - mettre à jour les éléments du catalogue
• avancé - suivre les utilisateurs

Ici, écrivez le code de transformation pour définir comment mapper diverses valeurs de webhook à des profils utilisateurs Braze.

1. Les nouvelles transformations ont ce modèle par défaut dans la section Transformation Code :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// 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;

2. Pour inclure des attributs personnalisés, des événements personnalisés et des achats dans vos appels de transformation, passez à l’étape 3. Sinon, supprimez les sections dont vous n’avez pas besoin.
   
   
3. Chaque objet d’attribut, d’événement et d’achat nécessite un identifiant utilisateur, soit external_id, user_alias, braze_id, email ou phone. Trouvez l’identifiant utilisateur dans le payload du webhook entrant et intégrez cette valeur dans votre code de transformation via une ligne de payload. Utilisez la notation point pour accéder aux propriétés de l’objet du payload.
   
   
4. Trouvez les valeurs du webhook que vous souhaitez représenter en tant qu’attributs, événements ou achats, et intégrez ces valeurs dans votre code de transformation via une ligne de payload. Utilisez la notation point pour accéder aux propriétés de l’objet du payload.
   
   
5. Pour chaque objet d’attribut, d’événement et d’achat, examinez la valeur _update_existing_only. Définissez cette valeur sur false si vous souhaitez que la transformation crée un nouvel utilisateur qui n’existe peut-être pas. Laissez cette option sur true pour ne mettre à jour que les profils existants.
   
   
6. Cliquez sur Validate pour obtenir un aperçu de la sortie de votre code et vérifier s’il s’agit d’une requête /users/track acceptable.
   
   
7. Activez votre transformation. Pour obtenir une aide supplémentaire concernant votre code avant de l’activer, contactez votre gestionnaire de compte Braze.
   
   
8. Demandez à votre plateforme source de commencer à envoyer des webhooks. Votre code de transformation s’exécutera pour chaque webhook entrant, et les profils utilisateurs commenceront à être mis à jour.

L’intégration de votre webhook est maintenant terminée !

Ici, vous pouvez écrire un code de transformation pour définir comment mapper différentes valeurs de webhook à des mises à jour d’éléments du catalogue Braze.

1. Les nouvelles transformations incluront ce modèle par défaut dans la section Transformation Code :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
// This is a default template that you can use as a starting point
// Feel free to delete this entirely to start from scratch, or to 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: https://www.braze.com/docs/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;

2. Les transformations pour les destinations /catalogs nécessitent un catalog_name pour définir le catalogue spécifique à mettre à jour. Vous pouvez coder ce champ en dur ou le modéliser avec un champ webhook via une ligne de payload. Utilisez la notation point pour accéder aux propriétés de l’objet du payload.
   
   
3. Définissez les éléments que vous souhaitez mettre à jour dans le catalogue à l’aide des champs id dans le tableau des éléments. Vous pouvez coder ces champs en dur ou les insérer via un champ webhook dans une ligne de payload.
   
   N’oubliez pas que catalog_column est une valeur de marque substitutive. Assurez-vous que les objets d’éléments ne contiennent que des champs qui existent dans le catalogue.
   
   
4. Sélectionnez Validate pour obtenir un aperçu du résultat de votre code et vérifier s’il s’agit d’une requête acceptable pour l’endpoint Mettre à jour plusieurs éléments du catalogue.
   
   
5. Activez votre transformation. Pour obtenir une aide supplémentaire concernant votre code avant de l’activer, contactez votre gestionnaire de compte Braze.
   
   
6. Veillez à vérifier si votre plateforme source dispose d’un paramètre permettant de lancer l’envoi de webhooks. Votre code de transformation s’exécutera pour chaque webhook entrant, et les éléments du catalogue commenceront à être mis à jour.

L’intégration de votre webhook est maintenant terminée !

Dans cette étape, vous transformerez le payload du webhook de la plateforme source en une valeur de retour d’objet JavaScript. Cette valeur de retour doit respecter le format du corps de la 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.
• Toutes les fonctionnalités prises en charge dans notre endpoint /users/track sont prises en charge, y compris :
  • Objets d’attributs utilisateur, objets d’événements et objets d’achat
  • Attributs imbriqués et propriétés d’événements personnalisés imbriquées
  • Mises à jour des groupes d’abonnement
  • L’adresse e-mail comme identifiant

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

Remarque

Les requêtes réseau externes, les bibliothèques tierces et les webhooks non JSON ne sont actuellement pas pris en charge.

Étape 5 : Surveiller votre transformation

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

• Incoming Requests : 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.
• Deliveries : après avoir reçu les requêtes entrantes, la Transformation des données applique votre code de transformation pour l’envoyer à la destination Braze que vous avez sélectionnée.

L’objectif 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 pour des journaux spécifiques, où sont consignées les 1 000 dernières requêtes entrantes adressées à toutes les transformations de vos espaces de travail. Vous pouvez sélectionner chaque journal 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.

S’il n’y a pas de livraisons, vérifiez que votre code de transformation ne contient pas d’erreurs de syntaxe et confirmez que le code se compile. Vérifiez ensuite si la sortie est une requête de destination valide.

Un nombre de livraisons inférieur au nombre de requêtes entrantes indique qu’au moins certains webhooks sont livrés avec succès. Consultez les journaux de transformation pour trouver des exemples d’erreurs et vérifiez si la sortie de la transformation est conforme aux attentes. Il est possible que votre code de transformation ne prenne pas en compte toutes les variations des webhooks reçus.