OneTrace.pro Centro assistenza

Importazione di file e sorgenti di dati

Se i clienti sono già presenti in un altro sistema (CRM, gestionale, foglio di calcolo), non è necessario aspettare che arrivino sul sito: basta caricare un file. Il caricamento una tantum di profili da CSV o Excel si fa con l'importazione, mentre il caricamento periodico di profili ed eventi da un file tramite URL, da S3, da un foglio Google o dal Suo data warehouse si fa con le sorgenti di dati.

Entrambi gli strumenti sono disponibili per «Proprietario», «Amministratore» e «Manager».

Importazione di profili da CSV ed Excel

Apra Dati → Importazione profili nel menu oppure faccia clic su Importazione profili nell'intestazione della pagina Profili.

Requisiti del file

  • CSV o Excel (.xlsx, .xls — il primo foglio) con le intestazioni delle colonne nella prima riga.
  • Separatore: virgola, punto e virgola o tabulazione, rilevato automaticamente.
  • Dimensione: CSV fino a 20 MB, Excel fino a 10 MB.
  • Almeno una colonna con un identificatore: id del cliente nel Suo sistema, email, telefono.
  • In Excel le celle con formato data vengono caricate come 2026-10-28 18:42:00 e le formule con il loro valore. I file di Excel 95 e quelli protetti da password non sono adatti: li salvi come .xlsx o CSV.

Esempio:

email;phone;first_name;city;customer_id;bonus
[email protected];+39 333 123 4567;Anna;Milano;1001;350

Come caricarlo

  1. Faccia clic su Scegli un file e selezioni il file.
  2. Nella tabella compaiono le colonne del file, alcuni valori di esempio e il campo Destinazione. Per ogni colonna indichi:
    • Identificatore: User ID, Email, Telefono o ID anonimo: in base a questo valore il profilo viene trovato o creato. Ogni tipo può essere scelto una sola volta.
    • Attributo: una proprietà del profilo; accanto inserisca la chiave in caratteri latini, ad esempio city o bonus_balance.
    • Salta: la colonna non viene caricata.
  3. Faccia clic su Avvia importazione.

OneTrace.pro propone automaticamente la destinazione in base alle intestazioni: email diventa email, phone e mobile diventano telefono, customer_id e user_id diventano User ID. Le altre intestazioni diventano chiavi di attributo in minuscolo con trattini bassi: ad esempio «Città» diventa citta e «Data di nascita» diventa data_di_nascita. Per ottenere direttamente le chiavi abituali, chiami le colonne first_name, last_name, city, country. Verifichi i suggerimenti prima dell'avvio.

Importazione dei profili: associazione delle colonne del file

Avanzamento dell'importazione

L'importazione avviene in background: la pagina mostra la barra di avanzamento, lo stato e il contatore «elaborate N di M, errori: K». È possibile chiudere la pagina: l'importazione continua. Le righe con errori sono elencate con il loro numero. Al termine, il pulsante Apri profili porta all'elenco dei profili.

A destra, nel blocco Cronologia, si trovano le ultime 20 importazioni: file, chi l'ha caricato e quando, stato («Caricato», «In coda», «In elaborazione», «Completato», «Non riuscito») ed esito.

Pagina di importazione con la cronologia dei caricamenti

Come vengono elaborate le righe

  • Se esiste già un profilo con quell'identificatore, viene aggiornato: i nuovi attributi vengono aggiunti, quelli coincidenti sovrascritti. Se in una riga compaiono identificatori di due profili diversi, i profili vengono uniti: vedi Profili.
  • Le celle vuote vengono ignorate e non cancellano i valori già noti.
  • I numeri e true/false vengono salvati come numeri e valori booleani.
  • Email e telefono del file diventano sia identificatori sia attributi del profilo.
  • Dal telefono vengono rimossi spazi, parentesi e trattini. Lo indichi con il prefisso internazionale: +39 333 123 4567. Un numero senza prefisso internazionale verrà salvato con un prefisso errato.
  • Una riga priva di qualsiasi identificatore valido viene saltata con un errore.

L'importazione crea per ogni riga un evento $identify, quindi le modifiche agli attributi possono avviare i percorsi con trigger sulla modifica di un attributo. Se non lo desidera, metta in pausa questi percorsi durante l'importazione.

Sorgenti di dati

Una sorgente è un'importazione periodica pianificata. È adatta quando il CRM o il magazzino pubblica ogni notte un'esportazione aggiornata: OneTrace.pro la preleva da solo e aggiorna i profili o aggiunge eventi.

Preparazione

Prima crei una connessione nella sezione Integrazioni (serve il ruolo «Amministratore» o «Proprietario»):

  • File tramite URL: un file a un indirizzo HTTP(S). Se il file è protetto, indichi l'intestazione di autorizzazione, ad esempio Bearer e il token.
  • File da S3: bucket AWS, Yandex Object Storage, MinIO e altri storage compatibili.
  • Foglio Google: tramite la chiave di un account di servizio Google. Conceda a questo account l'accesso in lettura al foglio.
  • PostgreSQL, ClickHouse, BigQuery o Snowflake: una tabella o una query nel Suo data warehouse, vedi Data warehouse.

Formati di file: CSV, JSON (array di oggetti, fino a 50 MB) e JSON Lines.

Come creare una sorgente

  1. Apra Dati → Sorgenti di dati e faccia clic su Nuova sorgente.
  2. Inserisca il Nome e scelga la Connessione.
  3. Compili le impostazioni della connessione: URL del file e Formato, Percorso del file nel bucket oppure ID del foglio di calcolo e Intervallo (ad esempio Foglio1!A:F).
  4. Faccia clic su Carica colonne: OneTrace.pro leggerà le prime righe.
  5. Nel campo Importa come scelga Profili (ogni riga aggiorna gli attributi) o Eventi (ogni riga è un evento).
  6. Scelga la Pianificazione: da ogni 15 minuti a una volta al giorno.
  7. Nella tabella Colonne indichi la destinazione di ogni colonna, come per l'importazione CSV.
  8. Faccia clic su Salva.

Impostazioni della sorgente di dati con l'associazione delle colonne

Per gli eventi, la tabella delle colonne offre anche Nome dell'evento, Proprietà dell'evento e Ora dell'evento. La colonna con l'ora è obbligatoria. Il nome dell'evento può essere unico per tutte le righe, nel campo Nome dell'evento (ad esempio order_completed), oppure si può scegliere la colonna in cui è riportato.

Per gli scontrini dei negozi c'è il modello Scontrini dei negozi con un file di esempio: compila l'evento di acquisto, la proprietà di acquisto in negozio e i suggerimenti per le colonne (telefono, carta fedeltà, negozio, numero dello scontrino, importo e prodotti). Vedi Negozi e vendite offline.

Funzionamento della sorgente

La scheda della sorgente mostra lo stato («Attiva», «In pausa», «Errore»), la pianificazione, l'ora dell'ultima esecuzione e l'esito: righe totali, accettate, saltate, con errori.

  • Esegui ora: esecuzione straordinaria. Riattiva anche la sorgente dalla pausa o dall'errore.
  • Metti in pausa / Riprendi: ferma e riprende le esecuzioni pianificate.
  • Cronologia: elenco delle esecuzioni con avvio, modalità di avvio («Pianificata» o «Manuale»), stato e primi errori di riga con il numero.

Sorgenti di dati: schede con stato ed esito delle esecuzioni

Da sapere

  • Se il file non è cambiato dall'ultima volta, l'esecuzione termina con lo stato «Nessuna modifica» e le righe non vengono lette.
  • La ripetizione della stessa riga entro 24 ore non crea duplicati.
  • Per gli eventi viene memorizzata l'ora dell'ultimo evento caricato: le esecuzioni successive saltano le righe non più recenti. Per questo un file con la cronologia può essere semplicemente esteso in coda.
  • Una sorgente in errore viene ritentata secondo la pianificazione; il testo dell'errore è visibile nella scheda.
  • Gli eventi caricati rientrano nella quota mensile del piano.
  • Eliminando la sorgente, i dati già caricati restano.

Data warehouse

Se profili e ordini sono già raccolti nel Suo data warehouse (PostgreSQL, ClickHouse, BigQuery o Snowflake), la sorgente li legge direttamente da lì. Ogni esecuzione preleva solo le righe modificate dall'ultima volta, quindi anche una tabella grande non va esportata in un file. Le modifiche arrivano nei profili e negli eventi, che avviano i percorsi e aggiornano i segmenti. La direzione opposta è l'esportazione nei data warehouse.

La lettura dai data warehouse è disponibile con il piano «Enterprise», vedi Piani.

Connessione

Crei la connessione nella sezione Integrazioni, nel gruppo Sorgenti di dati. I campi sono gli stessi dell'esportazione in questo data warehouse, ma conviene creare un utente separato di sola lettura:

  • PostgreSQL: host, porta, database, utente con il permesso SELECT sulle tabelle necessarie.
  • ClickHouse: indirizzo dell'interfaccia HTTP, utente con il permesso di lettura.
  • BigQuery: chiave di un account di servizio con i ruoli BigQuery Data Viewer e BigQuery Job User, progetto e posizione dei dati.
  • Snowflake: account, utente con una coppia di chiavi, ruolo con il permesso SELECT e warehouse di calcolo. Per la lettura il bucket S3 non serve.

Il data warehouse deve essere raggiungibile da internet: OneTrace.pro non apre gli indirizzi delle reti interne.

Impostazioni della sorgente

Crei una sorgente come descritto sopra e scelga la connessione al data warehouse. Le sue impostazioni:

  • Cosa leggere: Tabella (ad esempio public.customers o shop_dwh.customers) oppure Query personalizzata, cioè SELECT o WITH in un solo comando senza ;. OneTrace.pro aggiunge alla query una condizione, l'ordinamento e un limite di righe, quindi tramite la query non è possibile modificare i dati.
  • Colonna del cursore: l'ora di modifica della riga, ad esempio updated_at. Ogni esecuzione legge le righe in cui quest'ora è successiva a quella dell'esecuzione precedente. Le righe senza quest'ora non vengono lette.
  • Chiave di riga: una colonna univoca, ad esempio id o customer_id. Serve a distinguere le righe con la stessa ora di modifica.
  • Colonna del flag di eliminazione: facoltativa, ad esempio is_deleted. Vedi Eliminazione.

Sorgente da un data warehouse BigQuery: tabella, cursore, chiave di riga e colonne

Il resto è come per un file: Carica colonne, destinazione delle colonne, profili o eventi, pianificazione.

Come vengono lette le modifiche

  • La prima esecuzione legge l'intera tabella, le successive solo le righe modificate dopo l'ultima letta.
  • Un'esecuzione legge al massimo 1 milione di righe. Se le righe sono di più, l'esecuzione successiva parte subito, senza aspettare la pianificazione: così il primo caricamento di una tabella grande procede con più esecuzioni consecutive.
  • Se un'esecuzione si interrompe, le stesse righe vengono rilette: i profili vengono semplicemente aggiornati di nuovo e gli eventi ripetuti non vengono duplicati.
  • Se cambia la tabella, la query, la colonna del cursore o la chiave, la lettura riparte dall'inizio.
  • La colonna con l'ora di modifica deve essere aggiornata dal Suo data warehouse: OneTrace.pro non rilegge una riga la cui ora non è cambiata.
  • La query viene eseguita in sola lettura e con un limite di tempo: 10 minuti in PostgreSQL, ClickHouse e Snowflake, 15 minuti in BigQuery.

Eliminazione

Se in una riga di una sorgente di profili la Colonna del flag di eliminazione contiene true o 1, OneTrace.pro elimina il profilo con gli identificatori di quella riga, come per una richiesta GDPR: insieme alla cronologia, ai profili uniti e ai dati nelle esportazioni. L'eliminazione viene registrata nel registro attività e l'esito dell'esecuzione mostra quanti profili sono stati eliminati. In una sorgente di eventi le righe con il flag vengono semplicemente saltate.

Per una migrazione una tantum da Mindbox e da altre piattaforme, inclusa la cronologia, esiste uno strumento dedicato: vedi Migrazione da altre piattaforme.