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 si fa con l'importazione, mentre il caricamento periodico di profili ed eventi da un file tramite URL, da S3 o da un foglio Google si fa con le sorgenti di dati.

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

Importazione di profili da CSV

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

Requisiti del file

• CSV con le intestazioni delle colonne nella prima riga.
• Separatore: virgola, punto e virgola o tabulazione, rilevato automaticamente.
• Dimensione: fino a 20 MB.
• Almeno una colonna con un identificatore: id del cliente nel Suo sistema, email, telefono.

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 CSV 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.

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.

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.

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.

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.

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.

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.

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