Personalização sem cópia usando CDI

Aprenda a sincronizar gatilhos do Canvas usando CDI para personalização sem cópia. Esse recurso acessa informações específicas do usuário a partir da sua solução de armazenamento de dados e as transmite para um Canvas de destino. As etapas do Canvas podem incluir, opcionalmente, campos de personalização que não são mantidos nos perfis de usuário da Braze.

Sincronizando disparadores de Canvas

Etapas de início rápido

Se você já conhece o CDI da Braze, saiba que a configuração de uma sincronização de disparadores de Canvas segue de perto o processo das integrações de CDI para dados de usuários, com as seguintes ressalvas:

• Somente identificadores de ID externo ou alias de usuário são aceitos. E-mail e números de telefone não são identificadores aceitos.
• Somente usuários existentes na Braze podem ser sincronizados. Novos usuários não podem ser criados.
• properties substitui a coluna payload. Trata-se de uma string JSON dos campos que você deseja usar como propriedades de entrada do Canvas para personalização.

Para começar, selecione o tipo de dados Canvas Triggers ao criar uma nova sincronização.

Usando disparadores de Canvas

Etapa 1: Configurar a fonte de dados para disparadores de Canvas

• snowflake
• redshift
• bigquery
• databricks
• fabric
• armazenamento de arquivos

Etapa 1.1: Configure sua tabela de origem no Snowflake

Você pode usar os nomes do exemplo a seguir ou escolher seus próprios nomes de banco de dados, esquema e tabela. Também é possível usar uma view ou uma view materializada em vez de uma tabela.

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

Você pode nomear o banco de dados, o esquema e a tabela como preferir, mas os nomes das colunas devem corresponder à definição anterior.

• UPDATED_AT: A hora em que esta linha foi atualizada ou adicionada à tabela. A Braze sincroniza as linhas em que UPDATED_AT é posterior ao último valor sincronizado. Linhas no timestamp exato do limite podem ser sincronizadas novamente se novas linhas compartilharem o mesmo timestamp.
• external_id ou alias_name e alias_label como coluna de identificador do usuário. Esses campos identificam os usuários para os quais você deseja disparar o envio de mensagens pelo Canvas.
  • EXTERNAL_ID: Identifica o usuário a ser inserido no Canvas. Deve corresponder ao valor external_id usado na Braze.
  • ALIAS_NAME e ALIAS_LABEL: Essas colunas criam um objeto de alias de usuário. alias_name deve ser um identificador exclusivo, e alias_label especifica o tipo de alias. Os usuários podem ter vários aliases com diferentes labels, mas apenas um alias_name por alias_label.
• PROPERTIES: Uma string JSON de campos a serem disponibilizados como propriedades de personalização no seu Canvas. Deve conter informações específicas do usuário.

Nota

As propriedades não são obrigatórias para cada linha ou usuário. No entanto, os valores de propriedades devem ser uma string JSON válida. Insira uma string {} vazia se não houver propriedades para a linha.

Etapa 1.2: Configure as credenciais

Configure uma role, um warehouse e um usuário e conceda as permissões adequadas. Se você já possui credenciais de uma sincronização existente, pode reutilizá-las, mas certifique-se de estender o acesso à tabela de origem dos disparadores 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;

Etapa 1.3: Configure as políticas de rede

Se a sua conta possui políticas de rede, adicione os IPs da Braze à lista de permissões para habilitar a conexão do serviço CDI. Para a lista de IPs, consulte Ingestão de dados na nuvem.

Etapa 1.1: Configure sua tabela de origem no Redshift

Você pode usar os nomes do exemplo a seguir ou escolher seus próprios nomes de banco de dados, esquema e tabela. Também é possível usar uma view ou uma view materializada em vez de uma tabela.

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

Você pode nomear o banco de dados, o esquema e a tabela como preferir, mas os nomes das colunas devem corresponder à definição anterior.

• UPDATED_AT: A hora em que esta linha foi atualizada ou adicionada à tabela. A Braze sincroniza as linhas em que UPDATED_AT é posterior ao último valor sincronizado. Linhas no timestamp exato do limite podem ser sincronizadas novamente se novas linhas compartilharem o mesmo timestamp.
• external_id ou alias_name e alias_label como coluna de identificador do usuário. Esses campos identificam os usuários para os quais você deseja disparar o envio de mensagens pelo Canvas.
  • EXTERNAL_ID: Identifica o usuário a ser inserido no Canvas. Deve corresponder ao valor external_id usado na Braze.
  • ALIAS_NAME e ALIAS_LABEL: Essas colunas criam um objeto de alias de usuário. alias_name deve ser um identificador exclusivo, e alias_label especifica o tipo de alias. Os usuários podem ter vários aliases com diferentes labels, mas apenas um alias_name por alias_label.
• PROPERTIES: Uma string JSON de campos a serem disponibilizados como propriedades de personalização no seu Canvas. Deve conter informações específicas do usuário.

Nota

As propriedades não são obrigatórias para cada linha ou usuário. No entanto, os valores de propriedades devem ser uma string JSON válida. Insira uma string {} vazia se não houver propriedades para a linha.

Etapa 1.2: Configure as credenciais

Configure uma role, um warehouse e um usuário e conceda as permissões adequadas. Se você já possui credenciais de uma sincronização existente, pode reutilizá-las, mas certifique-se de estender o acesso à tabela de origem dos disparadores 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;

Etapa 1.3: Configure as políticas de rede

Se a sua conta possui políticas de rede, adicione os IPs da Braze à lista de permissões para habilitar a conexão do serviço CDI. Para a lista de IPs, consulte Ingestão de dados na nuvem.

Etapa 1.1: Crie um novo projeto ou dataset para sua tabela de origem (opcional)

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Etapa 1.2: Configure sua tabela de origem no BigQuery

Consulte o seguinte ao criar sua tabela de origem:

Nome do campo	Tipo	Obrigatório?
UPDATED_AT	Timestamp	Sim
PROPERTIES	JSON	Sim
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE

Nota

As propriedades não são obrigatórias para cada linha ou usuário. No entanto, os valores de propriedades devem ser uma string JSON válida. Insira uma string {} vazia se não houver propriedades para a linha.

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

Etapa 1.3: Configure as credenciais

Crie um usuário e conceda as permissões. Se você já possui credenciais de outra sincronização, pode reutilizá-las desde que tenham acesso à tabela de disparadores de Canvas.

Permissão	Finalidade
BigQuery Connection User	Permite que a Braze se conecte.
BigQuery User	Permite que a Braze execute consultas, leia metadados e liste tabelas.
BigQuery Data Viewer	Permite que a Braze visualize datasets e conteúdos.
BigQuery Job User	Permite que a Braze execute jobs.

Após conceder as permissões, configure como a Braze se autentica como a conta de serviço:

Workload Identity Federation: Vincule o principal da Braze à conta de serviço para não precisar criar uma chave. Para ver as etapas, consulte Configurando o Google Cloud para Workload Identity Federation.

Chave de conta de serviço: Gere uma chave JSON. Consulte Criar e excluir chaves para instruções. Você fará o upload dela no dashboard da Braze posteriormente.

Etapa 1.4: Configure as políticas de rede

Se a sua conta possui políticas de rede, adicione os IPs da Braze à lista de permissões para habilitar a conexão do serviço CDI. Para a lista de IPs, consulte Ingestão de dados na nuvem.

Etapa 1.1: Crie um catálogo ou esquema para sua tabela de origem.

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Etapa 1.2: Configure sua tabela de origem no Databricks

Consulte o seguinte ao criar sua tabela de origem:

Nome do campo	Tipo	Obrigatório
UPDATED_AT	Timestamp	Sim
PROPERTIES	JSON	Sim
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE

Você pode nomear o esquema e a tabela como preferir, mas os nomes das colunas devem corresponder à definição anterior.

• UPDATED_AT: A hora em que esta linha foi atualizada ou adicionada à tabela. A Braze sincroniza as linhas em que UPDATED_AT é posterior ao último valor sincronizado. Linhas no timestamp exato do limite podem ser sincronizadas novamente se novas linhas compartilharem o mesmo timestamp.
• external_id ou alias_name e alias_label como coluna de identificador do usuário. Esses campos identificam os usuários para os quais você deseja disparar o envio de mensagens pelo Canvas.
  • EXTERNAL_ID: Identifica o usuário a ser inserido no Canvas. Deve corresponder ao valor external_id usado na Braze.
  • ALIAS_NAME e ALIAS_LABEL: Essas colunas criam um objeto de alias de usuário. alias_name deve ser um identificador exclusivo, e alias_label especifica o tipo de alias. Os usuários podem ter vários aliases com diferentes labels, mas apenas um alias_name por alias_label.
• PROPERTIES: Uma string ou struct de campos a serem disponibilizados como propriedades de personalização no seu Canvas. Deve conter informações específicas do usuário.

Nota

As propriedades não são obrigatórias para cada linha ou usuário. No entanto, os valores de propriedades devem ser strings JSON válidas. Insira uma string {} vazia se não houver propriedades para a linha.

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

Etapa 1.3: Configure as credenciais

Crie um service principal com credenciais OAuth máquina a máquina (M2M) (recomendado) ou um token de acesso pessoal. Se você já possui credenciais de outra sincronização, pode reutilizá-las desde que tenham acesso à tabela de disparadores de Canvas.

OAuth M2M: Crie um service principal, gere um client secret, conceda ao service principal a permissão Can use no seu SQL warehouse e conceda SELECT na tabela de disparadores de Canvas. Para ver as etapas, consulte Criar credenciais para a Braze.

Token de acesso pessoal:

1. Selecione seu nome de usuário e depois selecione User Settings.
2. Na guia Access tokens, selecione Generate new token.
3. Adicione um comentário para identificar o token, como “Braze CDI”.
4. Deixe Lifetime (days) em branco para não haver expiração e selecione Generate.
5. Copie e salve o token de forma segura para uso no dashboard da Braze.

Etapa 1.4: Configure as políticas de rede

Se a sua conta possui políticas de rede, adicione os IPs da Braze à lista de permissões para habilitar a conexão do serviço CDI. Para a lista de IPs, consulte Ingestão de dados na nuvem.

Etapa 1.1: Configure sua tabela de origem no 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

Etapa 1.2: Configure as credenciais

Crie um service principal e conceda as permissões. Se você já possui credenciais de outra sincronização, pode reutilizá-las — apenas certifique-se de que elas tenham acesso à tabela de contas.

Etapa 1.3: Configure as políticas de rede

Se a sua conta possui políticas de rede, adicione os IPs da Braze à lista de permissões para habilitar a conexão do serviço CDI. Para a lista de IPs, consulte Ingestão de dados na nuvem.

Para sincronizar disparadores de Canvas a partir do armazenamento de arquivos, crie um arquivo de origem com os campos a seguir.

Campo	Obrigatório	Descrição
EXTERNAL_ID	Sim, um entre external_id ou alias_name e alias_label	Identifica o usuário que você deseja atualizar. Deve corresponder ao valor external_id usado na Braze.
ALIAS_NAME e ALIAS_LABEL	Sim, um entre external_id ou alias_name e alias_label	Essas duas colunas criam um objeto de alias de usuário. alias_name deve ser um identificador exclusivo, e alias_label especifica o tipo de alias. Os usuários podem ter vários aliases com diferentes labels, mas apenas um alias_name por alias_label.
PROPERTIES	Sim	String JSON de campos a serem disponibilizados como propriedades de personalização no seu Canvas. Deve conter informações específicas do usuário.

Dica

Os nomes dos arquivos devem seguir as regras da AWS e ser exclusivos. Adicione timestamps para ajudar a garantir a exclusividade. Para mais informações sobre sincronização com o Amazon S3, consulte Integrações de armazenamento de arquivos.

Etapa 2: Configurar seu Canvas de destino

1. Configure seu Canvas de destino para disparadores de Canvas. Crie um novo Canvas ou selecione um existente disparado por API. Consulte Tipos de agendamento de entrada para instruções sobre como criar um Canvas com um tipo de agendamento de entrega disparado por API.
2. Após selecionar o tipo de agendamento de entrega disparado por API, continue com a configuração e construa seu Canvas. Os Canvas podem variar desde envios simples de uma única mensagem até fluxos de trabalho complexos com várias etapas.
3. Dentro das etapas do seu Canvas, use as propriedades de entrada do Canvas para personalizar mensagens com os campos de propriedades que você planeja sincronizar da sua tabela de origem.
   • Por exemplo, se na Etapa 1 você configurou um campo de propriedades para account_balance, você usaria o seguinte template Liquid para personalizar sua mensagem: \{\{canvas_entry_properties.\$\{account_balance\}\}\}.
4. Após construir seu Canvas, lance-o e prossiga para a Etapa 3.

Etapa 3: Criar sua sincronização zero copy

Com a configuração da origem concluída e o Canvas de destino lançado, crie uma nova sincronização de dados:

1. Na Braze, acesse Data Settings > Cloud Data Ingestion.
2. Configure a conexão inserindo os detalhes de conexão (ou reutilize credenciais existentes) e a tabela de origem da Etapa 1.
3. Forneça um nome para a integração.
4. Selecione o tipo de dados Canvas triggers.
5. Escolha seu Canvas de destino (da Etapa 2).
6. Escolha uma frequência de sincronização.
7. Configure as preferências de notificação.
8. Selecione Test Connection para confirmar que tudo funciona conforme o esperado. Se estiver conectando ao Snowflake, primeiro adicione a chave pública exibida no dashboard ao usuário criado para a Braze se conectar ao Snowflake. Para concluir esta etapa, você precisará de acesso SECURITYADMIN ou superior no Snowflake.
9. Salve a sincronização para começar a sincronizar disparadores de Canvas.

Quando a sincronização for executada, os usuários na sua tabela de origem começarão a entrar no Canvas. Use a análise de dados do Canvas e a página de logs de sincronização da ingestão de dados na nuvem para monitorar o desempenho.

Dica

Revise toda a sua configuração (desde o comportamento de sincronização até a configuração do Canvas) para evitar envios inesperados. Configurações do Canvas, como limite de frequência, limite de frequência de mensagens e filtros de segmentação, podem refinar ainda mais a entrega de mensagens.

Recomendamos realizar um teste com um público pequeno ou de teste antes de implementar casos de uso em produção.

Considerações

Os disparadores de Canvas via CDI utilizam o limite de frequência da sua REST API para /canvas/trigger/send. Se você estiver usando esse endpoint simultaneamente com disparadores de Canvas via CDI e sua integração REST API, espere que o uso combinado conte para o seu limite de frequência.

Cada execução de sincronização insere usuários no Canvas de destino a uma taxa máxima de aproximadamente 3,75 milhões de usuários por hora. Esteja preparado para tempos mais longos entre a origem e a entrada no Canvas quando:

• Sincronizar mais de 3,75 milhões de usuários por execução de sincronização.
• Usar disparadores de Canvas via CDI quando o limite de frequência da REST API para /canvas/trigger/send já estiver saturado.

Considere o seguinte sobre o CDI zero copy quando o arquivamento de mensagens estiver ativado:

• Os resultados da tabela são armazenados temporariamente na Braze durante o processamento. Eles também são exportados para o Snowflake por 30 dias para que você possa ver exatamente o que foi sincronizado.
• As mensagens arquivadas não são salvas em nenhum lugar dentro da Braze. As cópias são enviadas para serem armazenadas exclusivamente no seu armazenamento configurado.
• Ao usar o CDI zero copy com disparadores de Canvas, a Braze não armazena um backup dos resultados de consulta do data warehouse e nenhum dado é copiado para o perfil do usuário.
• As propriedades de contexto do Canvas podem ser registradas em sistemas internos por até 30 dias.