Connecter Klaviyo et Snowflake

Dans le cadre de cet article, nous utilisons le terme « table », mais les vues, les vues matérialisées et les tables sont toutes des objets Snowflake valides qui peuvent être importés. Tant que Klaviyo peut exécuter SELECT col1 FROM table_name sur l'objet, vous pouvez utiliser ce que vous préférez. 

Les mots-clés « DOIT », « NE DOIT PAS », « EXIGE », « NE DOIT PAS », « NE DOIT PAS », « NE DEVRAIT PAS », « RECOMMANDE », « PEUT » et « FACULTATIF » de ce document doivent être interprétés comme décrits dans la RFC 2119.

Configuration de l’Administrateur Snowflake

Cette section décrit les étapes que vous devez suivre dans votre environnement Snowflake pour permettre à Klaviyo d’importer vos données. 

1. Générez une clé privée en exécutant la commande suivante dans votre terminal local :

openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt

2. Générez une clé publique qui fait référence à la clé privée en exécutant la commande suivante dans votre terminal :

openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

3. Copiez le fichier rsa_key.pub et collez-le dans le script ci-dessous pour remplacer la valeur de remplissage « GENERATE_PUBLIC_KEY » pour user_rsa_public_key. Le script ci-dessous fonctionnera pour les utilisateurs de Mac, ou vous pouvez ouvrir rsa_key.pub dans un IDE et copier le contenu complet du fichier si vous le souhaitez. 

# Commande de terminal Mac pour écrire la clé sur votre terminal et la copier dans le presse-papiers rsa_key.pub | tee /dev/tty | pbcopy

4. Exécutez le script ci-dessous dans votre environnement Snowflake pour créer un utilisateur de service que Klaviyo pourra utiliser. Vous devez disposer des privilèges securityadmin et sysadmin pour effectuer la configuration ci-dessous. Pour vérifier le ou les rôles dont vous disposez, exécutez SHOW GRANTS TO USER <votre_nom_d’utilisateur> et assurez-vous que les deux rôles sont répertoriés.<your_username> Contactez un administrateur système si vous avez besoin de modifier votre rôle.
   1. N’hésitez pas à mettre à jour l’une des variables définies au début du script.
   2. En résumé, vous allez :
      1. Choisissez un entrepôt existant ou créez-en un nouveau
      2. Choisissez une base de données existante ou créez-en une nouvelle pour contenir les nouveaux schémas
      3. Créez deux nouveaux schémas : KLAVIYO_TMP et KLAVIYO_IMPORT_FROM_DWH.
      4. Créez une nouvelle politique de réseau et autorisez la liste des adresses IP Klaviyo.
      5. Créer un utilisateur et un rôle pour Klaviyo
   3. Ce script est idempotent (peut être exécuté en toute sécurité plusieurs fois), mais ne remplacera pas les objets existants dont les noms sont contradictoires. 

BEGIN ; — créez des variables pour utilisateur / mot de passe / rôle / entrepôt / base de données. 
— Choisissez ce que vous préférez.
SET role_name = 'KLAVIYO_DATA_TRANSFER_ROLE'; — toutes les lettres doivent être en majuscules, p. ex. 'KLAVIYO_DATA_TRANSFER_ROLE' SET user_name = 'KLAVIYO_DATA_TRANSFER_USER'; — toutes les lettres doivent être en majuscules, p. ex. 'KLAVIYO_DATA_TRANSFER_USER' SET nom_entrepôt = 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'; — toutes les lettres doivent être en majuscules, p. ex. 'KLAVIYO_DATA_TRANSFER_WAREHOUSE' SET database_name = 'KLAVIYO_DATABASE'; — toutes les lettres doivent être en majuscules, p. ex. « KLAVIYO_DATABASE ». Si cette base de données n’existe pas, une nouvelle base de données sera créée.
SET network_policy = 'KLAVIYO_DATA_TRANSFER_NETWORK_POLICY'; — toutes les lettres doivent être en majuscules, p. ex. 'KLAVIYO_NETWORK_POLICY' SET network_rule = 'KLAVIYO_DATA_TRANSFER_NETWORK_RULE'; — toutes les lettres doivent être en majuscules, p. ex. 'KLAVIYO_NETWORK_RULE' /* remplacez GENERATE_PUBLIC_KEY ci-dessous par la clé publique générée */ — NE MODIFIEZ PAS SET schema_name_tmp = $database_name || '.KLAVIYO_TMP'; — NE MODIFIEZ PAS SET schema_name_import = $database_name || '.KLAVIYO_IMPORT_FROM_DWH'; — NE MODIFIEZ PAS SET full_network_rule_tmp = $schema_name_tmp || '.' | $network_rule; — NE MODIFIEZ PAS SET full_network_rule_import = $schema_name_import || '.' | $network_rule; — NE PAS MODIFIER — changer le rôle en sysadmin pour les étapes entrepôt / base de données USE ROLE sysadmin ; — créer un entrepôt pour le service de transfert de données CRÉER UN ENTREPÔT SI N'EXISTE PAS IDENTIFIER($nom_entrepôt) taille_entrepôt = xsmall type_entrepôt = standard suspension_auto = 60 reprise_auto = vrai suspension initiale = vrai ; — créer une base de données pour le service de transfert de données CRÉER UNE BASE DE DONNÉES SI N'EXISTE PAS IDENTIFIER($nom_base_de_données); — créer des schémas pour le service de transfert de données CRÉER UN SCHÉMA SI N'EXISTE PAS IDENTIFIER($nom_schéma_tmp); — CRÉER UN SCHÉMA SI N'EXISTE PAS IDENTIFIANT($nom_nom_schéma_importation); passer le rôle à securityadmin pour les étapes utilisateur / rôle USE ROLE securityadmin ; — créer une règle et une politique réseau pour la base de données GRANT USAGE ON DATABASE IDENTIFIER($database_name) TO ROLE securityadmin ; GRANT USAGE, CREATE NETWORK RULE ON SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE securityadmin ; GRANT USAGE, CREATE NETWORK RULE ON SCHEMA IDENTIFIER($schema_name_import) TO ROLE securityadmin ; — liste blanche Klaviyo plages, pour le schéma KLAVIYO_TMP CRÉER UNE RÈGLE RÉSEAU SI ELLE N'EXISTE PAS IDENTIFIER($full_network_rule_tmp) type = IPV4 value_list = ( '184.72.183.187/32', 52.206.71.52/32', 3.227.146.32/32', '44.198.39.11/32', '35.172.58.121/32', '3.228.37.244/32', '54.88.219.8/32' '3.214.211.176/32' ) commentaire = 'Klaviyo IP Ranges as of April 2025'; CREATE NETWORK POLICY IF NOT EXISTS IDENTIFIER($network_policy) allow_network_rule_list = ($full_network_rule_tmp); — whitelist Klaviyo ip range, for KLAVIYO_IMPORT_FROM_DWH schema CREATE NETWORK RULE IF NOT EXISTS IDENTIFIER($full_network_rule_import) type = IPV4 value_list = ( '184.72.183.187/32', 52.206.71.52/32', 3.227.146.32/32', '44.198.39.11/32', '35.172.58.121/32', '3.228.37.244/32', '54.88.219.8/32' '3.214.211.176/32' ) commentaire = 'Klaviyo IP Ranges as of April 2025'; CREATE NETWORK POLICY IF NOT EXISTS IDENTIFIER($network_policy) allow_network_rule_list = ($full_network_rule_import); — create role for data transfer service CREATE ROLE IF NOT EXISTS IDENTIFIER($role_name); GRANT ROLE IDENTIFIER($role_name) TO ROLE sysadmin; — create a user for data transfer service CREATE USER IF NOT EXISTS IDENTIFIER($user_name) type = SERVICE network_policy = $network_policy default_role = $role_name_role_role_role = $role_name default_entrepôt_nom_de données rsa_public_key = 'GENERATE_PUBLIC_KEY'; GRANT ROLE IDENTIFIER($role_name) TO USER IDENTIFIER($user_name); ALTER USER IDENTIFIER($user_name) SET NETWORK_POLICY = $network_policy; — accorder l'accès du rôle de service à l'entrepôt ACCORDER L'UTILISATION SUR L'IDENTIFIANT D'ENTREPÔT($nom_d'entrepôt) TO ROLE IDENTIFIER($role_name); — accorder l'accès du service à la base de données GRANT MONITOR, UTILISATION SUR L'IDENTIFIANT DE BASE DE DONNÉES($nom_de_base_de_données) TO ROLE IDENTIFIER($nom_rôle); — Accorder des privilèges pour KLAVIYO_TMP GRANT SUR SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE IDENTIFIER($role_name); GRANT MONITOR, USAGE, CREATE TABLE, CREATE VIEW, CREATE SEQUENCE, CREATE FUNCTION, CREATE PROCEDURE ON SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE IDENTIFIER($role_name); GRANT ALL ON FUTURE TABLES IN SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE IDENTIFIER($role_name); — Accordez des privilèges pour KLAVIYO_IMPORT_FROM_DWH GRANT USAGE ON SCHEMA IDENTIFIER($schema_name_import) TO ROLE IDENTIFIER($role_name_NAME); GRANT IN FUTURE IDENTIFIER($schema_name_import) TO ROLE IDENTIFIER($role_name); COMMIT ;

Configuration des données Snowflake

Vous avez créé deux nouveaux schémas ci-dessus. 

• KLAVIYO_TMP sera utilisé exclusivement par Klaviyo. Vous NE DEVEZ PAS modifier les tables créées dans ce schéma. Klaviyo supprimera ces tables lorsqu’elles seront devenues inutiles.
• KLAVIYO_IMPORT_FROM_DWH est l’endroit où vous devez stocker vos tables finales pour que Klaviyo les importe. Lorsque vous passez par le processus de création de la synchronisation, toutes les tables de ce schéma sont répertoriées et vous pouvez faire votre choix. Par conséquent, vous NE DEVEZ stocker que les tables finales que vous souhaitez importer afin d'éviter toute confusion lors de la configuration. 

Tous les tableaux que vous prévoyez d’importer vers Klaviyo doivent répondre aux critères suivants. 

Exigences en matière d’horodatage 

1. Les tables DOIVENT contenir un champ d’horodatage qui indique la date de création ou de mise à jour de la ligne. Souvent, il s’agit de insert_at ou de update_at. Vous le définissez pour chaque tableau au cours du processus de création de la synchronisation.
   1. Le champ d’horodatage DOIT augmenter de manière monotone (c’est-à-dire qu’il doit toujours être plus grand ou rester le même, sans jamais être plus petit).
   2. Après la création de la synchronisation, vous NE DEVEZ PAS définir la valeur d’horodatage d’une ligne sur une heure antérieure, sous peine de voir Klaviyo ne pas reprendre cette ligne.
   3. Le fuseau horaire de ce champ particulier n’est pas important pour Klaviyo, à condition que vous respectiez les exigences ci-dessus
   4. Klaviyo RECOMMANDE de définir le champ timestamp avec CURRENT_TIMESTAMP() ou une fonction équivalente. Plusieurs lignes peuvent avoir le même horodatage. Consultez l’exemple ci-dessous. 

INSERT INTO nom_table AS SELECT ... , CURRENT_TIMESTAMP() AS insert_at ... 

2. Vos horodatages DOIVENT être au format UTC ou inclure des informations de fuseau horaire. Si des informations sur le fuseau horaire sont manquantes, Klaviyo utilisera UTC. Pour les propriétés personnalisées, ces horodatages restent au format chaîne, ce qui vous permet de les interpréter dans le fuseau horaire de votre choix.

Structure du tableau 

3. Les tableaux DOIVENT être traités comme des ajouts uniquement (c'est-à-dire des insertions uniquement).
   1. Si vous préférez mettre à jour les lignes en place, vous DEVEZ mettre à jour le champ d’horodatage afin que Klaviyo puisse identifier la modification.
4. Les tableaux DOIVENT être classés dans votre colonne d’horodatage. Snowflake s’occupera du regroupement et du partitionnement en fonction de l’ordre de vos insertions. Cela vous aidera à optimiser les requêtes d’importation de Klaviyo et à réduire vos coûts de calcul dans Snowflake

Uniformité et cohérence des profils 

5. Vous DEVEZ vous assurer que chaque propriété de profil est importée à partir d’une seule source de données (tableau). Klaviyo empêche de sélectionner la même propriété dans différentes tables lors de la création de la synchronisation, ce qui simplifie cette exigence.
6. Vous DEVEZ utiliser le ou les mêmes identifiants de profil (adresse e-mail, numéro de téléphone, identifiant externe, etc.) dans toutes vos tables d’importation, afin de réduire le risque de création de profils en double.
   1. Klaviyo créera de nouveaux profils si l’identifiant de profil que vous fournissez ne correspond pas à un profil existant dans Klaviyo.
   2. Exemple : Table1 (Email, fav_color) + Table2 (Phone, anniversaire)
      1. Vous pouvez ainsi créer 2 profils pour la même personne si le profil n’existe pas actuellement. S’il existe un profil, Klaviyo gère la résolution et les mises à jour en interne. 
   3. Pour éviter ce problème, vous pouvez utiliser une seule table d’importation pour tous vos profils. 

Prévention de boucle d'importation-exportation circulaire 

7. Vous DEVEZ gérer avec soin les scénarios dans lesquels les fonctionnalités d'importation et d'exportation sont utilisées pour éviter les boucles d'importation-exportation circulaires. Veillez à ce que votre processus d’exportation ne réinjecte pas de données dans une table située en amont de votre table d’importation, car Klaviyo ne détecte actuellement pas ce scénario.
   1. Klaviyo n’a pas encore de logique pour détecter ce scénario.
   2. Voici à quoi cela ressemblerait :
      1. À chaque cycle de synchronisation d’exportation, Klaviyo exportera tous vos profils
      2. Vous ajoutez ensuite tous vos profils exportés à votre tableau d’importation par le biais d’une série de transformations.
      3. À chaque cycle de synchronisation d’importation, Klaviyo lit tous les profils de votre tableau d’importation, qui seront ensuite réexportés
   3. Scénarios dans lesquels cette option est probablement sûre 
      1. si vous utilisez uniquement le tableau d’exportation pour restreindre les lignes ajoutées à votre tableau d’importation
      2. Si vous vérifiez que le tableau d’exportation n’ajoute pas de lignes à votre tableau d’importation.
   4. Quelles sont les conséquences d’une boucle d’import-export circulaire ?
      1. Cela entraînera des coûts de calcul inutiles pour vous et Klaviyo.