Comprendre l’importation d’événements d’entrepôt de données dans Klaviyo

Objectif de cet article

Apprenez à utiliser l’ importation d’événements d’entrepôt de données pour synchroniser les données d’événements de votre entrepôt dans Klaviyo, afin d’alimenter les segments, les flux et le reporting avec des comportements qui proviennent d’intégrations autres que les intégrations natives de Klaviyo (par exemple, les systèmes de point de vente, les plateformes d’assistance ou les applications personnalisées).

Définition importation d’événements d’entrepôt de données

L’importation d’événements d’entrepôt de données permet à Klaviyo de se connecter directement à votre entrepôt de données et de configurer les synchronisations d’importation à partir de tables ou de vues d’entrepôt qui contiennent des données d’événements.

Chaque ligne de votre tableau source est traitée comme un seul événement dans Klaviyo :

• Les horodatages, le nom de l’indicateur et les identifiants de la ligne définissent ce qui s’est passé, quand et pour qui.
• Les colonnes supplémentaires deviennent des propriétés d’événement que vous pouvez utiliser dans la segmentation, les flux et les analyses.

L’importation d’événements repose sur la même infrastructure d’importation depuis un entrepôt de données que l’importation de profils, mais elle cible le pipeline d’ingestion d’événements de Klaviyo plutôt que les profils.

Comment fonctionne l’importation d’événements d’entrepôt de données ?

Après avoir connecté Klaviyo à votre entrepôt et configuré une synchronisation d’événements :

1. Klaviyo interroge votre entrepôt pour la table ou la vue configurée.
2. À chaque exécution, Klaviyo ne lit que les lignes dont l’ horodatage de détection des modifications est plus récent que la dernière synchronisation réussie. Cela permet des importations incrémentielles sans retraiter l’ensemble du tableau.
3. Chaque ligne est ensuite traitée comme suit :
   • Klaviyo détermine le nom de l’indicateur (type d’événement) en fonction des options sélectionnées lors de la configuration de la synchronisation : un indicateur unique ou dynamiquement en fonction de la valeur d’une colonne de nom d’indicateur désignée dans le tableau source.
   • L’horodatage des événements, les identifiants de profil, ainsi que l’ identifiant unique, la valeur et la devise de la valeur facultatifs sont définis sur la base des mappages de champs configurés lors de la configuration de la synchronisation.
   • Toutes les colonnes restantes sont ingérées en tant que propriétés d’événement, en utilisant les noms de colonne comme noms de propriété. Les noms de colonne avec trois traits de soulignement (p. ex., parent___child1, parent___child2) peuvent être utilisés pour créer une propriété d’événement (parent) avec des propriétés enfants.
4. Klaviyo charge les événements résultants dans votre compte, où ils se comportent comme d’autres indicateurs API personnalisés dans la segmentation, les flux et les analyses.

Les importations s’exécutent à une cadence récurrente (par exemple, toutes les heures), de sorte que les nouvelles lignes ou les lignes mises à jour dans votre entrepôt sont régulièrement traduites en événements dans Klaviyo.

Avant de commencer

Assurez-vous que les conditions suivantes sont remplies avant de créer une synchronisation d’importation d’événements :

• Votre compte a accès à Advanced KDP et à l’ importation depuis un entrepôt de données.
• Vous avez créé et validé une connexion à un entrepôt de données dans Klaviyo. Pour plus d’informations sur le compte de service et les schémas requis, consultez les articles du centre d’assistance de votre entrepôt de données.
• Votre tableau ou vue source contient les colonnes requises ci-dessous.
• Vous disposez de privilèges suffisants dans votre entrepôt pour exposer les tables/vues nécessaires à l’utilisateur du service Klaviyo.

Structure du tableau source pour les événements

Pour que vos données d’événement puissent être importées correctement, votre table ou vue source doit respecter les champs et la structure requis par Klaviyo.

Champs obligatoires

Les colonnes suivantes sont requises dans la V1 de l’importation d’événements d’entrepôt de données :

Champs facultatifs

Ces champs sont recommandés le cas échéant, mais ne sont pas strictement obligatoires :

Propriétés de l’événement

Toutes les autres colonnes de votre tableau sont traitées comme des propriétés d’événement:

• Les colonnes sont importées en tant que propriétés aplaties, le nom de la colonne étant utilisé directement comme nom de la propriété dans Klaviyo.
• Vous n’avez pas besoin de mapper explicitement toutes les propriétés. Les colonnes non mappées seront incluses en tant que propriétés d’événement.
• Les JSON imbriqués peuvent être stockés dans une valeur de propriété individuelle si nécessaire (par exemple, un objet JSON d’éléments de ligne), mais le nom de la propriété lui- même provient d’une colonne de niveau supérieur.

Klaviyo effectue une analyse de type optimale pour les propriétés d’événement et ne fournit pas de logique de transformation par champ dans le cadre de la configuration de l’importation d’événements.

Cas d’utilisation courants

Les clients utilisent généralement l’importation d’événements d’entrepôt de données pour :

1) Importation d’événements hors ligne ou en point de vente

Importez des événements en magasin ou hors ligne (par exemple, achats en point de vente, retours ou rendez-vous) depuis votre entrepôt afin qu’ils se comportent comme d’autres événements et indicateurs Klaviyo.

Exemples :

• In-Store Purchase événements avec les totaux de commande, l’emplacement du magasin et le type de paiement
• Appointment Completed événements avec le membre du personnel, le type de service et la durée

2) Interactions avec le service client et l’assistance

Synchronisez les événements d’assistance et de service client tels que la création de tickets, la résolution ou les retours pour enrichir votre chronologie client et alimenter vos messages en fonction de l’historique du service.

Exemples :

• Support Ticket Created et Support Ticket Resolved
• Order Returned avec des codes de motif et des montants de remboursement

3) Événements modélisés ou dérivés

Convertissez les comportements modélisés par l’entrepôt en événements plus faciles à utiliser dans Klaviyo.

Exemples :

• High Churn Risk événements générés à partir d’un modèle dans votre entrepôt de données
• Lifecycle Milestone Reached événements lorsqu’un client change d’étape dans un modèle de cycle de vie personnalisé

Configurez une synchronisation d’importation d’événements d’entrepôt de données

1) Connecter votre entrepôt de données

Si vous n’avez pas encore connecté votre entrepôt :

1. Dans Klaviyo, accédez à Advanced KDP > Gestion des données > Synchronisation.
2. Cliquez sur Ajouter un entrepôt de données et sélectionnez le connecteur de votre entrepôt.
3. Suivez les étapes de connexion à votre plateforme en suivant le guide de connexion correspondant, lié à l’article de synthèse de l’importation depuis un entrepôt de données.

Klaviyo prend en charge une connexion active à un entrepôt de données par compte.

2) Créer une nouvelle synchronisation d’importation d’événements

Une fois votre entrepôt connecté :

1. Dans Advanced KDP > Gestion des données > Synchronisation, sélectionnez votre connexion à l’entrepôt.
2. Choisissez Importer des données (si vous configurez des importations pour la première fois) ou cliquez sur Créer une synchronisation / Ajouter une synchronisation pour une connexion existante.
3. Lorsque le type de données vous est demandé, sélectionnez Événements (au lieu de Profils).
4. Choisissez le tableau ou la vue de votre entrepôt qui contient les événements que vous souhaitez importer.

3) Mapper les champs obligatoires

Ensuite, vous mappez les colonnes de votre tableau d’entrepôt aux champs d’événement obligatoires de Klaviyo.

La configuration de l’importation d’événements exige que vous fournissiez des mappages pour :

• Horodatage de l’événement
• Nom de l’indicateur (une constante que vous sélectionnez dans la configuration ou une colonne qui contient le nom de l’indicateur par ligne)
• Identifiant de profil (au moins un)
• Modifier l’horodatage de détection

Vous pouvez également mapper les champs recommandés :

• Identifiant unique
• Valeur
• Devise de valeur

Les colonnes restantes que vous ne mappez pas explicitement à ces champs principaux deviennent automatiquement des propriétés d’événement.

L’interface utilisateur de configuration vous empêche de mapper plusieurs colonnes au même champ de niveau supérieur et vérifie que tous les champs obligatoires sont présents avant de vous permettre d’enregistrer.

4) Choisissez la cadence de synchronisation et l’étendue historique

Lorsque vous enregistrez l’importation de votre événement :

• Klaviyo planifie des synchronisations récurrentes à une cadence régulière (généralement toutes les heures).
• À chaque exécution, seules les lignes dont l’ horodatage de détection des modifications est plus récent que la dernière exécution réussie sont traitées, ce qui garantit que les importations sont incrémentielles.

Pour l’historique de remplissage, vous pouvez :

• Dirigez votre importation d’événements vers une table ou une vue qui comprend déjà tous les événements historiques pertinents, ou
• Commencez par un tableau historique dédié et passez ensuite à une vue basée sur la collecte de données pour les mises à jour en cours.

Comportement des événements importés dans Klaviyo

Une fois importé :

• Chaque ligne apparaît comme un événement d’un indicateur API personnalisé dans Klaviyo.
• Le nom de l’indicateur que vous avez mappé (ou configuré comme une constante) détermine le nom du type d’événement que vous voyez dans le produit (par exemple, Placed Order).
• Dans la mesure du possible, tous les identifiants de profil sont résolus en profils existants. Dans le cas contraire, Klaviyo crée de nouveaux profils à l’aide des champs d’identification fournis, comme pour d’autres chemins d’ingestion d’événements.

Vous pouvez utiliser ces événements pour :

• Créez des segments en fonction de ce que quelqu’un a fait et filtrez sur les propriétés d’événement.
• Déclenchez et filtrez les flux.
• Analysez le comportement dans les indicateurs et les rapports en plus des événements provenant d’autres sources.

Limites et bonnes pratiques

Gardez les points suivants à l’esprit lorsque vous utilisez l’importation d’événements d’entrepôt de données :

• La V1 de l’importation d’événements se concentre uniquement sur les données d’événements. Les propriétés du profil doivent être mises à jour via l’importation de profils ou d’autres chemins pris en charge.
• L’ horodatage de détection des modifications doit être différent de l’horodatage de l’événement. L’utilisation de la même colonne pour les deux peut vous empêcher d’importer en toute sécurité des événements historiques après votre première synchronisation.
• Pour une vitesse optimale, définissez le champ de détection des modifications sur l’horodatage de la création du nouveau tableau. Les enregistrements sont regroupés par lots dans des cycles de synchronisation utilisant cette valeur, de sorte que le temps d’importation des enregistrements historiques peut être réduit si tous les enregistrements historiques ont des horodatages de détection des changements dans une plage étroite (par exemple, l’horodatage d’une tâche qui crée le nouveau tableau).
• Utilisez un identifiant unique stable par événement lorsque cela est possible pour améliorer la déduplication et faciliter le débogage en aval.
• Si votre tableau contient plusieurs types d’événements (indicateurs) avec différents ensembles de colonnes, il est généralement acceptable de les conserver ensemble : les colonnes qui sont NULL pour des lignes particulières sont simplement ignorées pour ces événements dans Klaviyo.
• Pour les objets imbriqués complexes (par exemple, des tableaux d’éléments linéaires), nous vous recommandons de les aplatir en plusieurs colonnes si possible, en particulier pour les propriétés que vous prévoyez d’utiliser dans la segmentation ou les flux.

```

• Conservez l’horodatage de détection des modifications regroupé à proximité de la date du jour. Klaviyo lit les données dans des fenêtres d’une heure, en itérant vers l’avant à partir de l’horodatage de détection des modifications le plus ancien de votre tableau. Si une ligne a un horodatage de détection des changements bien antérieur (par exemple, un seul enregistrement de 2023 lorsque tous les autres sont récents), Klaviyo analyse toutes les fenêtres d’une heure à partir de cette date à chaque cycle de synchronisation, ce qui ralentit la synchronisation de l’historique de remplissage.
• Ne dépassez pas environ 100 000 lignes dans une seule fenêtre d’horodatage de détection des changements d’une heure. Si un trop grand nombre de lignes partagent la même fenêtre d’une heure, le délai de la requête de synchronisation peut expirer.

Configuration recommandée de la clé de clustering Snowflake

Pour les tables Snowflake, le regroupement dans la colonne d’horodatage de détection des modifications permet à Klaviyo d’ignorer les micro-partitions inutiles, ce qui réduit le temps de synchronisation et les coûts de calcul de Snowflake :

ALTER TABLE your_schema.your_table CLUSTER BY (your_change_timestamp_column);