Como funciona a importação de eventos do data warehouse na Klaviyo

O que você vai aprender

Saiba como usar a importação de eventos do data warehouse para sincronizar dados de eventos do seu warehouse com a Klaviyo, para que você possa alimentar segmentos, fluxos e relatórios com comportamentos que se originam fora das integrações nativas da Klaviyo (por exemplo, sistemas POS, plataformas de suporte ou aplicativos personalizados).

O que é importação de eventos do data warehouse?

A importação de eventos do data warehouse permite que a Klaviyo se conecte diretamente ao seu data warehouse e configure sincronizações de importação a partir de tabelas ou visualizações do warehouse que contenham dados de eventos.

Cada linha em sua tabela de origem é tratada como um único evento na Klaviyo:

• Os carimbos de data/hora, o nome da métrica e os identificadores da linha definem o que aconteceu, quando e para quem.
• Colunas adicionais se tornam propriedades de eventos que você pode usar em segmentação, fluxos e análises.

A importação de eventos é criada na mesma infraestrutura de importação do data warehouse que a importação de perfis, mas segmenta o pipeline de ingestão de eventos da Klaviyo em vez de perfis.

Como funciona a importação de eventos do data warehouse?

Depois de conectar a Klaviyo ao seu warehouse e configurar uma sincronização de eventos:

1. A Klaviyo consulta seu warehouse para a tabela ou visualização configurada.
2. A primeira importação lê o histórico disponível na sua origem. As execuções posteriores continuam a partir do progresso salvo usando o carimbo de data/hora de detecção de alterações, para que a Klaviyo não reprocesse a tabela inteira.
3. Cada linha é então processada da seguinte forma:
   • A Klaviyo determina o nome da métrica (tipo de evento) com base em uma métrica da API existente que você seleciona ou no valor de uma coluna de nome da métrica designada em cada linha.
   • O carimbo de data/hora do evento, os identificadores de perfil e o ID exclusivo e o valor opcionais são definidos com base nos mapeamentos de campos configurados durante a configuração da sincronização.
   • Todas as colunas restantes são ingeridas como propriedades do evento, usando os nomes das colunas como nomes de propriedades. Nomes de colunas com 3 sublinhados (por exemplo, parent___child1, parent___child2) podem ser usados para criar uma propriedade do evento (parent) com propriedades filhas.
4. A Klaviyo carrega os eventos resultantes na sua conta, onde eles se comportam como outras métricas de API personalizadas em segmentação, fluxos e análises.

Você pode programar importações recorrentes (por exemplo, a cada hora) ou escolher Manual para executar importações quando necessário.

Antes de começar

Verifique se os seguintes requisitos foram atendidos antes de criar uma sincronização de importação de eventos:

• Sua conta tem acesso à Advanced KDP e à importação do data warehouse.
• Prepare as credenciais e os esquemas da conta de serviço necessários para o seu warehouse. Consulte os guias de conexão em Entendendo a Data Warehouse Import no Klaviyo.
• Sua tabela ou visualização de origem contém as colunas necessárias abaixo.
• Você tem privilégios suficientes no seu warehouse para expor as tabelas/visualizações necessárias ao usuário de serviço da Klaviyo.

Estrutura da tabela de origem para eventos

Para garantir que seus dados de eventos possam ser importados corretamente, sua tabela ou visualização de origem deve atender aos campos e estrutura obrigatórios da Klaviyo.

Campos obrigatórios

As seguintes colunas são obrigatórias para a importação de eventos do data warehouse:

Campos opcionais

Esses campos são recomendados quando aplicáveis, mas não estritamente necessários:

Propriedades do evento

Todas as outras colunas na sua tabela são tratadas como propriedades de evento:

• Os nomes das colunas se tornam nomes de propriedades de nível superior, a menos que contenham 3 sublinhados (___), que criam propriedades filhas aninhadas conforme descrito acima.
• Você não precisa mapear explicitamente todas as propriedades; colunas não mapeadas serão incluídas como propriedades de evento.
• O JSON aninhado pode ser armazenado dentro de um valor de propriedade individual, se necessário (por exemplo, um objeto JSON de itens de linha), mas o próprio nome da propriedade vem de uma coluna de nível superior.

A Klaviyo realiza a análise do tipo de melhor esforço para propriedades de eventos e não fornece a lógica de transformação por campo como parte da configuração de importação de eventos.

Casos de uso comuns

Normalmente, os clientes usam a importação de eventos do data warehouse para:

1) Importação de eventos offline ou POS

Traga eventos in -store ou offline (por exemplo, compras, devoluções ou compromissos de PDV) do seu warehouse para que eles se comportem como outros eventos e métricas da Klaviyo.

Exemplos:

• In-Store Purchase eventos com totais de pedidos, localização da loja e tipo de forma de pagamento
• Appointment Completed eventos com membro da equipe, tipo de serviço e duração

2) Interações de serviço e suporte

Sincronize eventos de suporte e serviço, como criação, resolução de tíquetes ou devoluções, para enriquecer as linhas do tempo dos clientes e potencializar as mensagens com base no histórico de serviços.

Exemplos:

• Support Ticket Created e Support Ticket Resolved
• Order Returned com códigos de motivo e valores de reembolso

3) Eventos modelados ou derivados

Converta comportamentos modelados no warehouse em eventos mais fáceis de usar na Klaviyo.

Exemplos:

• High Churn Risk eventos gerados a partir de um modelo no seu data warehouse
• Lifecycle Milestone Reached eventos quando um cliente muda de estágio em um modelo de ciclo de vida personalizado

Configurar uma sincronização de importação de eventos do data warehouse

1) Conecte seu data warehouse

Se o seu armazém já estiver conectado, pule para a etapa 2. Caso contrário:

1. Na Klaviyo, acesse Advanced KDP > Data management > Syncing.
2. Clique em Criar sincronização se você já tiver sincronizações configuradas. Selecione Importar dados do seu data warehouse e, em seguida, selecione o conector do seu warehouse.
3. Conclua as etapas de preparação do warehouse no guia de conexão aplicável com link em Como entender o Data Warehouse Import no Klaviyo.
4. Clique em Conectar a e, em seguida, no nome do seu data warehouse. Insira os detalhes de conexão obrigatórios e, em seguida, clique em Próxima.
5. Clique em Testar. Depois que a conexão for bem-sucedida e a Klaviyo puder acessar pelo menos 1 tabela ou visualização, clique em Próxima.

Você pode criar várias conexões de Data Warehouse Import e adicionar tabelas ou visualizações de origem a cada conexão.

Antes de criar a sincronização, decida quais eventos históricos incluir. Você pode:

• Aponte sua importação de eventos para uma tabela ou visualização que já inclua todos os eventos históricos relevantes, ou
• Comece com uma tabela histórica dedicada e, depois, mude para uma visualização baseada em change data capture para atualizações contínuas. Mantenha as mesmas colunas mapeadas e, depois, dê às novas linhas carimbos de data/hora de detecção de alterações posteriores ao progresso salvo da sincronização.

2) Crie uma nova sincronização de importação de eventos

Para uma nova conexão, continue na configuração que você abriu acima. Para uma conexão existente, primeiro:

1. Em Advanced KDP > Data management > Syncing, selecione sua conexão de warehouse.
2. Clique em Adicionar origem.

Na configuração de sincronização:

1. Insira um Nome para a sincronização e, opcionalmente, uma Descrição.
2. Em Fonte de dados, selecione a tabela ou visualização que contém os eventos que você quer importar.
3. Em Tipos de objeto de dados, selecione Eventos.

3) Escolha a cadência de sincronização

1. Em Cadência, escolha como executar a sincronização:
   • Agendar execução: escolha o intervalo em A cada e defina a Data de início, a Hora de início e o Fuso horário. O intervalo padrão é de 1 hora.
   • Manual: salve a sincronização sem um agendamento recorrente e execute quando necessário.
2. Clique em Próximo para mapear os campos.

4) Mapeie os campos obrigatórios

Em seguida, você mapeará as colunas da tabela do warehouse para os campos de eventos obrigatórios da Klaviyo.

Conclua estes mapeamentos:

1. Em Detecção de alterações, selecione sua coluna de carimbo de data/hora de detecção de alterações em Detecção de novas linhas. Use uma coluna de origem diferente da coluna de carimbo de data/hora do evento.
2. Em Tipo de evento, escolha 1 destas opções:
   • Mesmo tipo de evento: selecione uma métrica de API existente para todas as linhas.
   • Tipo de evento específico para cada linha: selecione a coluna que contém o nome da métrica de cada linha. Use esta opção se a métrica de que você precisa não estiver na lista de métricas de API existente.
3. Em Carimbos de data/hora do evento, selecione a coluna que registra quando o evento ocorreu.
4. Em Propriedades do perfil, clique em Adicionar mapeamento e mapeie pelo menos um identificador de perfil (por exemplo, e-mail, número de telefone, ID externo ou ID da Klaviyo).

Você também pode mapear campos recomendados:

• ID única
• Valor

Para manter os metadados de moeda (por exemplo, USD), deixe a coluna sem mapeamento para que ela se torne uma propriedade de evento. Não há um mapeamento dedicado de Moeda do valor.

Todas as colunas restantes que você não mapear explicitamente para esses campos principais automaticamente se tornarão propriedades de evento.

A UI de configuração impede que você mapeie várias colunas para o mesmo campo de nível superior e valida se todos os campos obrigatórios estão presentes antes de permitir que você salve.

5) Salve e verifique a sincronização

1. Revise suas configurações e clique em Concluído para salvar a sincronização da importação de eventos.
2. Na página de conexão do data warehouse, clique no nome da sincronização. Se a configuração levou você de volta para a visão geral de Sincronização, selecione primeiro a conexão do data warehouse.
3. Se você escolheu Manual, clique em Executar sincronização para iniciar a importação. As importações agendadas são executadas de acordo com a cadência que você selecionou.
4. Verifique Histórico de execução para acompanhar o progresso e Logs para ver erros.

Como os eventos importados se comportam na Klaviyo

Uma vez importado:

• Cada linha aparece como um evento de uma métrica de API personalizada na Klaviyo.
• O nome da métrica que você mapeou (ou configurou como uma constante) determina o nome do tipo de evento que você vê no produto (por exemplo, Placed Order).
• Todos os identificadores de perfil são resolvidos para os perfis existentes sempre que possível; caso contrário, a Klaviyo cria novos perfis usando os campos de identificadores fornecidos, semelhantes a outros caminhos de ingestão de eventos.

Você pode usar esses eventos para:

• Crie segmentos com base no que alguém fez e filtre nas propriedades do evento.
• Disparar e filtrar fluxos.
• Analise o comportamento em métricas e relatórios juntamente com eventos de outras fontes.

Limitações e práticas recomendadas

Lembre-se do seguinte ao usar a importação de eventos do data warehouse:

• Use a importação de eventos para dados de eventos. Para atualizar as Propriedades do perfil, use a importação de perfil ou outros caminhos compatíveis.
• O carimbo de data/hora da detecção de alterações deve ser diferente do carimbo de data/hora do evento. Usar a mesma coluna para ambos pode impedir que você importe eventos históricos com segurança após a primeira sincronização.
• Para backfills históricos, use o momento em que cada linha foi carregada no data warehouse como o timestamp de detecção de alterações. Um job que cria uma tabela histórica pode armazenar o timestamp desse job nas linhas para manter o intervalo estreito. Não recalcule este carimbo de data/hora toda vez que uma visualização for consultada e siga as orientações de volume de linhas abaixo.
• Use um ID exclusivo e estável por evento sempre que possível para melhorar a deduplicação e facilitar a depuração. Reimportar o mesmo ID para o mesmo perfil e a mesma métrica é tratado como duplicado; isso não atualiza as propriedades do evento.
• Você pode manter vários tipos de evento (métricas) na mesma tabela. Colunas não mapeadas são incluídas como propriedades do evento; por isso, use visualizações separadas se você precisar de conjuntos de propriedades diferentes para métricas diferentes.
• Para objetos aninhados complexos (por exemplo, matrizes de itens de linha), recomendamos o achatamento em várias colunas, quando viável, especialmente para propriedades que você espera usar em segmentação ou fluxos.
• Mantenha os carimbos de data e hora históricos de detecção de alterações em um intervalo curto. Durante o backfill inicial, a Klaviyo lê os dados em janelas de 1 hora a partir do carimbo de data e hora de detecção de alterações mais antigo. Um único registro de 2023 quando todos os outros são recentes pode deixar esse backfill mais lento, porque a Klaviyo precisa avançar pelas janelas intermediárias. As execuções posteriores retomam a partir do progresso salvo, em vez de começar novamente pelo registro mais antigo.
• Não ultrapasse aproximadamente 100.000 linhas em uma única janela de carimbo de data/hora de detecção de alterações de 1 hora. Se muitas linhas compartilharem a mesma janela de 1 hora, a consulta de sincronização pode expirar.

Melhore o desempenho de consultas do Snowflake

Configuração recomendada da chave de agrupamento do Snowflake

Para tabelas grandes do Snowflake, uma chave de clustering no timestamp de detecção de alterações pode ajudar as consultas a ignorar micro-partições desnecessárias. Teste consultas representativas antes de adicionar uma chave e compare qualquer economia de consultas com os créditos do Snowflake usados para manter o clustering:

ALTER TABLE your_schema.your_table CLUSTER BY (your_change_timestamp_column);