Crear una transformación

Transformación de datos de Braze te permite crear y gestionar integraciones de webhook para automatizar el flujo de datos desde plataformas externas a Braze. Estas integraciones de webhook pueden impulsar casos de uso de marketing aún más sofisticados. Puedes crear tu Transformación de datos a partir del código predeterminado o utilizando nuestra biblioteca de plantillas dedicada para ayudarte a empezar con determinadas plataformas externas.

Requisitos previos

Paso 1: Identifica una plataforma de origen

Identifica una plataforma externa que quieras conectar a Braze y comprueba que la plataforma admite webhooks. Estas configuraciones a veces se denominan “notificaciones de API” o “solicitudes de servicio web”.

A continuación se muestra un ejemplo de webhook de Typeform, que se puede configurar iniciando sesión en su plataforma:

Paso 2: Crear una transformación

En el panel de Braze, ve a Configuración de datos > Transformación de datos.

Selecciona Crear transformación para darle un nombre a tu transformación y, a continuación, elige tu experiencia de edición.

Selecciona Utilizar una plantilla para examinar una biblioteca de plantillas, incluidos los ejemplos de transformación de datos. O bien, selecciona Empezar de cero para cargar una plantilla de código predeterminada.

Si empiezas de cero, elige un destino para tu transformación. Todavía puedes insertar una plantilla de código de la biblioteca de plantillas.

Nota

¿Quieres additional templates or destinations? Considera dejar comentarios sobre el producto.

Después de crear tu transformación, verás la vista detallada de la transformación. Aquí puedes ver el webhook más reciente recibido para esta transformación en Webhook details y un espacio para escribir tu código de transformación en Transformation code.

Copia tu URL del webhook para utilizarla en el siguiente paso.

Paso 3: Envía un webhook de prueba (recomendado)

Este paso es opcional, pero te recomendamos que envíes un webhook de prueba desde tu plataforma de origen a la transformación que acabas de crear.

1. Copia la URL de tu transformación.
2. En tu plataforma de origen, busca una función de “Enviar prueba” para que genere un webhook de muestra y lo envíe a esta URL.
   • Si tu plataforma de origen te pide un tipo de solicitud, selecciona POST.
   • Si tu plataforma de origen ofrece opciones de autenticación, selecciona Sin autenticación.
   • Si tu plataforma de origen te pide secretos, selecciona Sin secretos.
3. Actualiza tu página en el panel de Braze para ver si se ha recibido el webhook. Si se recibió, deberías ver una carga útil del webhook en Webhook más reciente.

Así es como se ve para Typeform:

Nota

Es posible que la transformación de datos de Braze aún no admita plataformas externas que requieran una verificación o autenticación especial para los webhooks. ¿Quieres webhook authentication for external platforms? Considera dejar comentarios sobre el producto.

Paso 4: Escribir el código de transformación

Si tienes poca o ninguna experiencia con código JavaScript o prefieres instrucciones más detalladas, sigue la pestaña Beginner - POST: Track users o Beginner - PUT: Update multiple catalog items para escribir tu código de transformación.

Si eres desarrollador o tienes bastante experiencia con código JavaScript, sigue la pestaña Advanced - POST: Track users para ver instrucciones generales sobre cómo escribir tu código de transformación.

Consejo

Para generar código de transformación con IA, elige Código con Operator en el editor de código de transformación. Para usar esta opción, se debe enviar un webhook a tu transformación. Si prefieres empezar desde una plantilla prediseñada, elige Insertar plantilla. Para ver ejemplos de indicaciones, consulta Generar código de transformación de datos.

Código con Operator solo está disponible si Operator está habilitado para tu cuenta. Si no lo ves, ponte en contacto con tu director de cuentas.

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

Aquí, escribe el código de transformación para definir cómo asignar los distintos valores del webhook a los perfiles de usuario de Braze.

1. Las nuevas transformaciones tienen esta plantilla predeterminada en la sección Código de transformación:

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. Para incluir atributos personalizados, eventos personalizados y compras en tus llamadas de transformación, pasa directamente al paso 3. De lo contrario, elimina las secciones que no necesites.
   
   
3. Cada objeto de atributo, evento y compra requiere un identificador de usuario: external_id, user_alias, braze_id, email o phone. Busca el identificador de usuario en la carga útil del webhook entrante e inserta ese valor como plantilla en tu código de transformación mediante una línea de carga útil. Usa la notación de puntos para acceder a las propiedades del objeto de carga útil.
   
   
4. Busca los valores del webhook que quieras representar como atributos, eventos o compras, e insértalos como plantilla en tu código de transformación mediante una línea de carga útil. Usa la notación de puntos para acceder a las propiedades del objeto de carga útil.
   
   
5. Para cada objeto de atributo, evento y compra, revisa el valor de _update_existing_only. Establécelo en false si quieres que la transformación cree un usuario nuevo que puede no existir. Déjalo en true para actualizar solo los perfiles existentes.
   
   
6. Haz clic en Validar para obtener una vista previa del resultado de tu código y comprobar si es una solicitud /users/track aceptable.
   
   
7. Activa tu transformación. Si necesitas más ayuda con tu código antes de activarlo, ponte en contacto con tu director de cuentas de Braze.
   
   
8. Haz que tu plataforma de origen empiece a enviar webhooks. Tu código de transformación se ejecutará para cada webhook entrante y los perfiles de usuario empezarán a actualizarse.

¡Tu integración de webhook ya está completa!

Aquí puedes escribir el código de transformación para definir cómo quieres asignar los distintos valores del webhook a las actualizaciones de artículos del catálogo de Braze.

1. Las nuevas transformaciones incluirán esta plantilla predeterminada en la sección Código de transformación:

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/es/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. Las transformaciones para destinos /catalogs requieren un catalog_name para definir el catálogo específico que se va a actualizar. Puedes codificar este campo de forma fija o insertarlo como plantilla con un campo del webhook mediante una línea de carga útil. Usa la notación de puntos para acceder a las propiedades del objeto de carga útil.
   
   
3. Define qué artículos quieres actualizar en el catálogo con los campos id de la matriz de artículos. Puedes codificar estos campos de forma fija o insertarlos como plantilla con un campo del webhook mediante una línea de carga útil.
   
   Ten en cuenta que catalog_column es un valor de marcador de posición. Asegúrate de que los objetos de artículo solo contengan campos que existan en el catálogo.
   
   
4. Selecciona Validar para obtener una vista previa del resultado de tu código y comprobar si es una solicitud aceptable para el endpoint Actualizar varios artículos del catálogo.
   
   
5. Activa tu transformación. Si necesitas más ayuda con tu código antes de activarlo, ponte en contacto con tu director de cuentas de Braze.
   
   
6. Comprueba si tu plataforma de origen tiene una configuración para empezar a enviar webhooks. Tu código de transformación se ejecutará para cada webhook entrante y los artículos del catálogo empezarán a actualizarse.

¡Tu integración de webhook ya está completa!

En este paso, transformarás la carga útil del webhook de la plataforma de origen en un valor de retorno de objeto JavaScript. Este valor de retorno debe seguir el formato del cuerpo de la solicitud del endpoint /users/track:

• El código de transformación se acepta en el lenguaje de programación JavaScript. Se admite cualquier flujo de control estándar de JavaScript, como la lógica if/else.
• El código de transformación accede al cuerpo de la solicitud del webhook a través de la variable payload. Esta variable es un objeto que se completa al analizar el JSON del cuerpo de la solicitud.
• Se admite cualquier característica compatible con nuestro endpoint /users/track, incluyendo:
  • Objetos de atributos de usuario, objetos de eventos y objetos de compra
  • Atributos anidados y propiedades de eventos personalizados anidadas
  • Actualizaciones de grupos de suscripción
  • Dirección de correo electrónico como identificador

Selecciona Validar para obtener una vista previa del resultado de tu código y comprobar si es una solicitud /users/track aceptable.

Nota

Actualmente no se admiten las solicitudes de red externas, las bibliotecas de terceros ni los webhooks que no sean JSON.

Paso 5: Monitoriza tu transformación

Después de activar tu transformación, consulta los análisis en la página principal de Transformaciones para ver un resumen del rendimiento.

• Solicitudes entrantes: Es el número de webhooks recibidos en la URL de esta transformación. Si las solicitudes entrantes son 0, tu plataforma de origen no ha enviado ningún webhook o no se puede establecer la conexión.
• Entregas: Después de recibir las solicitudes entrantes, Data Transformation aplica tu código de transformación para enviarlas al destino de Braze que hayas seleccionado.

Un buen objetivo es que el 100 % de las solicitudes entrantes den lugar a entregas. El número de entregas nunca superará el número de solicitudes entrantes.

Solución de problemas

Para una monitorización y una solución de problemas más detalladas, consulta la página Registros, donde se registran las últimas 1000 solicitudes entrantes a todas las transformaciones de tus espacios de trabajo. Puedes seleccionar cada registro para ver el cuerpo de la solicitud entrante, la salida de la transformación y el cuerpo de la respuesta del destino de la transformación.

Si no hay entregas, revisa tu código de transformación en busca de errores de sintaxis y confirma que el código se compila. Después, comprueba si la salida es una solicitud de destino válida.

Si hay menos entregas que solicitudes entrantes, significa que al menos algunos webhooks se entregan correctamente. Consulta los registros de la transformación para ver ejemplos de errores y comprueba si la salida de la transformación es la esperada. Es posible que tu código de transformación no tenga en cuenta todas las variaciones de los webhooks recibidos.