Ir para o conteúdo

Esta página foi traduzida automaticamente e pode conter imprecisões. Para relatar um erro de tradução, use o componente de feedback na parte inferior do sumário, à direita da página.

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 na 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 ficam salvos nos perfis de usuário da Braze.

Sincronização de gatilhos do Canvas

Etapas de início rápido

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

Só são aceitos os identificadores ID externo ou alias de usuário. E-mail e números de telefone não são identificadores aceitos.
Só é possível sincronizar usuários que já existem na Braze. Não é possível criar novos usuários.
properties substitui a coluna payload. Trata-se de uma string JSON com os campos que você quer usar como propriedades de entrada do Canvas para personalização.

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

Uso de gatilhos do Canvas

Etapa 1: Configure a fonte de dados para os gatilhos do Canvas

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.

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 dar o nome que quiser ao banco de dados, ao esquema e à tabela, mas os nomes das colunas devem seguir a definição anterior.

UPDATED_AT: O momento em que esta linha foi atualizada ou adicionada à tabela. A Braze sincroniza as linhas em que UPDATED_AT é posterior ao último valor sincronizado. Linhas com o timestamp exato do limite podem ser sincronizadas novamente se novas linhas tiverem esse mesmo timestamp.
external_id ou alias_name e alias_label como coluna de identificador do usuário. Elas identificam os usuários para os quais você quer disparar mensagens do Canvas.
- EXTERNAL_ID: Identifica o usuário que vai entrar no Canvas. Deve corresponder ao valor de 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 rótulos diferentes, mas apenas um alias_name por alias_label.
PROPERTIES: Uma string JSON de campos que ficarão disponíveis como propriedades de personalização no seu Canvas. Deve conter informações específicas do usuário.

Nota

Propriedades não são obrigatórias para todas as linhas ou usuários. No entanto, os valores de propriedades devem ser uma string JSON válida. Insira uma string vazia {} se a linha não tiver propriedades.

Etapa 1.2: Configure as credenciais

Configure uma função, um warehouse e um usuário e conceda as permissões adequadas. Se você já tiver credenciais de uma sincronização existente, pode reutilizá-las, mas não se esqueça de estender o acesso à tabela de origem dos gatilhos do Canvas.

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;

A instrução CREATE USER deste exemplo serve para autenticação por par de chaves RSA. Para a Workload Identity Federation, crie a função e o warehouse como mostrado e crie o usuário de serviço a partir do formulário de credenciais do Snowflake. As concessões de função, warehouse e banco de dados continuam as mesmas. A política de rede da próxima etapa continua se aplicando. Para ver a instrução e onde executá-la, consulte Configuração do Snowflake para Workload Identity Federation.

Etapa 1.3: Configure as políticas de rede

Se a sua conta tiver políticas de rede, coloque os IPs da Braze na lista de permissões para ativar a conexão do serviço de CDI. Para ver 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.

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 dar o nome que quiser ao banco de dados, ao esquema e à tabela, mas os nomes das colunas devem seguir a definição anterior.

UPDATED_AT: O momento em que esta linha foi atualizada ou adicionada à tabela. A Braze sincroniza as linhas em que UPDATED_AT é posterior ao último valor sincronizado. Linhas com o timestamp exato do limite podem ser sincronizadas novamente se novas linhas tiverem esse mesmo timestamp.
external_id ou alias_name e alias_label como coluna de identificador do usuário. Elas identificam os usuários para os quais você quer disparar mensagens do Canvas.
- EXTERNAL_ID: Identifica o usuário que vai entrar no Canvas. Deve corresponder ao valor de 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 rótulos diferentes, mas apenas um alias_name por alias_label.
PROPERTIES: Uma string JSON de campos que ficarão disponíveis como propriedades de personalização no seu Canvas. Deve conter informações específicas do usuário.

Nota

Etapa 1.2: Configure as credenciais

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 tiver políticas de rede, coloque os IPs da Braze na lista de permissões para ativar a conexão do serviço de CDI. Para ver a lista de IPs, consulte Ingestão de dados na nuvem.

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

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Etapa 1.2: Configure sua tabela de origem no BigQuery

Consulte a tabela a seguir 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

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á tiver credenciais de outra sincronização, pode reutilizá-las, desde que tenham acesso à tabela de gatilhos do 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 conjuntos de dados e seus conteúdos.
BigQuery Job User	Permite que a Braze execute jobs.

Depois de 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, assim você não precisa criar uma chave. Para ver as etapas, consulte Configuração do Google Cloud para Workload Identity Federation.

Chave da conta de serviço: Gere uma chave JSON. Consulte Criar e excluir chaves para ver as instruções. Você vai fazer o upload dela no dashboard da Braze mais tarde.

Etapa 1.4: Configure as políticas de rede

Se a sua conta tiver políticas de rede, coloque os IPs da Braze na lista de permissões para ativar a conexão do serviço de CDI. Para ver 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.

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Etapa 1.2: Configure sua tabela de origem no Databricks

Consulte a tabela a seguir 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 dar o nome que quiser ao esquema e à tabela, mas os nomes das colunas devem seguir a definição anterior.

UPDATED_AT: O momento em que esta linha foi atualizada ou adicionada à tabela. A Braze sincroniza as linhas em que UPDATED_AT é posterior ao último valor sincronizado. Linhas com o timestamp exato do limite podem ser sincronizadas novamente se novas linhas tiverem esse mesmo timestamp.
external_id ou alias_name e alias_label como coluna de identificador do usuário. Elas identificam os usuários para os quais você quer disparar mensagens do Canvas.
- EXTERNAL_ID: Identifica o usuário que vai entrar no Canvas. Deve corresponder ao valor de 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 rótulos diferentes, mas apenas um alias_name por alias_label.
PROPERTIES: Uma string ou struct de campos que ficarão disponíveis como propriedades de personalização no seu Canvas. Deve conter informações específicas do usuário.

Nota

Propriedades não são obrigatórias para todas as linhas ou usuários. No entanto, os valores de propriedades devem ser strings JSON válidas. Insira uma string vazia {} se a linha não tiver propriedades.

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 principal de serviço com credenciais OAuth máquina a máquina (M2M) (recomendado) ou um token de acesso pessoal. Se você já tiver credenciais de outra sincronização, pode reutilizá-las, desde que tenham acesso à tabela de gatilhos do Canvas.

OAuth M2M: Crie um principal de serviço, gere um segredo de cliente, conceda ao principal de serviço a permissão Can use no seu SQL warehouse e conceda a ele SELECT na tabela de gatilhos do Canvas. Para ver as etapas, consulte Criar credenciais para a Braze.

Token de acesso pessoal:

Selecione seu nome de usuário e depois User Settings.
Na guia Access tokens, selecione Generate new token.
Adicione um comentário para identificar o token, como “Braze CDI”.
Deixe Lifetime (days) em branco para que o token não expire e selecione Generate.
Copie e guarde o token com segurança para usar no dashboard da Braze.

Etapa 1.4: Configure as políticas de rede

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

Etapa 1.1: Configure sua tabela de origem no Fabric

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 principal de serviço e conceda as permissões. Se você já tiver credenciais de outra sincronização, pode reutilizá-las. Só confirme que elas têm acesso à tabela de contas.

Etapa 1.3: Configure as políticas de rede

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

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

Campo	Obrigatório	Descrição
`EXTERNAL_ID`	Sim, um entre `external_id` ou `alias_name` e `alias_label`	Identifica o usuário que você quer atualizar. Deve corresponder ao valor de `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 rótulos diferentes, mas apenas um `alias_name` por `alias_label`.
`PROPERTIES`	Sim	String JSON de campos que ficarão disponíveis como propriedades de personalização no seu Canvas. Deve conter informações específicas do usuário.

Dica

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

Etapa 2: Configure seu Canvas de destino

Configure seu Canvas de destino para os gatilhos do Canvas. Crie um novo Canvas disparado por API ou selecione um existente. Consulte Tipos de cronograma de entrada para ver instruções sobre como criar um Canvas com o tipo de cronograma de entrega disparado por API.
Depois de selecionar o tipo de cronograma de entrega disparado por API, continue a configuração e monte seu Canvas. Os Canvas podem ir desde envios simples de uma única mensagem até fluxos complexos de clientes com várias etapas.
Nas etapas do seu Canvas, use as propriedades de entrada do Canvas para personalizar mensagens com os campos de propriedades que você pretende sincronizar da sua tabela de origem.
- Por exemplo, se na Etapa 1 você instrumentou um campo de propriedades para account_balance, use o seguinte template Liquid para personalizar sua mensagem: \{\{canvas_entry_properties.\$\{account_balance\}\}\}.
Depois de montar seu Canvas, lance-o e siga para a Etapa 3.

Etapa 3: Crie 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:

Na Braze, acesse Configurações de dados > Ingestão de dados na nuvem.
Configure a conexão informando os detalhes de conexão (ou reutilize credenciais existentes) e a tabela de origem da Etapa 1.
Dê um nome à integração.
Selecione o tipo de dados Gatilhos do Canvas.
Escolha seu Canvas de destino (da Etapa 2).
Escolha uma frequência de sincronização.
Configure as preferências de notificação.
Selecione Testar conexão para confirmar que tudo funciona como esperado. Se estiver se conectando ao Snowflake com um par de chaves RSA, primeiro adicione a chave pública exibida no dashboard ao usuário criado para a Braze. Para concluir essa etapa, você precisa de acesso SECURITYADMIN ou superior no Snowflake. Se estiver se conectando com Workload Identity Federation, execute a instrução do formulário de credenciais antes de testar a conexão. Consulte Configuração do Snowflake para Workload Identity Federation.
Salve a sincronização para começar a sincronizar os gatilhos do Canvas.
Selecione Testar conexão para confirmar que tudo funciona como esperado. Se estiver se conectando ao Snowflake com um par de chaves RSA, primeiro adicione a chave pública exibida no dashboard ao usuário criado para a Braze. Para concluir essa etapa, você precisa de acesso SECURITYADMIN ou superior no Snowflake. Se estiver se conectando com Workload Identity Federation, execute a instrução do formulário de credenciais antes de testar a conexão. Consulte Configuração do Snowflake para Workload Identity Federation.

Dica

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

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

Considerações

Os gatilhos do Canvas da CDI usam o limite de taxa da sua REST API para /canvas/trigger/send. Se você estiver usando esse endpoint ao mesmo tempo com os gatilhos do Canvas da CDI e com sua integração da REST API, o uso combinado vai contar para o seu limite de taxa.

Cada execução de sincronização insere usuários no respectivo Canvas de destino a uma taxa máxima de aproximadamente 3,75 milhões de usuários por hora. Espere tempos maiores 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 gatilhos do Canvas da CDI quando já estiver atingindo o limite de taxa para /canvas/trigger/send da sua REST API.

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

Os resultados da tabela ficam 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 da Braze. As cópias são enviadas para armazenamento exclusivamente no armazenamento que você configurou.
Ao usar a CDI zero-copy com gatilhos do Canvas, a Braze não armazena um backup dos resultados da consulta do data warehouse, e nenhum dado é copiado para o perfil de usuário.
As propriedades de contexto do Canvas podem ser registradas em sistemas internos por até 30 dias.

New Stuff!