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. Le premier import lit l’historique disponible dans votre source. Les exécutions ultérieures reprennent à partir de la progression enregistrée grâce à l’ horodatage de détection des changements, de sorte que Klaviyo ne retraite pas l’intégralité de la table.
3. Chaque ligne est ensuite traitée comme suit :
   • Klaviyo détermine le nom de l’indicateur (type d’événement) à partir d’un indicateur d’API existant que vous sélectionnez ou de la valeur d’une colonne de nom d’indicateur désignée dans chaque ligne.
   • L’horodatage de l’événement, les identifiants de profil, ainsi que l’ID unique et la valeur facultatifs sont définis en fonction 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 comportant 3 tirets bas (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.

Vous pouvez planifier des importations récurrentes (p. ex., toutes les heures) ou choisir Manuel pour exécuter des importations lorsque nécessaire.

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.
• Préparez les identifiants du compte de service et les schémas requis pour votre entrepôt de données. Consultez les guides de connexion dans Comprendre l’importation depuis un entrepôt de données dans Klaviyo.
• 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 obligatoires pour 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 noms de colonnes deviennent des noms de propriétés de niveau supérieur, sauf s’ils contiennent 3 tirets de soulignement (___), qui créent des propriétés enfants imbriquées, comme décrit ci-dessus.
• 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 votre entrepôt est déjà connecté, passez à l’étape 2. Sinon :

1. Dans Klaviyo, accédez à Advanced KDP > Gestion des données > Synchronisation.
2. Cliquez sur Créer une synchronisation si vous avez déjà configuré des synchronisations. Sélectionnez Importer des données depuis votre entrepôt de données, puis sélectionnez le connecteur de votre entrepôt.
3. Terminez les étapes de préparation de l’entrepôt dans le guide de connexion applicable accessible depuis Comprendre l’importation depuis un entrepôt de données dans Klaviyo.
4. Cliquez sur Se connecter à, puis sur le nom de votre entrepôt. Saisissez les informations de connexion requises, puis cliquez sur Suivant.
5. Cliquez sur Test. Une fois la connexion réussie, et lorsque Klaviyo peut accéder à au moins 1 table ou vue, cliquez sur Suivant.

Vous pouvez créer plusieurs connexions d’importation depuis un entrepôt de données et ajouter des tables sources ou des vues à chaque connexion.

Avant de créer la synchronisation, décidez quels événements historiques inclure. Vous avez le choix entre :

• Dirigez votre importation d’événements vers une table ou une vue qui comprend déjà tous les événements historiques pertinents, ou
• Commencez avec une table historique dédiée, puis passez ultérieurement à une vue adossée à la capture des changements de données (CDC) pour les mises à jour continues. Conservez les mêmes colonnes mappées et attribuez aux nouvelles lignes des horodatages de détection de modification ultérieurs à la progression enregistrée de la synchronisation.

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

Pour une nouvelle connexion, continuez dans la configuration que vous avez ouverte ci-dessus. Pour une connexion existante, commencez par :

1. Dans Advanced KDP > Gestion des données > Synchronisation, sélectionnez votre connexion à l’entrepôt.
2. Cliquez sur Ajouter une source.

Dans la configuration de la synchronisation :

1. Saisissez un nom pour la synchronisation et, si vous le souhaitez, une description.
2. Sous Source de données, sélectionnez la table ou la vue qui contient les événements que vous souhaitez importer.
3. Sous Types d’objets de données, sélectionnez Événements.

3) Choisissez la fréquence de synchronisation

1. Sous Cadence, choisissez comment exécuter la synchronisation :
   • Planifier l’exécution: choisissez l’intervalle sous Tous les et définissez la Date de début, l’Heure de début et le Fuseau horaire. L’intervalle par défaut est de 1 heure.
   • Manuel: enregistrez la synchronisation sans planning récurrent et exécutez-la lorsque nécessaire.
2. Cliquez sur Suivant pour mapper les champs.

4) Associer les champs requis

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

Terminez ces mappages :

1. Sous Détection des modifications, sélectionnez votre colonne d’horodatage de détection des modifications dans Détection de nouvelle ligne. Utilisez une autre colonne source que l’horodatage de l’événement.
2. Sous Type d’événement, choisissez l’une de ces options :
   • Même type d’événement: sélectionnez un indicateur API existant pour toutes les lignes.
   • Type d’évènement spécifique pour chaque ligne: sélectionnez la colonne contenant le nom de l’indicateur de chaque ligne. Utilisez cette option si l’indicateur dont vous avez besoin ne figure pas dans la liste d’indicateurs API existante.
3. Sous Horodatages des événements, sélectionnez la colonne qui enregistre le moment où l’événement s’est produit.
4. Sous propriétés de profil, cliquez sur Ajouter un mappage et mappez au moins 1 identifiant de profil (par exemple, e-mail, numéro de téléphone, ID externe ou ID Klaviyo).

Vous pouvez également mapper les champs recommandés :

• Identifiant unique
• Valeur

Pour conserver les métadonnées de devise (par exemple, USD), laissez sa colonne non associée afin qu’elle devienne une propriété d’événement. Il n’existe aucun mappage dédié pour la Devise de la 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.

5) Enregistrez et vérifiez la synchronisation

1. Vérifiez vos paramètres, puis cliquez sur Terminé pour enregistrer la synchronisation d’importation d’événements.
2. Sur la page de connexion de l’entrepôt, cliquez sur le nom de la synchronisation. Si la configuration vous a ramené vers l’aperçu Synchronisation, sélectionnez d’abord la connexion de l’entrepôt.
3. Si vous avez choisi Manuel, cliquez sur Lancer la synchronisation pour démarrer l’importation. Les importations planifiées s’exécutent selon la cadence que vous avez sélectionnée.
4. Vérifiez Historique des exécutions pour suivre la progression et Journaux pour les erreurs.

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 :

• Utilisez l’importation d’événements pour les données d’événements. Pour mettre à jour les propriétés de profil, utilisez l’importation de profils ou d’autres parcours 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 les remplissages historiques, utilisez l’heure à laquelle chaque ligne a été chargée dans l’entrepôt de données comme horodatage de détection des modifications. Une tâche qui crée une table historique peut stocker l’horodatage de cette tâche dans les lignes afin de réduire la plage. Ne recalculez pas cet horodatage à chaque fois qu’une vue est interrogée, et suivez les recommandations ci-dessous concernant le volume de lignes.
• Utilisez, si possible, un ID unique stable par événement afin d’améliorer la déduplication et de faciliter le débogage. La réimportation du même ID pour le même profil et le même indicateur est considérée comme un doublon ; elle ne met pas à jour les propriétés de l’événement.
• Vous pouvez conserver plusieurs types d’événements (indicateurs) dans le même tableau. Les colonnes non mappées sont incluses en tant que propriétés d’événements ; utilisez donc des vues distinctes si vous avez besoin de différents ensembles de propriétés pour différents indicateurs.
• 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.
• Maintenez les horodatages historiques de détection des modifications dans une plage réduite. Lors du remplissage initial, Klaviyo lit les données dans des fenêtres d’une heure à partir du plus ancien horodatage de détection des modifications. Un seul enregistrement de 2023, lorsque tous les autres sont récents, peut ralentir ce remplissage, car Klaviyo doit avancer à travers les fenêtres intermédiaires. Les exécutions suivantes reprennent à partir de la progression enregistrée, au lieu de recommencer à partir du plus ancien enregistrement.
• 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.

Améliorer les performances des requêtes Snowflake

Configuration recommandée de la clé de clustering Snowflake

Pour les grandes tables Snowflake, une clé de clustering sur l’horodatage de détection des modifications peut aider les requêtes à ignorer des micro-partitions inutiles. Testez des requêtes représentatives avant d’ajouter une clé, et évaluez les économies de requêtes par rapport aux crédits Snowflake utilisés pour maintenir le clustering :

ALTER TABLE your_schema.your_table CLUSTER BY (your_change_timestamp_column);