Resumen de la ingesta de datos en la nube Braze

Braze Cloud Data Ingestion le permite configurar una conexión directa desde su almacén de datos o sistema de almacenamiento de archivos a Braze para sincronizar datos relevantes de usuarios o catálogos. Cuando se sincronizan con Braze, estos datos pueden aprovecharse para casos de uso como la personalización, la activación o la segmentación.

Cómo funciona

Con Braze Cloud Data Ingestion (CDI), puede configurar una integración entre su instancia de almacén de datos y el espacio de trabajo Braze para sincronizar los datos de forma periódica. Esta sincronización se ejecuta según el calendario que establezcas, y cada integración puede tener un calendario diferente. Las sincronizaciones pueden ser tan frecuentes como cada 15 minutos o tan infrecuentes como una vez al mes. Si necesitas que las sincronizaciones se produzcan con una frecuencia superior a 15 minutos, ponte en contacto con tu administrador del éxito del cliente o considera la posibilidad de utilizar llamadas a la API REST para la ingesta de datos en tiempo real.

Cuando se ejecuta una sincronización, Braze se conecta directamente a tu instancia de almacén de datos, recupera todos los datos nuevos de la tabla especificada y actualiza los datos correspondientes en tu panel Braze. Cada vez que se ejecute la sincronización, los datos actualizados se reflejarán en Braze.

Fuentes de datos compatibles

La ingesta de datos en la nube puede sincronizar datos de las siguientes fuentes con Braze:

• Fuentes de almacén de datos
  • Amazon Redshift
  • Databricks
  • Google BigQuery
  • Microsoft Fabric
  • Snowflake
• Fuentes de almacenamiento de archivos
  • Amazon S3

Tipos de datos admitidos

La ingesta de datos en la nube admite los siguientes tipos de datos:

• Atributos de usuario, incluyendo:
  • Atributos personalizados anidados
  • Matrices de objetos
  • Estados de suscripción
• Eventos personalizados
• Eventos de compra
• Artículos del catálogo
• Solicitudes de eliminación de usuarios

Los datos de usuario pueden actualizarse por ID externo, alias de usuario, ID Braze, correo electrónico o número de teléfono. Los usuarios pueden eliminarse por ID externo, alias de usuario o ID Braze.

Qué se sincroniza

Cada vez que se ejecuta una sincronización, Braze busca filas que no se hayan sincronizado previamente. Lo comprobamos utilizando la columna UPDATED_AT de su tabla o vista. Cualquier fila en la que UPDATED_AT sea posterior a la última fila sincronizada se seleccionará y se introducirá en Braze.

En tu almacén de datos, añade los siguientes usuarios y atributos a tu tabla, ajustando la hora UPDATED_AT a la hora en que añadas estos datos:

Durante la siguiente sincronización programada, todas las filas con una marca de tiempo UPDATED_AT posterior a la marca de tiempo más reciente se sincronizarán con los perfiles de usuario Braze. Los campos se actualizarán o añadirán, por lo que no es necesario sincronizar el perfil de usuario completo cada vez. Tras la sincronización, los usuarios reflejarán las nuevas actualizaciones:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "external_id":"customer_1234",
  "email":"[email protected]",
  "attribute_1":"abcdefg",
  "attribute_2":{
        "attribute_a":"example_value_1",
        "attribute_b":"example_value_2"
    },
  "attribute_3":"2019-07-16T19:20:30+1:00",
  "attribute_4":false,
  "attribute_5":"testing"
}

1
2
3
4
5
6
7
8
9
{
  "external_id":"customer_3456",
  "email":"[email protected]",
  "attribute_1":"abcdefg",
  "attribute_2":42,
  "attribute_3":"2019-07-16T19:20:30+1:00",
  "attribute_4":true,
  "attribute_5":"testing"
}

1
2
3
4
5
6
7
8
9
{
  "external_id":"customer_5678",
  "email":"[email protected]",
  "attribute_1":"abcdefg",
  "attribute_2":42,
  "attribute_3":"2017-08-10T09:20:30+1:00",
  "attribute_4":true,
  "attribute_5":"testing_123"
}

Caso de uso: Primera sincronización y actualizaciones posteriores

Este ejemplo muestra el proceso general para sincronizar datos por primera vez y, a continuación, sólo actualizar los datos cambiantes (deltas) en las actualizaciones posteriores. Supongamos que tenemos una tabla EXAMPLE_DATA con algunos datos de usuario. El día 1 tiene los siguientes valores:

Para obtener estos datos en el formato que espera CDI, puede ejecutar la siguiente consulta:

1
2
3
4
5
6
7
8
9
10
11
12
SELECT
    CURRENT_TIMESTAMP AS UPDATED_AT,
    EXTERNAL_ID AS EXTERNAL_ID,
    TO_JSON(
        OBJECT_CONSTRUCT(
            'attribute_1', attribute_1,
            'attribute_2', attribute_2,
            'attribute_3', attribute_3,
            'attribute_4', attribute_4
        )
    ) AS PAYLOAD
FROM EXAMPLE_DATA;

Nada de esto se ha sincronizado antes con Braze, así que añádelo todo a la tabla de origen para CDI:

Se ejecuta una sincronización y Braze registra que has sincronizado todos los datos disponibles hasta “2023-03-16 15:00:00”. A continuación, en la mañana del día 2, se ejecuta un ETL y se actualizan algunos campos de la tabla de usuarios (resaltados):

Ahora tienes que añadir solo los valores modificados en la tabla fuente CDI. Estas filas pueden añadirse en lugar de actualizar las filas antiguas. Esa tabla tiene ahora este aspecto:

CDI sólo sincronizará las nuevas filas, por lo que la próxima sincronización que se ejecute sólo sincronizará las últimas cinco filas.

Caso de uso: Actualizar un campo en una matriz de objetos existente

Este ejemplo muestra cómo actualizar un campo en un array de objetos existente. Supongamos que tenemos una tabla de origen con la siguiente definición:

1
2
3
4
5
6
7
8
Create table BRAZE_CLOUD_INGESTION_DEMO.BRAZE_SCHEMA.pet_list (
    pet_id int IDENTITY(1,1), 
    breed VARCHAR, 
    type VARCHAR, 
    name VARCHAR, 
    owner_id VARCHAR, 
    age int
);

En este ejemplo, queremos añadir un array de mascotas propiedad de cada usuario, que corresponde a owner_id. Concretamente, queremos incluir la identificación, la raza, el tipo y el nombre. Podemos utilizar la siguiente consulta para rellenar una tabla o una vista:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
SELECT 
CURRENT_TIMESTAMP as UPDATED_AT,
owner_id as EXTERNAL_ID,
TO_JSON(
    OBJECT_CONSTRUCT(
        '_merge_objects','true',
       'pets',
        OBJECT_CONSTRUCT(
           '$add', ARRAY_AGG( OBJECT_CONSTRUCT(
                'id',
                pet_id,
                'breed',
                breed,
                'type',
                type,
                'name',
                name
                )) WITHIN GROUP (ORDER BY type ASC)    
        )
    )
)
as PAYLOAD from BRAZE_CLOUD_INGESTION_DEMO.BRAZE_SCHEMA.pet_list group by EXTERNAL_ID;

El resultado esperado sería el siguiente:

1
2
3
4
UPDATED_AT	EXTERNAL_ID	PAYLOAD
2023-10-02 19:56:17.377 +0000	03409324	{"_merge_objects":"true","pets":{"$add":[{"breed":"parakeet","id":5,"name":"Mary","type":"bird"}]}}
2023-10-02 19:56:17.377 +0000	21231234	{"_merge_objects":"true","pets":{"$add":[{"breed":"calico","id":2,"name":"Gerald","type":"cat"},{"breed":"beagle","id":1,"name":"Gus","type":"dog"}]}}
2023-10-02 19:56:17.377 +0000	12335345	{"_merge_objects":"true","pets":{"$add":[{"breed":"corgi","id":3,"name":"Doug","type":"dog"},{"breed":"salmon","id":4,"name":"Larry","type":"fish"}]}}

A continuación, para enviar un campo de nombre actualizado y un nuevo campo de edad para cada propietario, podemos utilizar la siguiente consulta para rellenar una tabla o vista:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
SELECT 
CURRENT_TIMESTAMP as UPDATED_AT,
owner_id as EXTERNAL_ID,
TO_JSON(
    OBJECT_CONSTRUCT(
        '_merge_objects','true',
       'pets',
        OBJECT_CONSTRUCT(
           '$update', ARRAY_AGG( OBJECT_CONSTRUCT(
                '$identifier_key','id',
                '$identifier_value',pet_id,
                '$new_object',OBJECT_CONSTRUCT(
                    'name',name,
                    'age',age
                )
                )) WITHIN GROUP (ORDER BY type ASC)    
        )
    )
)
as PAYLOAD from BRAZE_CLOUD_INGESTION_DEMO.BRAZE_SCHEMA.pet_list group by EXTERNAL_ID; 

El resultado esperado sería el siguiente:

1
2
3
4
UPDATED_AT	EXTERNAL_ID	PAYLOAD
2023-10-02 19:50:25.266 +0000	03409324	{"_merge_objects":"true","pets":{"$update":[{"$identifier_key":"id","$identifier_value":5,"$new_object":{"age":7,"name":"Mary"}}]}}
2023-10-02 19:50:25.266 +0000	21231234	{"_merge_objects":"true","pets":{"$update":[{"$identifier_key":"id","$identifier_value":2,"$new_object":{"age":3,"name":"Gerald"}},{"$identifier_key":"id","$identifier_value":1,"$new_object":{"age":3,"name":"Gus"}}]}}
2023-10-02 19:50:25.266 +0000	12335345	{"_merge_objects":"true","pets":{"$update":[{"$identifier_key":"id","$identifier_value":3,"$new_object":{"age":6,"name":"Doug"}},{"$identifier_key":"id","$identifier_value":4,"$new_object":{"age":1,"name":"Larry"}}]}}

Utilización de puntos de datos

La facturación del punto de datos para la ingesta de datos en la nube es equivalente a la facturación de las actualizaciones a través del punto final /users/track. Consulte Puntos de datos para obtener más información.

Recomendaciones para la configuración de datos

Escribir sólo atributos nuevos o actualizados para minimizar el consumo

Cada vez que se ejecuta una sincronización, Braze busca filas que no se hayan sincronizado previamente. Lo comprobamos utilizando la columna UPDATED_AT de su tabla o vista. Todas las filas en las que UPDATED_AT sea posterior a la última fila sincronizada se seleccionarán y se introducirán en Braze, independientemente de si coinciden o no con lo que hay actualmente en el perfil del usuario. Por ello, recomendamos sincronizar únicamente los atributos que desee añadir o actualizar.

El consumo de puntos de datos con CDI es idéntico al de otros métodos de ingesta como las API REST o los SDK, por lo que depende de usted asegurarse de que sólo añade atributos nuevos o actualizados a sus tablas de origen.

Utiliza una fecha y hora UTC para la columna UPDATED_AT

La columna UPDATED_AT debe estar en UTC para evitar problemas con el horario de verano. Prefiere funciones solo UTC, como SYSDATE() en lugar de CURRENT_DATE() siempre que sea posible.

Asegúrate de que la hora de UPDATED_AT no coincide con la hora de tu sincronización.

Tu sincronización CDI podría tener datos duplicados si algún campo de UPDATED_AT está exactamente a la misma hora que tu hora de sincronización anterior. Esto se debe a que el CDI elegirá un “límite inclusivo” cuando detecte cualquier fila que coincida en el tiempo con la sincronización anterior, y hará que las filas sean viables para sincronizar. El CDI volverá a analizar esas filas y creará datos duplicados.

Separa EXTERNAL_ID de la columna PAYLOAD

El objeto PAYLOAD no debe incluir un ID externo u otro tipo de ID.

Eliminar un atributo

Puedes establecerlo en null si quieres omitir un atributo del perfil de un usuario. Si quieres que un atributo no se modifique, no lo envíes a Braze hasta que se haya actualizado. Para eliminar completamente un atributo, utiliza TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL(...)).

Haz actualizaciones incrementales

Realiza actualizaciones incrementales de tus datos para evitar sobrescrituras involuntarias cuando se realicen actualizaciones simultáneas.

En el siguiente ejemplo, un usuario tiene dos atributos:

• Color: “Verde”
• Talla: “Grande”

Entonces Braze recibe simultáneamente las dos actualizaciones siguientes para ese usuario:

• Petición 1: Cambiar el color a “Rojo”
• Petición 2: Cambia el tamaño a “Medio”

Como la Petición 1 se produce en primer lugar, los atributos del usuario se actualizan a lo siguiente:

• Color: “Rojo”
• Talla: “Grande”

Sin embargo, cuando se produce la Petición 2, Braze comienza con los valores originales de los atributos (“Verde” y “Grande”) y, a continuación, actualiza los atributos del usuario a los siguientes:

• Color: “Rojo”
• Talla: “Medio”

Cuando finalicen las solicitudes, la Solicitud 2 sobrescribirá la actualización de la Solicitud 1, por lo que es mejor escalonar las actualizaciones para evitar que se sobrescriban las solicitudes.

Crear una cadena JSON a partir de otra tabla

Si prefiere almacenar internamente cada atributo en su propia columna, deberá convertir esas columnas en una cadena JSON para rellenar la sincronización con Braze. Para ello, puede utilizar una consulta del tipo:

• snowflake
• redshift
• bigquery
• databricks
• microsoft fabric

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
CREATE TABLE "EXAMPLE_USER_DATA"
    (attribute_1 string,
     attribute_2 string,
     attribute_3 number,
     my_user_id string);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
        OBJECT_CONSTRUCT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'yet_another_attribute',
            attribute_3)
    )as PAYLOAD FROM "EXAMPLE_USER_DATA";

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
CREATE TABLE "EXAMPLE_USER_DATA"
    (attribute_1 string,
     attribute_2 string,
     attribute_3 number,
     my_user_id string);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    JSON_SERIALIZE(
        OBJECT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'yet_another_attribute',
            attribute_3)
    ) as PAYLOAD FROM "EXAMPLE_USER_DATA";

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (attribute_1 string,
     attribute_2 STRING,
     attribute_3 NUMERIC,
     my_user_id STRING);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
      STRUCT(
        'attribute_1' AS attribute_1,
        'attribute_2'AS attribute_2,
        'yet_another_attribute'AS attribute_3
      )
    ) as PAYLOAD 
  FROM BRAZE.EXAMPLE_USER_DATA;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (
    attribute_1 string,
    attribute_2 STRING,
    attribute_3 NUMERIC,
    my_user_id STRING
);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
      STRUCT(
        attribute_1,
        attribute_2,
        attribute_3
      )
    ) as PAYLOAD 
  FROM BRAZE.EXAMPLE_USER_DATA;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
CREATE TABLE [braze].[users] (
    attribute_1 VARCHAR,
    attribute_2 VARCHAR,
    attribute_3 VARCHAR,
    attribute_4 VARCHAR,
    user_id VARCHAR
)
GO

CREATE VIEW [braze].[user_update_example]
AS SELECT 
    user_id as EXTERNAL_ID,
    CURRENT_TIMESTAMP as UPDATED_AT,
    JSON_OBJECT('attribute_1':attribute_1, 'attribute_2':attribute_2, 'attribute_3':attribute_3, 'attribute_4':attribute_4) as PAYLOAD

FROM [braze].[users] ;

Utiliza la marca de tiempo UPDATED_AT

Utilizamos la marca de tiempo UPDATED_AT para realizar un seguimiento de los datos que se han sincronizado correctamente con Braze. Si se escriben muchas filas con la misma marca de tiempo mientras se está ejecutando una sincronización, esto puede provocar que se sincronicen datos duplicados con Braze. Algunas sugerencias para evitar la duplicación de datos:

• Si estás configurando una sincronización con un VIEW, no utilices CURRENT_TIMESTAMP como valor predeterminado. Esto hará que todos los datos se sincronicen cada vez que se ejecute la sincronización porque el campo UPDATED_AT se evaluará a la hora en que se ejecuten nuestras consultas.
• Si tiene procesos o consultas de muy larga duración que escriben datos en la tabla de origen, evite ejecutarlos simultáneamente con una sincronización, o evite utilizar la misma marca de tiempo para cada fila insertada.
• Utilice una transacción para escribir todas las filas que tengan la misma marca de tiempo.

Configuración de la tabla

Disponemos de un repositorio público en GitHub para que los clientes compartan las mejores prácticas o fragmentos de código. Para contribuir con tus propios fragmentos de código, ¡crea un pull request!

Formato de los datos

Cualquier operación que sea posible a través del punto final Braze /users/track se admite a través de la Ingesta de datos en la nube, incluida la actualización de atributos personalizados anidados, la adición del estado de suscripción y la sincronización de eventos personalizados o compras.

Los campos de la carga útil deben seguir el mismo formato que el punto final correspondiente de /users/track. A continuación se detallan los requisitos de formato:

Tenga en cuenta el requisito especial para capturar fechas en atributos anidados.

• atributos personalizados anidados
• evento
• comprar
• grupos de suscripción

1
2
3
4
5
6
7
8
9
10
11
12
{
      "most_played_song": {
        "song_name": "Solea",
        "artist_name": "Miles Davis",
        "album_name": "Sketches of Spain",
        "genre": "Jazz",
        "play_analytics": {
            "count": 1000,
            "top_10_listeners": true
        }
      }
}

1
2
3
4
5
6
7
8
9
{
    "app_id" : "your-app-id",
    "name" : "rented_movie",
    "time" : "2013-07-16T19:20:45+01:00",
    "properties": {
        "movie": "The Sad Egg",
        "director": "Dan Alexander"
    }
} 

1
2
3
4
5
6
7
8
9
10
11
12
{
    "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
    "product_id" : "Completed Order",
    "currency" : "USD",
    "price" : 219.98,
    "time" : "2013-07-16T19:20:30+01:00",
    "properties" : {
        "products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99, },
        { "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99, }
        ]
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "subscription_groups" : [
        {
            "subscription_group_id": "subscription_group_identifier_1",
            "subscription_state": "unsubscribed"
        },
        {
            "subscription_group_id": "subscription_group_identifier_2",
            "subscription_state": "subscribed"
        },
        {
            "subscription_group_id": "subscription_group_identifier_3",
            "subscription_state": "subscribed"
        }
      ]
}

Evitar tiempos de espera en las consultas al almacén de datos

Recomendamos que las consultas se realicen en el plazo de una hora para obtener un rendimiento óptimo y evitar posibles errores. Si las consultas superan este plazo, considere la posibilidad de revisar la configuración de su almacén de datos. La optimización de los recursos asignados a su almacén puede ayudar a mejorar la velocidad de ejecución de las consultas.

Limitaciones del producto