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. Em cada execução, a Klaviyo lê apenas as linhas cujo carimbo de data/hora de detecção de alterações é mais recente do que a última sincronização bem-sucedida. Isso permite importações incrementais sem reprocessar toda a tabela.
3. Cada linha é então processada da seguinte forma:
   • A Klaviyo determina o nome da métrica (tipo de evento) com base nas opções selecionadas durante a configuração da sincronização: uma única métrica escolhida ou dinamicamente com base no valor de uma coluna de nome de métrica designada na tabela de origem.
   • O carimbo de data/hora do evento, os identificadores de perfil e a ID exclusiva opcional, o valor e a moeda do valor são definidos com base nos mapeamentos de campo configurados durante a configuração da sincronização.
   • Todas as colunas restantes são ingeridas como propriedades de evento, usando os nomes das colunas como nomes de propriedades. Nomes de colunas com três sublinhados (por exemplo, parent___child1, parent___child2) podem ser usados para criar uma propriedade de 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.

As importações são executadas em uma cadência recorrente (por exemplo, por hora), para que as linhas novas ou atualizadas no seu warehouse sejam traduzidas regularmente em eventos na Klaviyo.

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.
• Você criou e validou uma conexão do data warehouse na Klaviyo. Consulte os artigos da central de suporte do seu data warehouse para obter detalhes sobre a conta de serviço e os esquemas necessários.
• 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 colunas a seguir são obrigatórias na V1 da 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:

• As colunas são importadas como propriedades niveladas, com o nome da coluna usado diretamente como o nome da propriedade na Klaviyo.
• 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 você ainda não conectou seu warehouse:

1. Na Klaviyo, acesse Advanced KDP > Data management > Syncing.
2. Clique em Adicionar data warehouse e selecione seu conector de warehouse.
3. Conclua as etapas de conexão de sua plataforma seguindo o guia de conexão aplicável vinculado do artigo de visão geral da importação do data warehouse.

A Klaviyo aceita uma conexão ativa do data warehouse por conta.

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

Quando seu warehouse estiver conectado:

1. Em Advanced KDP > Data management > Syncing, selecione sua conexão de warehouse.
2. Escolha Importar dados (se estiver configurando importações pela primeira vez) ou clique em Criar sincronização / Adicionar sincronização para uma conexão existente.
3. Quando solicitado para o tipo de dados, selecione Eventos (em vez de Perfis).
4. Escolha a tabela ou a exibição no seu warehouse que contém os eventos que você deseja importar.

3) Mapear campos obrigatórios

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

A configuração de importação de eventos exige que você forneça mapeamentos para:

• Carimbo de data/hora do evento
• Nome da métrica (uma constante selecionada na configuração ou uma coluna que contenha o nome da métrica por linha)
• Identificador de perfil (pelo menos um)
• Alterar carimbo de data/hora de detecção

Você também pode mapear campos recomendados:

• ID única
• Valor
• 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.

4) Escolha cadência de sincronização e escopo histórico

Quando você salvar sua importação de eventos:

• A Klaviyo agenda sincronizações recorrentes para serem executadas em uma cadência regular (normalmente de hora em hora).
• Em cada execução, somente as linhas cujo carimbo de data/hora de detecção de alterações é mais recente do que a última execução bem-sucedida são processadas, garantindo que as importações sejam incrementais.

Para o preenchimento histórico, 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 exclusiva e, mais tarde, mude para uma visualização apoiada pela captura de dados alterados para atualizações contínuas.

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:

• A V1 da importação de eventos se concentra somente nos dados do evento. As propriedades do perfil devem ser atualizadas por meio da importação de perfil ou de 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 obter a velocidade ideal, defina o campo de detecção de alterações como a data e hora de criação da nova tabela. Os registros são agrupados em ciclos de sincronização usando esse valor, portanto, o tempo para importar registros históricos pode ser reduzido se todos os registros históricos tiverem carimbos de data/hora de detecção de alterações em um intervalo estreito (por exemplo, o carimbo de data/hora de uma tarefa que cria a nova tabela).
• Sempre que possível, use uma ID única estável por evento para melhorar a desduplicação e facilitar a depuração downstream.
• Se sua tabela contiver vários tipos de eventos (métricas) com conjuntos diferentes de colunas, é normal mantê-los juntos: colunas NULL para linhas específicas são simplesmente ignoradas para esses eventos na Klaviyo.
• 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 o carimbo de data/hora de detecção de alterações em cluster próximo à data atual. A Klaviyo lê os dados em janelas de 1 hora, iterando a partir do carimbo de data/hora de detecção de alterações mais antigo da tabela. Se alguma linha tiver um registro de data/hora de detecção de alterações muito antigo (por exemplo, um único registro de 2023 quando todos os outros são recentes), a Klaviyo fará a varredura a cada janela de 1 hora a partir dessa data em cada ciclo de sincronização, resultando em um histórico lento de tempo de sincronização de preenchimento.
• 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.

Configuração recomendada da chave de agrupamento do Snowflake

Para tabelas Snowflake, agrupar na coluna de carimbo de data/hora de detecção de alterações ajuda as consultas da Klaviyo a ignorar micropartições desnecessárias, reduzindo o tempo de sincronização e os custos de computação do Snowflake:

ALTER TABLE your_schema.your_table CLUSTER BY (your_change_timestamp_column);