Skip to content

Exportación de Currents personalizada

Aprende a integrar un conector de Currents personalizado para obtener datos de eventos de Braze en tiempo real, lo que permite análisis, informes y automatización más personalizados.

Requisitos previos

Para integrar un conector de Currents personalizado en Braze, tendrás que proporcionar una URL de endpoint y un token de autenticación opcional.

Además, si tienes más de un grupo de aplicaciones en Braze, tendrás que configurar un conector de Currents personalizado para cada grupo. Sin embargo, puedes apuntar todos los grupos de aplicaciones al mismo endpoint, o a un endpoint con un parámetro GET adicional, como your_app_group_key="Brand A".

Integración

Paso 1: Configura tu endpoint

Necesitarás una URL de endpoint para configurar esta integración. Tu endpoint debe poder recibir solicitudes HTTP POST y devolver un código de estado 2XX para confirmar la recepción correcta de los eventos. Si deseas autenticar las solicitudes de Braze, también necesitarás un token de portador.

Paso 2: Configura Braze Currents

En Braze, ve a Integraciones de partners > Exportación de datos, haz clic en Crear nueva corriente y selecciona Exportación de Currents personalizada.

Asigna un nombre y un correo electrónico de contacto a tu exportación, y luego continúa a la página Detalles de la corriente. En esta página, introduce la URL de tu endpoint y el token de portador opcional.

Después de configurar tus credenciales, marca todos los eventos de participación en mensajes, comportamiento del cliente y eventos de usuario que desees exportar, y haz clic en Iniciar corriente.

Eventos de Currents compatibles

Braze permite exportar los siguientes datos a tu conector HTTP personalizado:

Para ver la estructura de la carga útil de cada evento, selecciona la pestaña Custom HTTP Connector en el glosario de eventos.

Prevención de la pérdida de datos

Monitoreo de errores

Para evitar la pérdida de datos y la interrupción del servicio, es esencial que monitorees tus endpoints en todo momento y abordes con prontitud cualquier error o tiempo de inactividad.

Para la mayoría de los tipos de error (como errores de servidor y errores de conexión de red), Braze reintentará activamente las transmisiones de eventos. Si el problema persiste durante más de 5 días, la integración se deshabilitará automáticamente. Los nuevos eventos entrantes se descartarán y se perderán de forma permanente.

Resiliencia ante cambios

Ocasionalmente, realizaremos cambios no disruptivos en los esquemas de Braze Currents. Los cambios no disruptivos son nuevas columnas con valores nulos o tipos de eventos.

Normalmente damos un aviso con dos semanas de antelación para estos cambios, pero a veces esto no es posible. Es esencial que diseñes tu integración para manejar campos o tipos de eventos no reconocidos; de lo contrario, es probable que se produzca una pérdida de datos.

Agrupación por lotes y serialización

El formato de datos de destino es JSON sobre HTTPS. De forma predeterminada, los eventos se envían a tu endpoint en lotes de hasta 100 eventos cada uno.

Los eventos se envían al endpoint como un array JSON de todos los eventos en el siguiente formato:

1

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

Habrá un objeto JSON de nivel superior con la clave "events" que se mapea a un array de más objetos JSON, cada uno representando un solo evento. Cada evento contiene dos subobjetos:

Si un endpoint receptor recibe una carga útil con cero eventos o un cuerpo de solicitud vacío, el resultado debe considerarse una operación nula (no-op), lo que significa que no deben producirse efectos secundarios a partir de esta llamada. Sin embargo, deberías verificar el encabezado Authorization (como lo harías en una llamada API normal), y dar una respuesta HTTP adecuada para credenciales no válidas, como 401 o 403. Esto permite que Braze sepa que las credenciales del conector son válidas.

Autenticación

Los tokens de autenticación en tu carga útil son opcionales. Se pueden pasar a través de un encabezado HTTP Authorization utilizando el esquema de autorización Bearer, como se especifica en RFC 6750. Aunque son opcionales, si se pasa un token de autenticación, Braze siempre lo validará primero—incluso si no hay eventos en la carga útil.

Según RFC 6750, los tokens deben ser valores codificados en Base64 con al menos un carácter. Ten en cuenta que RFC 6750 permite que los tokens contengan los siguientes caracteres además de los caracteres normales de Base64: -, ., _ y ~. Puedes elegir si deseas incluir estos caracteres en tu token o no—sin embargo, debe estar en formato Base64.

Además, si el encabezado Authorization está presente, se construirá utilizando el siguiente formato:

1

"Authorization: Bearer " + <token>

Por ejemplo, si tu token de autenticación es 0p3n5354m3==, tu encabezado Authorization debería ser similar al siguiente:

1

Authorization: Bearer 0p3n5354m3==

Control de versiones

Todas las solicitudes de nuestra integración del conector HTTP se enviarán con un encabezado personalizado que designa la versión de la solicitud de Currents que se está realizando:

1

Braze-Currents-Version: 1

La versión siempre será 1, ya que no esperamos incrementar este número con frecuencia, si es que alguna vez lo hacemos.

Al igual que nuestros esquemas de almacenamiento del almacén de datos, se garantiza que cada campo de evento en un evento individual sea retrocompatible con versiones anteriores de la carga útil del evento, según la definición de retrocompatibilidad de Apache Avro:

  1. Se garantiza que los campos de evento específicos siempre tendrán el mismo tipo de datos a lo largo del tiempo.
  2. Cualquier campo nuevo que se agregue a la carga útil con el tiempo debe ser considerado opcional por todas las partes.
  3. Los campos obligatorios nunca se eliminarán.

Manejo de errores y mecanismo de reintento

Si se produce un error, Braze pondrá en cola y reintentará la solicitud en función del código de retorno HTTP recibido. Si el problema persiste durante más de 5 días, la integración se deshabilitará automáticamente: los nuevos eventos entrantes se descartarán y se perderán permanentemente, y los eventos ya en cola se descartarán permanentemente tras conservarse durante 7 días. Si los datos están atascados durante más de 24 horas, nuestros ingenieros de guardia recibirán una alerta automáticamente. Para un desglose completo de cómo se maneja cada código de estado, consulta la tabla en la siguiente sección.

Si tu integración de Currents devuelve errores de autenticación, Braze te enviará automáticamente un correo electrónico de notificación.

Cualquier código de error HTTP no incluido en la siguiente sección se tratará como un error HTTP 5XX.

Los siguientes códigos de estado HTTP serán reconocidos por nuestro cliente conector:
New Stuff!