Personalización sin copia utilizando CDI

Aprende a sincronizar los desencadenantes de Canvas utilizando CDI para una personalización sin copia. Esta característica accede a información específica del usuario desde tu solución de almacenamiento de datos y la transfiere a un Canvas de destino. Los pasos en Canvas pueden incluir opcionalmente campos de personalización que no se conservan en los perfiles de usuario de Braze.

Sincronización de desencadenadores de Canvas

Pasos de inicio rápido

Si ya estás familiarizado con Braze CDI, ten en cuenta que la configuración de una sincronización de desencadenadores de Canvas sigue de cerca el proceso de las integraciones CDI de datos de usuario, con las siguientes consideraciones:

• Solo se admiten identificadores de ID externo o alias de usuario. Los correos electrónicos y números de teléfono no son identificadores admitidos.
• Solo se pueden sincronizar usuarios existentes de Braze. No se pueden crear usuarios nuevos.
• properties reemplaza la columna payload. Es una cadena JSON con los campos que deseas usar como propiedades de entrada de Canvas para la personalización.

Para comenzar, selecciona el tipo de datos Canvas Triggers al crear una nueva sincronización.

Uso de desencadenadores de Canvas

Paso 1: Configurar el origen de datos para desencadenadores de Canvas

• snowflake
• redshift
• bigquery
• databricks
• fabric
• almacenamiento de archivos

Paso 1.1: Configurar la tabla de origen en Snowflake

Puedes usar los nombres del siguiente ejemplo o elegir tus propios nombres de base de datos, esquema y tabla. También puedes usar una vista o una vista materializada en lugar de una tabla.

1
2
3
4
5
6
7
8
9
10
11

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
CREATE OR REPLACE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC (
     UPDATED_AT TIMESTAMP_NTZ(9) NOT NULL DEFAULT SYSDATE(),
     --at least one of external_id or alias_name and alias_label is required
     EXTERNAL_ID VARCHAR(16777216),
     --if using user alias, both alias_name and alias_label are required
     ALIAS_LABEL VARCHAR(16777216),
     ALIAS_NAME VARCHAR(16777216),
     PROPERTIES VARCHAR(16777216)
);

Puedes nombrar la base de datos, el esquema y la tabla como desees, pero los nombres de las columnas deben coincidir con la definición anterior.

• UPDATED_AT: La hora en que se actualizó o añadió esta fila a la tabla. Braze sincroniza las filas donde UPDATED_AT es posterior al último valor sincronizado. Las filas en la marca de tiempo límite exacta pueden volver a sincronizarse si nuevas filas comparten esa misma marca de tiempo.
• external_id o alias_name y alias_label como columna de identificador de usuario. Estos identifican a los usuarios para quienes deseas desencadenar la mensajería de Canvas.
  • EXTERNAL_ID: Identifica al usuario que entrará en Canvas. Debe coincidir con el valor de external_id utilizado en Braze.
  • ALIAS_NAME y ALIAS_LABEL: Estas columnas crean un objeto de alias de usuario. alias_name debe ser un identificador único, y alias_label especifica el tipo de alias. Los usuarios pueden tener múltiples alias con diferentes etiquetas, pero solo un alias_name por alias_label.
• PROPERTIES: Una cadena JSON de campos que estarán disponibles como propiedades de personalización en tu Canvas. Debe contener información específica del usuario.

Nota

Las propiedades no son obligatorias para cada fila o usuario. Sin embargo, los valores de propiedades deben ser una cadena JSON válida. Introduce una cadena {} vacía si no hay propiedades para la fila.

Paso 1.2: Configurar las credenciales

Configura un rol, un almacén y un usuario, y otorga los permisos adecuados. Si ya tienes credenciales de una sincronización existente, puedes reutilizarlas, pero asegúrate de extender el acceso a la tabla de origen de desencadenadores de Canvas.

1
2
3
4
5
6
7
8
9
10
11
12
13

CREATE ROLE BRAZE_INGESTION_ROLE;

GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC TO ROLE BRAZE_INGESTION_ROLE;

CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;

CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

Paso 1.3: Configurar políticas de red

Si tu cuenta tiene políticas de red, añade las IP de Braze a la lista de permitidos para habilitar la conexión del servicio CDI. Para la lista de IP, consulta Ingesta de datos en la nube.

Paso 1.1: Configurar la tabla de origen en Redshift

Puedes usar los nombres del siguiente ejemplo o elegir tus propios nombres de base de datos, esquema y tabla. También puedes usar una vista o una vista materializada en lugar de una tabla.

1
2
3
4
5
6
7
8
9
10
11

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC (
    updated_at timestamptz default sysdate not null,
    --at least one of external_id or alias_name and alias_label is required
    external_id varchar not null,.
    --if using user alias, both alias_name and alias_label are required
    alias_label varchar,
    alias_name varchar,
    properties varchar(max)
 );

Puedes nombrar la base de datos, el esquema y la tabla como desees, pero los nombres de las columnas deben coincidir con la definición anterior.

• UPDATED_AT: La hora en que se actualizó o añadió esta fila a la tabla. Braze sincroniza las filas donde UPDATED_AT es posterior al último valor sincronizado. Las filas en la marca de tiempo límite exacta pueden volver a sincronizarse si nuevas filas comparten esa misma marca de tiempo.
• external_id o alias_name y alias_label como columna de identificador de usuario. Estos identifican a los usuarios para quienes deseas desencadenar la mensajería de Canvas.
  • EXTERNAL_ID: Identifica al usuario que entrará en Canvas. Debe coincidir con el valor de external_id utilizado en Braze.
  • ALIAS_NAME y ALIAS_LABEL: Estas columnas crean un objeto de alias de usuario. alias_name debe ser un identificador único, y alias_label especifica el tipo de alias. Los usuarios pueden tener múltiples alias con diferentes etiquetas, pero solo un alias_name por alias_label.
• PROPERTIES: Una cadena JSON de campos que estarán disponibles como propiedades de personalización en tu Canvas. Debe contener información específica del usuario.

Nota

Las propiedades no son obligatorias para cada fila o usuario. Sin embargo, los valores de propiedades deben ser una cadena JSON válida. Introduce una cadena {} vacía si no hay propiedades para la fila.

Paso 1.2: Configurar las credenciales

Configura un rol, un almacén y un usuario, y otorga los permisos adecuados. Si ya tienes credenciales de una sincronización existente, puedes reutilizarlas, pero asegúrate de extender el acceso a la tabla de origen de desencadenadores de Canvas.

1
2
3

CREATE USER braze_user PASSWORD '{password}';
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION to braze_user;
GRANT SELECT ON TABLE CANVAS_TRIGGERS_SYNC TO braze_user;

Paso 1.3: Configurar políticas de red

Si tu cuenta tiene políticas de red, añade las IP de Braze a la lista de permitidos para habilitar la conexión del servicio CDI. Para la lista de IP, consulta Ingesta de datos en la nube.

Paso 1.1: Crear un nuevo proyecto o conjunto de datos para la tabla de origen (opcional)

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Paso 1.2: Configurar la tabla de origen en BigQuery

Consulta lo siguiente al crear tu tabla de origen:

Nombre del campo	Tipo	¿Obligatorio?
UPDATED_AT	Timestamp	Sí
PROPERTIES	JSON	Sí
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE

Nota

Las propiedades no son obligatorias para cada fila o usuario. Sin embargo, los valores de propiedades deben ser una cadena JSON válida. Introduce una cadena {} vacía si no hay propiedades para la fila.

1
2
3
4
5
6
7
8
9
10

CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp,
  --At least one of external_id or alias_name and alias_label is required
  external_id STRING,
  --If using user alias, both alias_name and alias_label are required
  alias_name STRING,
  alias_label STRING,
  properties JSON
);

Paso 1.3: Configurar las credenciales

Crea un usuario y otorga permisos. Si ya tienes credenciales de otra sincronización, puedes reutilizarlas siempre que tengan acceso a la tabla de desencadenadores de Canvas.

Permiso	Propósito
BigQuery Connection User	Permite que Braze se conecte.
BigQuery User	Permite que Braze ejecute consultas, lea metadatos y liste tablas.
BigQuery Data Viewer	Permite que Braze vea conjuntos de datos y su contenido.
BigQuery Job User	Permite que Braze ejecute trabajos.

Después de otorgar los permisos, configura cómo Braze se autentica como la cuenta de servicio:

Workload Identity Federation: Vincula el principal de Braze a la cuenta de servicio para no tener que crear una clave. Para conocer los pasos, consulta Configuración de Google Cloud para Workload Identity Federation.

Clave de cuenta de servicio: Genera una clave JSON. Consulta Crear y eliminar claves para obtener instrucciones. La cargarás en el panel de Braze más adelante.

Paso 1.4: Configurar políticas de red

Si tu cuenta tiene políticas de red, añade las IP de Braze a la lista de permitidos para habilitar la conexión del servicio CDI. Para la lista de IP, consulta Ingesta de datos en la nube.

Paso 1.1: Crear un catálogo o esquema para la tabla de origen.

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Paso 1.2: Configurar la tabla de origen en Databricks

Consulta lo siguiente al crear tu tabla de origen:

Nombre del campo	Tipo	Obligatorio
UPDATED_AT	Timestamp	Sí
PROPERTIES	JSON	Sí
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE

Puedes nombrar el esquema y la tabla como desees, pero los nombres de las columnas deben coincidir con la definición anterior.

• UPDATED_AT: La hora en que se actualizó o añadió esta fila a la tabla. Braze sincroniza las filas donde UPDATED_AT es posterior al último valor sincronizado. Las filas en la marca de tiempo límite exacta pueden volver a sincronizarse si nuevas filas comparten esa misma marca de tiempo.
• external_id o alias_name y alias_label como columna de identificador de usuario. Estos identifican a los usuarios para quienes deseas desencadenar la mensajería de Canvas.
  • EXTERNAL_ID: Identifica al usuario que entrará en Canvas. Debe coincidir con el valor de external_id utilizado en Braze.
  • ALIAS_NAME y ALIAS_LABEL: Estas columnas crean un objeto de alias de usuario. alias_name debe ser un identificador único, y alias_label especifica el tipo de alias. Los usuarios pueden tener múltiples alias con diferentes etiquetas, pero solo un alias_name por alias_label.
• PROPERTIES: Una cadena o estructura de campos que estarán disponibles como propiedades de personalización en tu Canvas. Debe contener información específica del usuario.

Nota

Las propiedades no son obligatorias para cada fila o usuario. Sin embargo, los valores de propiedades deben ser cadenas JSON válidas. Introduce una cadena {} vacía si no hay propiedades para la fila.

1
2
3
4
5
6
7
8
9
10

CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.USERS_ATTRIBUTES_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp(),
  --At least one of external_id or alias_name and alias_label is required
  external_id STRING,
  --If using user alias, both alias_name and alias_label are required
  alias_name STRING,
  alias_label STRING,
  properties STRING, STRUCT, or MAP
);

Paso 1.3: Configurar las credenciales

Crea un principal de servicio con credenciales OAuth máquina a máquina (M2M) (recomendado), o un token de acceso personal. Si ya tienes credenciales de otra sincronización, puedes reutilizarlas siempre que tengan acceso a la tabla de desencadenadores de Canvas.

OAuth M2M: Crea un principal de servicio, genera un secreto de cliente, otorga al principal de servicio el permiso Can use en tu almacén SQL y otórgale SELECT en la tabla de desencadenadores de Canvas. Para conocer los pasos, consulta Crear credenciales para Braze.

Token de acceso personal:

1. Selecciona tu nombre de usuario y luego selecciona User Settings.
2. En la pestaña Access tokens, selecciona Generate new token.
3. Añade un comentario para identificar el token, como “Braze CDI”.
4. Deja Lifetime (days) en blanco para que no tenga vencimiento y luego selecciona Generate.
5. Copia y guarda el token de forma segura para usarlo en el panel de Braze.

Paso 1.4: Configurar políticas de red

Si tu cuenta tiene políticas de red, añade las IP de Braze a la lista de permitidos para habilitar la conexión del servicio CDI. Para la lista de IP, consulta Ingesta de datos en la nube.

Paso 1.1: Configurar la tabla de origen en Fabric

1
2
3
4
5
6
7
8
9
10
11

CREATE OR ALTER TABLE [warehouse].[schema].[CDI_table_name]
(
  UPDATED_AT DATETIME2(6) NOT NULL,
  PROPERTIES VARCHAR NOT NULL,
  --at least one of external_id or alias_name and alias_label is required
  EXTERNAL_ID VARCHAR,
  --if using user alias, both alias_name and alias_label are required
  ALIAS_NAME VARCHAR,
  ALIAS_LABEL VARCHAR
)
GO

Paso 1.2: Configurar las credenciales

Crea un principal de servicio y otorga permisos. Si ya tienes credenciales de otra sincronización, puedes reutilizarlas; solo asegúrate de que tengan acceso a la tabla de cuentas.

Paso 1.3: Configurar políticas de red

Si tu cuenta tiene políticas de red, añade las IP de Braze a la lista de permitidos para habilitar la conexión del servicio CDI. Para la lista de IP, consulta Ingesta de datos en la nube.

Para sincronizar desencadenadores de Canvas desde almacenamiento de archivos, crea un archivo de origen con los siguientes campos.

Campo	Obligatorio	Descripción
EXTERNAL_ID	Sí, uno de external_id o alias_name y alias_label	Identifica al usuario que deseas actualizar. Debe coincidir con el valor de external_id utilizado en Braze.
ALIAS_NAME y ALIAS_LABEL	Sí, uno de external_id o alias_name y alias_label	Estas dos columnas crean un objeto de alias de usuario. alias_name debe ser un identificador único, y alias_label especifica el tipo de alias. Los usuarios pueden tener múltiples alias con diferentes etiquetas, pero solo un alias_name por alias_label.
PROPERTIES	Sí	Cadena JSON de campos que estarán disponibles como propiedades de personalización en tu Canvas. Debe contener información específica del usuario.

Consejo

Los nombres de archivo deben seguir las reglas de AWS y ser únicos. Añade marcas de tiempo para garantizar la unicidad. Para obtener más información sobre la sincronización con Amazon S3, consulta Integraciones de almacenamiento de archivos.

Paso 2: Configurar tu Canvas de destino

1. Configura tu Canvas de destino para los desencadenadores de Canvas. Crea un Canvas nuevo o selecciona uno existente activado por API. Consulta Tipos de programación de entrada para obtener instrucciones sobre cómo crear un Canvas con un tipo de programación de entrega activada por API.
2. Después de seleccionar el tipo de programación de entrega activada por API, continúa con la configuración de Canvas y construye tu Canvas. Los Canvas pueden ir desde envíos simples de un solo mensaje hasta flujos de trabajo complejos de clientes con múltiples pasos.
3. Dentro de los pasos de tu Canvas, usa las propiedades de entrada de Canvas para personalizar mensajes con los campos de propiedades que planeas sincronizar desde tu tabla de origen.
   • Por ejemplo, si en el paso 1 instrumentaste un campo de propiedades para account_balance, usarías la siguiente plantilla Liquid para personalizar tu mensaje: \{\{canvas_entry_properties.\$\{account_balance\}\}\}.
4. Después de construir tu Canvas, lánzalo y continúa al Paso 3.

Paso 3: Crear tu sincronización de copia cero

Con la configuración de tu origen completa y el Canvas de destino lanzado, crea una nueva sincronización de datos:

1. En Braze, ve a Configuración de datos > Ingesta de datos en la nube.
2. Configura la conexión introduciendo los detalles de conexión (o reutiliza credenciales existentes) y la tabla de origen del Paso 1.
3. Proporciona un nombre para la integración.
4. Selecciona el tipo de datos Canvas triggers.
5. Elige tu Canvas de destino (del Paso 2).
6. Elige una frecuencia de sincronización.
7. Configura las preferencias de notificación.
8. Selecciona Test Connection para confirmar que todo funciona como se espera. Si te conectas a Snowflake, primero añade la clave pública mostrada en el panel al usuario creado para que Braze se conecte a Snowflake. Para completar este paso, necesitarás acceso SECURITYADMIN o superior en Snowflake.
9. Guarda la sincronización para comenzar a sincronizar los desencadenadores de Canvas.

Cuando se ejecute la sincronización, los usuarios de tu tabla de origen comenzarán a entrar en Canvas. Usa los análisis de Canvas y la página de registros de sincronización de ingesta de datos en la nube para monitorizar el rendimiento.

Consejo

Revisa toda tu configuración (desde el comportamiento de sincronización hasta la configuración de Canvas) para evitar envíos inesperados. La configuración de Canvas, como el límite de velocidad, la limitación de frecuencia y los filtros de segmentación, puede refinar aún más la entrega de mensajes.

Recomendamos realizar una prueba con una audiencia pequeña o de prueba antes de implementar casos de uso en producción.

Consideraciones

Los desencadenadores de Canvas por CDI utilizan tu límite de velocidad de REST API para /canvas/trigger/send. Si estás usando este endpoint simultáneamente con los desencadenadores de Canvas por CDI y tu integración de REST API, el uso combinado contará para tu límite de velocidad.

Cada ejecución de sincronización hace entrar usuarios en su Canvas de destino correspondiente a una tasa máxima de aproximadamente 3,75 millones de usuarios por hora. Prepárate para tiempos más largos desde el origen hasta la entrada en Canvas cuando:

• Sincronices más de 3,75 millones de usuarios por ejecución de sincronización.
• Uses desencadenadores de Canvas por CDI cuando ya estés saturando el límite de velocidad de tu REST API para /canvas/trigger/send.

Ten en cuenta lo siguiente sobre CDI de copia cero cuando el archivado de mensajes está habilitado:

• Los resultados de la tabla se almacenan temporalmente en Braze durante el procesamiento. También se exportan a Snowflake durante 30 días para que puedas ver exactamente lo que se sincronizó.
• Los mensajes archivados no se guardan en ningún lugar dentro de Braze. Las copias se envían para almacenarse exclusivamente en tu almacenamiento configurado.
• Al usar CDI de copia cero con desencadenadores de Canvas, Braze no almacena una copia de seguridad de los resultados de la consulta del almacén de datos y no se copian datos en el perfil de usuario.
• Las propiedades de contexto de Canvas pueden registrarse en sistemas internos durante un máximo de 30 días.