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’usage 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 la 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 :

É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.

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.

Remarque

Vous souhaitez additional templates or destinations ? N’hésitez pas à laisser un retour produit.

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.

É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 la transformation que vous venez de créer.

1. Copiez l’URL de votre transformation.
2. Dans votre plateforme source, recherchez une fonctionnalité du type « 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 Aucune authentification.
   • Si votre plateforme source 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, vous devriez voir un payload de webhook sous Webhook le plus récent.

Voici à quoi cela ressemble pour Typeform :

Remarque

Braze Data Transformation ne prend peut-être pas encore en charge les plateformes externes qui exigent une vérification ou une authentification spécifique pour les webhooks. Vous souhaitez webhook authentication for external platforms ? N’hésitez pas à laisser un retour produit.

É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 Beginner - POST: Track users ou Beginner - PUT: Update multiple catalog items 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 Advanced - POST: Track users. Vous y trouverez des instructions générales pour écrire votre code de transformation.

Conseil

Pour générer du code de transformation avec l’IA, choisissez Coder avec Operator dans l’éditeur de code de transformation. Pour utiliser cette option, un webhook doit avoir été envoyé à votre transformation. Pour partir plutôt d’un modèle prédéfini, choisissez Insérer un modèle. Pour des exemples de prompts, consultez Générer du code de transformation des données.

Coder avec Operator n’est disponible que si Operator est activé pour votre compte. Si cette option n’apparaît pas, contactez votre gestionnaire de compte.

• beginner - track users
• beginner - update catalog items
• advanced - track users

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

1. Les nouvelles transformations contiennent ce modèle par défaut dans la section Code de transformation :

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 directement à 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 : 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.
   
   
4. 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.
   
   
5. Pour chaque objet d’attribut, d’événement et d’achat, vérifiez la valeur _update_existing_only. Définissez-la sur false si vous voulez que la transformation crée un nouvel utilisateur qui n’existe peut-être pas encore. Laissez-la sur true pour mettre à jour uniquement les profils existants.
   
   
6. Cliquez sur Valider pour afficher un aperçu du résultat de votre code et vérifier qu’il s’agit d’une requête /users/track acceptable.
   
   
7. Activez votre transformation. Si vous avez besoin d’aide supplémentaire avec 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 à se mettre à jour.

Votre intégration 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 Braze.

1. Les nouvelles transformations contiennent ce modèle par défaut dans la section Code de transformation :

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 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;

2. Les transformations ayant pour destination /catalogs nécessitent un catalog_name pour définir le catalogue précis à mettre à jour. Vous pouvez coder ce champ en dur ou le remplir 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.
   
   
3. Définissez les articles que vous souhaitez mettre à jour dans le catalogue à l’aide des champs id du tableau des articles. Vous pouvez coder ces champs en dur ou les remplir avec un champ du webhook à l’aide d’une ligne payload.
   
   Gardez à l’esprit que catalog_column est une valeur de marque substitutive. Assurez-vous que les objets d’article ne contiennent que des champs qui existent dans le catalogue.
   
   
4. Sélectionnez Valider pour afficher 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.
   
   
5. Activez votre transformation. Si vous avez besoin d’aide supplémentaire avec votre code avant de l’activer, contactez votre gestionnaire de compte Braze.
   
   
6. 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 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 afficher un aperçu du résultat de votre code et vérifier qu’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 pas pris en charge pour le moment.

Étape 5 : Surveiller votre transformation

Une fois votre transformation activée, consultez l’analyse sur la page principale Transformations pour obtenir un résumé des performances.

• Demandes entrantes : Il s’agit du nombre de webhooks reçus à l’URL de cette transformation. Si les demandes entrantes sont à 0, cela signifie que votre plateforme source n’a envoyé aucun webhook ou que la connexion ne peut pas être établie.
• Livraisons : Après avoir reçu les demandes 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 demandes entrantes aboutissent à des livraisons. Le nombre de livraisons ne dépassera jamais le nombre de demandes entrantes.

Résolution des problèmes

Pour une surveillance et une résolution des problèmes plus détaillées, consultez la page Journaux afin d’accéder à des journaux spécifiques. C’est là que sont enregistrées les 1 000 dernières demandes entrantes adressées à toutes les transformations de vos espaces de travail. Vous pouvez sélectionner chaque journal pour afficher le corps de la demande entrante, la sortie de la transformation et le corps de la réponse provenant de la destination de la transformation.

En l’absence de livraisons, vérifiez que votre code de transformation ne contient pas d’erreurs de syntaxe et qu’il compile correctement. Vérifiez ensuite si la sortie constitue une demande de destination valide.

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