Cómo funciona la importación de eventos del almacén de datos en Klaviyo

Objetivos del artículo

Aprende a utilizar la importación de eventos de almacenes de datos para sincronizar datos de eventos de tu almacén con Klaviyo, de modo que puedas impulsar segmentos, flujos e informes con un comportamiento que se origina fuera de las integraciones nativas de Klaviyo (por ejemplo, sistemas POS, plataformas de asistencia o aplicaciones personalizadas).

¿Qué es la importación de eventos del almacén de datos?

La importación de eventos del almacén de datos permite que Klaviyo se conecte directamente a tu almacén de datos y configure las sincronizaciones de importación desde tablas del almacén o vistas que contengan datos de eventos.

Cada fila de tu tabla de origen se trata como un único evento en Klaviyo:

• Las marcas de tiempo, el nombre de la métrica y los identificadores de la fila definen lo que sucedió, cuándo, y para quién.
• Las columnas adicionales se convierten en propiedades de evento que puedes usar en segmentación, flujos y análisis.

La importación de eventos se basa en la misma infraestructura de importación del almacén de datos que la importación de perfiles, pero se dirige a la canalización de ingesta de eventos de Klaviyo en lugar de a los perfiles.

¿Cómo funciona la importación de eventos del almacén de datos?

Después de conectar Klaviyo a tu almacén y configurar la sincronización de un evento:

1. Klaviyo consulta tus almacenes para la tabla o vista configurada.
2. La primera importación lee el historial disponible en el origen. Las ejecuciones posteriores se reanudan desde el progreso guardado usando la marca de tiempo de detección de cambios, por lo que Klaviyo no vuelve a procesar toda la tabla.
3. Cada fila se procesa de la siguiente manera:
   • Klaviyo determina el nombre de la métrica (tipo de evento) a partir de una métrica existente de la interfaz de programación de aplicaciones (API) que selecciones o del valor de una columna designada de nombre de métrica en cada fila.
   • La marca de tiempo del evento, los identificadores de perfil y el ID único y el valor opcionales se establecen en función de las asignaciones de campos configuradas durante la configuración de la sincronización.
   • Todas las columnas restantes se ingieren como propiedades de eventos, con los nombres de las columnas como nombres de propiedad. Los nombres de columna con 3 guiones bajos (por ejemplo, parent___child1, parent___child2) se pueden usar para crear una propiedad de evento (parent) con propiedades secundarias.
4. Klaviyo carga los eventos resultantes en tu cuenta, donde se comportan como otras métricas personalizadas de la API en segmentación, flujos y análisis.

Puedes programar importaciones recurrentes (por ejemplo, cada hora) o elegir Manual para ejecutar importaciones cuando sea necesario.

Antes de empezar

Asegúrate de que cumples con los siguientes requisitos antes de crear una sincronización de importación de eventos:

• Tu cuenta tiene acceso a Advanced KDP y a la importación de almacenes de datos.
• Prepara las credenciales y los esquemas de la cuenta de servicio necesarios para el almacén de datos. Consulta las guías de conexión en Comprender la Importación desde almacén de datos en Klaviyo.
• Tu tabla o vista de origen contiene las columnas obligatorias que aparecen a continuación.
• Tienes privilegios suficientes en tu almacén para exponer las tablas/vistas necesarias al usuario del servicio de Klaviyo.

Estructura de la tabla de origen para los eventos

Para asegurarte de que los datos de tus eventos se puedan importar correctamente, tu tabla o vista de origen debe satisfacer la estructura y los campos obligatorios de Klaviyo.

Campos obligatorios

Las siguientes columnas son obligatorias para la importación de eventos del almacén de datos:

Campos opcionales

Estos campos se recomiendan cuando corresponda, pero no son estrictamente necesarios:

Propiedades del evento

Todas las demás columnas de la tabla se tratan como propiedades de evento:

• Los nombres de las columnas se convierten en nombres de propiedades de nivel superior, a menos que contengan 3 guiones bajos (___), que crean propiedades secundarias anidadas como se describió anteriormente.
• No tienes que asignar explícitamente todas las propiedades; las columnas no asignadas se incluirán como propiedades de evento.
• El JSON anidado se puede almacenar dentro de un valor de propiedad individual si es necesario (por ejemplo, un objeto JSON de elementos de línea), pero el nombre de la propiedad en sí proviene de una columna de nivel superior.

Klaviyo realiza el análisis del mejor tipo de esfuerzo para las propiedades de eventos y no proporciona una lógica de transformación por campo como parte de la configuración de la importación de eventos.

Casos de uso comunes

Los clientes suelen utilizar la importación de eventos del almacén de datos para lo siguiente:

1) Importación de eventos sin conexión o POS

Trae eventos en la tienda o fuera de ella (por ejemplo, compras en puntos de venta, devoluciones o citas) desde tu almacén para que se comporten como otros eventos y métricas de Klaviyo.

Ejemplos:

• In-Store Purchase eventos con totales de pedidos, ubicación de la tienda y tipo de método de pago
• Appointment Completed eventos con miembro del personal, tipo de servicio y duración

2) Interacciones de servicio y asistencia

Sincroniza eventos de asistencia y servicio como la creación de tickets, la resolución o las devoluciones para enriquecer los plazos de tus clientes y potenciar la mensajería en función del historial del servicio.

Ejemplos:

• Support Ticket Created y Support Ticket Resolved
• Order Returned con códigos de motivo y montos de reembolso

3) Eventos modelados o derivados

Convierte los comportamientos modelados en almacenes en eventos más fáciles de usar en Klaviyo.

Ejemplos:

• High Churn Risk eventos generados a partir de un modelo en tu almacén de datos
• Lifecycle Milestone Reached eventos cuando un cliente cambia de etapa en un modelo de ciclo de vida personalizado

Configura una sincronización de importación de eventos del almacén de datos

1) Conecta tus almacenes de datos

Si tu almacén ya está conectado, pasa al paso 2. De lo contrario:

1. En Klaviyo, ve a Advanced KDP > Administración de datos > Sincronización.
2. Haz clic en Crear sincronización si ya tienes sincronizaciones configuradas. Selecciona Importar datos desde tu almacén de datos y luego selecciona el conector de tu almacén.
3. Completa los pasos de preparación del almacén de datos en la guía de conexión correspondiente con enlace en Comprender la Importación desde almacén de datos en Klaviyo.
4. Haz clic en Conectar a y luego en el nombre del almacén. Ingresa los detalles de conexión obligatorios y luego haz clic en Siguiente.
5. Haz clic en Probar. Después de que la conexión se realice correctamente y Klaviyo pueda acceder a al menos 1 tabla o vista, haz clic en Siguiente.

Puedes crear varias conexiones de Importación desde almacén de datos y agregar tablas o vistas de origen a cada conexión.

Antes de crear la sincronización, decide qué eventos históricos incluir. fuentes:

• Apunta la importación de tu evento a una mesa o vista que ya incluya todos los eventos históricos relevantes, o
• Empieza con una tabla histórica dedicada y luego cambia a una vista respaldada por captura de datos de cambios para las actualizaciones continuas. Mantén las mismas columnas asignadas y aplica a las filas nuevas marcas de tiempo de detección de cambios posteriores al progreso guardado de la sincronización.

2) Crear una nueva sincronización de importación de eventos

Para una conexión nueva, continúa con la configuración que abriste arriba. Para una conexión existente, primero:

1. En Advanced KDP > Administración de datos > Sincronización, selecciona la conexión a tu almacén.
2. Haz clic en Añadir fuente.

En configuración de sincronización:

1. Ingresa un nombre para la sincronización y, opcionalmente, una descripción.
2. En Origen de datos, selecciona la tabla o vista que contiene los eventos que quieres importar.
3. En Tipos de objetos de datos, selecciona Eventos.

3) Elige la cadencia de sincronización

1. En Cadence, elige cómo ejecutar la sincronización:
   • Programar ejecución: elige el intervalo en Cada y configura la Fecha de inicio, la Hora de inicio y la Zona horaria. El intervalo predeterminado es de 1 hora.
   • Manual: guarda la sincronización sin una programación recurrente y ejecútala cuando sea necesario.
2. Haz clic en Siguiente para asignar campos.

4) Asignar campos obligatorios

A continuación, asignarás columnas de la tabla de tu almacén a los campos de eventos obligatorios de Klaviyo.

Completa estas asignaciones:

1. En Change detection, selecciona la columna de marca de tiempo de detección de cambios en New Row Detection. Usa una columna de origen diferente de la marca de tiempo del evento.
2. En Tipo de evento, elige una de estas opciones:
   • Mismo tipo de evento: selecciona una métrica de interfaz de programación de aplicaciones (API) existente para todas las filas.
   • Tipo de evento específico para cada fila: selecciona la columna que contiene el nombre de la métrica de cada fila. Usa esta opción si la métrica que necesitas no está en la lista de métricas existente de la interfaz de programación de aplicaciones (API).
3. En Marcas de tiempo de eventos, selecciona la columna que registra cuándo ocurrió el evento.
4. En propiedades del perfil, haz clic en Agregar mapeo y asigna al menos 1 identificador de perfil (p. ej., correo electrónico, número de teléfono, ID externo o ID de Klaviyo).

También puedes asignar campos recomendados:

• ID único
• Valor

Para mantener los metadatos de moneda (p. ej., USD), deja su columna sin asignar para que se convierta en una propiedad de evento. No hay una asignación dedicada para Moneda del valor.

Cualquier columna restante que no asignes explícitamente a estos campos principales se convertirá automáticamente en propiedades de evento.

La interfaz de usuario de configuración te impide asignar varias columnas al mismo campo de nivel superior y valida que todos los campos obligatorios estén presentes antes de permitirte guardar.

5) Guarda y revisa la sincronización

1. Revisa la configuración y luego haz clic en Listo para guardar la sincronización de importación de eventos.
2. En la página de conexión del almacén, haz clic en el nombre de sincronización. Si la configuración te regresó a la descripción general de Sincronizando, selecciona primero la conexión del almacén.
3. Si elegiste Manual, haz clic en Ejecutar sincronización para iniciar la importación. Las importaciones programadas se ejecutan según la cadencia que seleccionaste.
4. Revisa Historial de ejecución para ver el progreso y Registros para ver errores.

Cómo se comportan los eventos importados en Klaviyo

Una vez importada:

• Cada fila aparece como un evento de una métrica de API personalizada en Klaviyo.
• El nombre de la métrica que asignaste (o configuraste como una constante) determina el nombre del tipo de evento que ves en el producto (por ejemplo, Placed Order).
• Todos los identificadores de perfil se resuelven en perfiles existentes siempre que es posible; de lo contrario, Klaviyo crea nuevos perfiles utilizando los campos de identificador proporcionados, al igual que otras rutas de ingesta de eventos.

Puedes usar estos eventos para lo siguiente:

• Crea segmentos basados en lo que alguien ha hecho y filtra las propiedades de los eventos.
• Activar y filtrar flujos.
• Analiza el comportamiento en métricas e informes junto con eventos de otras fuentes.

Limitaciones y mejores prácticas

Ten en cuenta lo siguiente cuando utilices la importación de eventos del almacén de datos:

• Usa la importación de eventos para los datos de eventos. Para actualizar las propiedades del perfil, usa la importación de perfiles u otras rutas compatibles.
• La marca de tiempo de detección de cambios debe ser diferente de la marca de tiempo del evento. Usar la misma columna para ambos puede evitar que importes de forma segura eventos históricos después de tu primera sincronización.
• Para backfills históricos, usa la hora en que se cargó cada fila en el almacén de datos como su marca de tiempo de detección de cambios. Un job que crea una tabla histórica puede almacenar la marca de tiempo de ese job en las filas para mantener el intervalo reducido. No recalcules esta marca de tiempo cada vez que se consulta una vista y sigue las recomendaciones de volumen de filas que se indican a continuación.
• Usa un ID único y estable por evento cuando sea posible para mejorar la deduplicación y facilitar la depuración. Reimportar el mismo ID para el mismo perfil y la misma métrica se trata como un duplicado; no actualiza las propiedades del evento.
• Puedes mantener varios tipos de eventos (métricas) en la misma tabla. Las columnas no asignadas se incluyen como propiedades de eventos, así que usa vistas separadas si necesitas conjuntos de propiedades diferentes para distintas métricas.
• En el caso de objetos anidados complejos (por ejemplo, matrices de elementos de línea), te recomendamos aplanarlos en varias columnas cuando sea factible, especialmente para las propiedades que esperas utilizar en la segmentación o los flujos.
• Mantén las marcas de tiempo históricas de detección de cambios dentro de un rango reducido. Durante el backfill inicial, Klaviyo lee los datos en ventanas de 1 hora, empezando desde la marca de tiempo de detección de cambios más antigua. Un solo registro de 2023, cuando todos los demás son recientes, puede hacer que ese backfill sea más lento porque Klaviyo debe avanzar por las ventanas intermedias. Las ejecuciones posteriores se reanudan desde el progreso guardado en lugar de volver a empezar desde el registro más antiguo.
• No excedas aproximadamente 100 000 filas en una sola ventana de marca de tiempo de detección de cambios de 1 hora. Si demasiadas filas comparten el mismo periodo de 1 hora, es posible que se agote el tiempo de espera de la consulta de sincronización.

Mejora el rendimiento de las consultas en Snowflake

Se recomienda la configuración de la clave de agrupamiento de Snowflake

Para tablas grandes de Snowflake, una clave de clustering en la marca de tiempo de detección de cambios puede ayudar a que las consultas omitan micro-partitions innecesarias. Prueba consultas representativas antes de agregar una clave y compara el ahorro en consultas con los créditos de Snowflake usados para mantener el clustering:

ALTER TABLE your_schema.your_table CLUSTER BY (your_change_timestamp_column);