Collegare Klaviyo e Snowflake

Ai fini di questo articolo utilizziamo il termine "tabella", ma le viste, le viste materializzate e le tabelle sono tutti oggetti Snowflake validi che possono essere importati. Finché Klaviyo può eseguire SELECT col1 FROM nome_tabella sull'oggetto, sei libero di usare quello che preferisci. 

Le parole chiave "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", e "OPTIONAL" in questo documento devono essere interpretate come descritto nella RFC 2119.

Configurazione dell'amministratore di Snowflake

Questa sezione illustra i passi da seguire nel tuo ambiente Snowflake per consentire a Klaviyo di importare i tuoi dati. 

1. Genera una chiave privata eseguendo il seguente comando nel tuo terminale locale:

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

2. Genera una chiave pubblica che faccia riferimento alla chiave privata eseguendo il seguente comando nel tuo terminale:

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

3. Copia il file rsa_key.pub e incollalo nello script sottostante per sostituire il valore del segnaposto 'GENERATE_PUBLIC_KEY' per user_rsa_public_key. Lo script qui sotto funzionerà per gli utenti Mac, oppure, se preferisci, puoi aprire rsa_key.pub in un IDE e copiare l'intero contenuto del file. 

# Comando da terminale Mac per scrivere la chiave sul terminale e copiarla negli appunti
cat rsa_key.pub | tee /dev/tty | pbcopy

4. Esegui il seguente script nel tuo ambiente Snowflake per creare un utente di servizio da utilizzare per Klaviyo. Devi avere i privilegi di securityadmin e sysadmin per poter completare la configurazione che segue. Per verificare quali ruoli hai, esegui SHOW GRANTS TO USER <your_username> e assicurati di avere entrambi i ruoli elencati. Se hai bisogno di modificare il tuo ruolo, rivolgiti a un amministratore di sistema.
   1. Puoi aggiornare, aggiornare qualsiasi variabile impostata all'inizio dello script.
   2. In sintesi, potrai:
      1. Scegli un magazzino esistente o creane uno nuovo
      2. Scegli un database esistente o creane uno nuovo per contenere i nuovi schemi.
      3. Creare due nuovi schemi KLAVIYO_TMP e KLAVIYO_IMPORT_FROM_DWH
      4. Crea un nuovo criterio di rete e autorizza l'elenco di IP di Klaviyo
      5. Crea un utente e un ruolo per Klaviyo
   3. Questo script è idempotente (può essere tranquillamente eseguito più volte), ma non sovrascriverà gli oggetti esistenti con nomi in conflitto. 

BEGIN;

-- crea le variabili per utente / password / ruolo / magazzino / database. 
-- Cambia questi dati con quelli che preferisci.
SET role_name = 'KLAVIYO_DATA_TRANSFER_ROLE'; -- tutte le lettere devono essere maiuscole, ad esempio. 'KLAVIYO_DATA_TRANSFER_ROLE'
SET user_name = 'KLAVIYO_DATA_TRANSFER_USER'; -- tutte le lettere devono essere maiuscole, ad esempio. 'KLAVIYO_DATA_TRANSFER_USER'
SET nome_magazzino = 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'; -- tutte le lettere devono essere maiuscole, es. 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'
SET database_name = 'KLAVIYO_DATABASE'; -- tutte le lettere devono essere maiuscole, ad esempio. 'KLAVIYO_DATABASE'. Se questo database non esiste, ne verrà creato uno nuovo.
SET network_policy = 'KLAVIYO_DATA_TRANSFER_NETWORK_POLICY'; -- tutte le lettere devono essere maiuscole, es. 'KLAVIYO_NETWORK_POLICY'
SET network_rule = 'KLAVIYO_DATA_TRANSFER_NETWORK_RULE'; -- tutte le lettere devono essere maiuscole, es. 'KLAVIYO_NETWORK_RULE'
/* sostituisci GENERATE_PUBLIC_KEY qui sotto con la chiave pubblica generata */

-- NON MODIFICARE
SET schema_name_tmp = $database_name || '.KLAVIYO_TMP'; -- NON MODIFICARE
SET schema_name_import = $database_name || '. KLAVIYO_IMPORT_FROM_DWH'; -- NON CAMBIARE
SET full_network_rule_tmp = $schema_name_tmp || '.' || $network_rule; -- NON CAMBIARE
SET full_network_rule_import = $schema_name_import || '.' || $network_rule; -- NON CAMBIARE


-- cambia il ruolo in sysadmin per i passaggi magazzino/database
USE ROLE sysadmin;

-- crea un magazzino per il servizio di trasferimento dati
CREATE WAREHOUSE IF NOT EXISTS IDENTIFIER($warehouse_name)
 warehouse_size = xsmall
 warehouse_type = standard
 auto_suspend = 60
 auto_resume = true
 initially_suspended = true;

-- crea il database per il servizio di trasferimento dati
CREATE DATABASE IF NOT EXISTS IDENTIFIER($database_name);

-- crea gli schemi per il servizio di trasferimento dati
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name_tmp);
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name_import);

-- cambia il ruolo in securityadmin per i passaggi utente/ruolo
USE ROLE securityadmin;

-- crea la rete  regola e criterio per il database
GRANT USAGE ON DATABASE IDENTIFIER($nome_database) 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;

-- whitelist Klaviyo intervalli di ip, per lo schema KLAVIYO_TMP 
CREATE NETWORK RULE IF NOT EXISTS 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'
 )
 comment = 'Klaviyo IP Ranges as of April 2025';
CREATE NETWORK POLICY IF NOT EXISTS IDENTIFIER($network_policy)
 allowed_network_rule_list = ($full_network_rule_tmp);

-- whitelist Klaviyo intervalli di ip, per lo schema KLAVIYO_IMPORT_FROM_DWH 
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'
 )
 comment = 'Klaviyo IP Ranges as of April 2025';
CREATE NETWORK POLICY IF NOT EXISTS IDENTIFIER($network_policy)
allowed_network_rule_list = ($full_network_rule_import);


-- creare un ruolo per il servizio di trasferimento dati
CREARE RUOLO SE NON ESISTE IDENTIFICATORE($nome_ruolo);
GRANT RUOLO IDENTIFICATORE($nome_ruolo) A RUOLO sysadmin;

-- crea un utente per il servizio di trasferimento dati
CREATE USER IF NOT EXISTS IDENTIFIER($nome_utente)
 type = SERVICE
 network_policy = $network_policy
 default_role = $nome_ruolo
 default_warehouse = $nome_warehouse
 rsa_public_key = 'GENERATE_PUBLIC_KEY';
GRANT ROLE IDENTIFIER($nome_ruolo) TO USER IDENTIFIER($nome_utente);
ALTER USER IDENTIFIER($nome_utente) SET NETWORK_POLICY = $network_policy;

-- concedere l'accesso al ruolo di servizio al magazzino
GRANT USAGE
 ON WAREHOUSE IDENTIFIER($nome_magazzino)
 TO  ROLE IDENTIFIER($role_name);

-- concedere l'accesso al servizio del database
GRANT controlla, USAGE
 ON DATABASE IDENTIFIER($database_name)
 TO ROLE IDENTIFIER($role_name);

-- concedere i privilegi per KLAVIYO_TMP 
GRANT USAGE ON SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE IDENTIFIER($role_name);
GRANT controlla, USAGE, CREATE TABLE, CREATE VIEW, CREATE SEQUENCE, CREATE FUNCTION, CREATE PROCEDURE
 SU SCHEMA IDENTIFIER($schema_name_tmp)
 A ROLE IDENTIFIER($role_name);
GRANT ALL ON FUTURE TABLES IN SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE IDENTIFIER($role_name);

-- Concessione dei privilegi per KLAVIYO_IMPORT_FROM_DWH
GRANT USAGE ON SCHEMA IDENTIFIER($schema_name_import) TO ROLE IDENTIFIER($role_name);
GRANT SELECT
 ON FUTURE TABLES
 IN SCHEMA IDENTIFIER($schema_name_import)
 TO ROLE IDENTIFIER($role_name);

COMMIT;

Impostazione dei dati Snowflake

Sopra hai creato due nuovi schemi. 

• KLAVIYO_TMP sarà utilizzato esclusivamente da Klaviyo. NON devi modificare le tabelle create in questo schema. Klaviyo eliminerà queste tabelle quando non saranno più necessarie.
• KLAVIYO_IMPORT_FROM_DWH è il punto in cui devi importare le tue tabelle finali da Klaviyo. Durante il processo di creazione della sincronizzazione, verranno elencate tutte le tabelle di questo schema tra cui scegliere. Per questo motivo DEVI importare solo i tavoli finali che vuoi importare per evitare confusione durante la configurazione. 

Tutte le tabelle che intendi importare in Klaviyo devono soddisfare i seguenti criteri. 

Requisiti del timestamp 

1. Le tabelle DEVONO contenere un campo timestamp che indica quando la riga è stata creata o aggiornata. Spesso si tratta di inserted_at o updated_at. Questa impostazione viene effettuata per ogni tabella durante il processo di creazione della sincronizzazione.
   1. Il campo timestamp DEVE essere monotonicamente crescente (cioè deve essere sempre più grande o uguale, mai più piccolo).
   2. Dopo la creazione della sincronizzazione, NON DEVI impostare il valore del timestamp di una riga su un tempo passato, altrimenti Klaviyo potrebbe non rilevare quella riga.
   3. Il fuso orario di questo campo non è importante per Klaviyo, purché tu segua i requisiti sopra indicati.
   4. Klaviyo RACCOMANDA di impostare il campo timestamp con CURRENT_TIMESTAMP() o una funzione equivalente. Più righe possono avere lo stesso timestamp. Vedi l'esempio seguente. 

INSERT INTO table_name AS 

SELECT ... 

, CURRENT_TIMESTAMP() AS inserted_at

... 

2. I tuoi timestamp DEVONO essere in UTC o includere informazioni sul fuso orario. Se mancano le informazioni sul fuso orario, Klaviyo assumerà UTC. Per le proprietà personalizzate, questi timestamp rimangono in formato stringa, consentendoti di interpretarli nel fuso orario che preferisci.

Struttura della tabella 

3. Le tabelle DOVREBBERO essere trattate come di sola appendice (alias di solo inserimento)
   1. Se invece preferisci aggiornare, aggiornare le righe in posizione, DEVI aggiornare il campo timestamp in modo che Klaviyo possa identificare la modifica.
4. Le tabelle DEVONO essere ordinate in base alla colonna timestamp. Snowflake gestirà il clustering e il partizionamento in base all'ordine di inserimento. Questo aiuterà a ottimizzare le query di importazione di Klaviyo, mantenendo bassi i costi di calcolo in Snowflake.

Unicità e coerenza del profilo 

5. Devi assicurarti che ogni Proprietà del profilo sia importata da una sola fonte di dati (tabella). Klaviyo impedisce di selezionare la stessa proprietà da tabelle diverse durante la creazione della sincronizzazione, semplificando questo requisito.
6. Dovresti utilizzare gli stessi identificativi del profilo (e-mail, numero di telefono, ID esterno, ecc.) in tutte le tabelle di importazione, per ridurre al minimo il rischio di creare profili duplicati.
   1. Klaviyo creerà un nuovo profilo se l'identificativo del profilo fornito non corrisponde a un profilo esistente all'interno di Klaviyo.
   2. Esempio: Tabella1 (e-mail, fav_color) + Tabella2 (telefono, compleanno)
      1. Questo potrebbe creare due profili per la stessa persona se il profilo non esiste ancora. Se un profilo esiste, Klaviyo gestirà internamente la risoluzione del profilo e l'aggiornamento. 
   3. Un modo per evitare questo problema è quello di utilizzare un'unica tabella di importazione per tutti i tuoi profili. 

Prevenzione del loop circolare di import-export 

7. Dovresti gestire con attenzione gli scenari in cui vengono utilizzate sia le funzionalità di importazione che quelle di esportazione per evitare cicli circolari di importazione-esportazione. Assicurati che il tuo processo di esportazione non riporti i dati in una tabella a monte della tabella di importazione, poiché al momento Klaviyo non rileva questo scenario.
   1. Klaviyo non dispone ancora di una logica per rilevare questo scenario.
   2. Il risultato sarebbe qualcosa di simile a:
      1. Ad ogni ciclo di sincronizzazione dell'esportazione, Klaviyo esporterà tutto il tuo profilo
      2. Poi aggiungi tutti i profili esportati alla tabella di importazione attraverso una serie di trasformazioni.
      3. Ad ogni ciclo di sincronizzazione dell'importazione, Klaviyo leggerà tutti i profili presenti nella tabella di importazione, che alla fine verranno riesportati.
   3. Scenari in cui questo è probabilmente sicuro 
      1. se utilizzi la tabella di esportazione solo per limitare le righe aggiunte alla tabella di importazione
      2. Se verifichi che la tabella di esportazione non aggiunge righe alla tabella di importazione.
   4. Quali sono le conseguenze di un ciclo circolare di import-export?
      1. Questo comporta costi di calcolo inutili sia per te che per Klaviyo.