Integrazione personalizzata per ricevere dati da sistemi esterni

In Connectif è possibile ricevere dati da sistemi esterni per utilizzare informazioni che non sono registrate di default nella piattaforma. Attraverso un'integrazione personalizzata, potrai sincronizzare i dati dei tuoi contatti in base a eventi generati su altre piattaforme.

In questo articolo, viene spiegato quali sono i tipi di integrazione personalizzata per ricevere dati e come creare un evento di questo tipo, con un esempio di integrazione con l'ERP.

1. Proprietà

Eventi di ricezione dati

• Gli eventi di ricezione dati sono uno strumento potente per ampliare e personalizzare Connectif in base ai tuoi casi d'uso specifici.

• Creando un nuovo evento di ricezione, dovrai indicare il contesto:

  • API pubblica.

  • Webhook.

  • Web o App mobile.
     

Evento di ricezione tramite API pubblica

Gli eventi di ricezione tramite API pubblica sono il meccanismo più sicuro, in quanto richiedono una Chiave API. Sono progettati affinché gli eventi vengano inviati dal tuo server a Connectif.

Caratteristiche e limiti:

• La dimensione massima di un evento è di 512KB.

• È obbligatorio definire un campo email richiesto e chiave primaria per identificare il contatto.

• È possibile indicare tramite la query string createContact se creare o generare un errore quando il contatto a cui appartiene l'evento non esiste.

• Il nodo trigger del workflow generato da un evento di ricezione tramite API pubblica non avrà contesto web.

• Richiedono una validazione rigorosa e non permettono di inviare campi non definiti nell'evento.

Evento di ricezione tramite Webhooks

Gli eventi di ricezione tramite Webhook sono un meccanismo più flessibile, ideali quando non si controlla il mittente dei dati, ad esempio utilizzando un webhook di uno strumento esterno dove non è possibile modificare il formato dei dati inviati o non è possibile stabilire un'intestazione di sicurezza con chiave API.

Caratteristiche e limiti:

• La dimensione massima di un evento è di 512KB.

• È obbligatorio definire un campo email richiesto e chiave primaria per identificare il contatto.

• Creano sempre il contatto in Connectif se non esiste.
• Permettono di definire JSON Pointer per mappare campi a strutture complesse. Ideale quando l'informazione dell'evento si trova in oggetti complessi e annidati.
• Non generano errore di validazione in caso di campi sconosciuti. Ciò permette di mappare solo i campi di interesse ignorandone altri che saranno semplicemente scartati.

• Il nodo trigger del workflow generato da un evento di ricezione tramite Webhook non avrà contesto web.

Evento di ricezione tramite Web o App mobile

Gli eventi di ricezione tramite Web o App mobile permettono di inviare eventi direttamente dal lato client del tuo sito web o dalla tua app mobile. Per questo è necessario utilizzare rispettivamente l'SDK Web o l'SDK Mobile.

Caratteristiche e limiti:

• Gli eventi tramite Web o App non richiedono un campo email obbligatorio e chiave primaria. Possono quindi essere inviati per contatti anonimi o conosciuti durante il tracciamento web o della tua app mobile.

• Il nodo trigger del workflow generato da un evento di ricezione tramite Web o App mobile avrà contesto web. Dopo questo nodo è possibile utilizzare il nodo Mostra contenuto web.
   

2. Come funziona la creazione di un evento di ricezione dati in Connectif

Il processo di creazione di un evento di ricezione dati consiste in alcuni passaggi da seguire, indipendentemente dal meccanismo scelto.

A titolo di esempio, di seguito viene mostrato come creare un evento di ricezione dati per collegare un ERP con Connectif:

2.1. Creazione dell'integrazione personalizzata

1. Accedi a "Integrazioni > Personalizzate" e clicca su  Crea nuova integrazione.

2. Imposta il campo "Nome" per identificare l'integrazione.

3. (Opzionale) Personalizza il colore, aggiungi una descrizione o categorizza l'integrazione.

4. Clicca su Aggiorna.

2.2 Creazione e configurazione dell'evento "Ricevi dati"

(In questa sezione verrà creato l'evento di ricezione e configurati i campi dove verranno memorizzati i dati ricevuti).

5. Nella scheda Ricevi dati, clicca su Crea nuovo evento di ricezione.

6. Nella finestra popup, scegli il tipo di connessione per l'evento e clicca su Vai all'editor. Nell'esempio, tramite API pubblica.

7. Assegna un Nome e un Alias all'evento.

8. Clicca su Aggiungi un nuovo campo per creare un campo di tipo Email, per raccogliere l'indirizzo email del contatto.

9. Ripeti l'azione indicata nel punto precedente tutte le volte che desideri ricevere dati.

10. Clicca su Salva e, nella schermata di conferma, clicca su Torna all'elenco eventi.

2.3. Creazione della Chiave API per abilitare la ricezione dati

(In questa sezione viene spiegato come generare l'indirizzo per notificare il tipo di evento creato, l'endpoint).

10. Vai a "Impostazioni negozio > API e accessi IP" e, in Chiavi API, clicca su Crea nuova chiave API.

11. Nella sezione Eventi personalizzati, attiva il permesso per Scrivere.

12. Salva la chiave API e, nel menu Chiavi API, individua quella appena creata e clicca sul pulsante per copiarla (indicato nell'immagine).

13. Usa la chiave API per effettuare la richiesta di invio dell'evento dal tuo sistema.

2.4. Ottenimento dell'endpoint di notifica

(In questa sezione viene spiegato come generare l'indirizzo per notificare il tipo di evento creato, l'endpoint).

14. Nella scheda Ricevi dati, clicca su Modifica.

15. Clicca su Copia URL per copiare negli appunti l'indirizzo dell'endpoint.

2.5. Invio dati a Connectif

(In questa sezione si spiega come stabilire la comunicazione con l'endpoint e inviare dati).

16. Nel tuo codice, incolla questa URL insieme alla Chiave API e al corpo della richiesta per generare l'evento di ricezione. Nel caso di eventi tramite Webhook o Web/App, non sarà necessario utilizzare la Chiave API.

17. Effettua la chiamata all'endpoint per notificare i dati dell'evento.

2.5.1 Esempio di invio dati tramite Postman (Webhook)

Una volta configurato l'evento di ricezione in Connectif, è possibile effettuare test di invio dati utilizzando Postman per verificare che le informazioni vengano ricevute correttamente.

Configura la richiesta

1. Apri Postman e crea una nuova richiesta.
2. Seleziona il metodo POST.
3. Inserisci come URL l'endpoint generato per l'evento di ricezione.

Esempio:

https://webhook-api.connectif.cloud/{store-id}/custom-events/alias/webhook-event-example

Configura le intestazioni (Headers)

Aggiungi le intestazioni necessarie per l'invio dati:

Configura il corpo della richiesta (Body)

Seleziona Body > raw > JSON e inserisci un payload conforme ai campi definiti nell'evento.

Esempio:

{
    "email": "john.doe@example.org",
    "phone": "+34666777888",
    "name": "Hi there!"
}

Invia la richiesta

Clicca su Send per effettuare la richiesta.

Se la richiesta viene processata correttamente, l'evento sarà ricevuto da Connectif e potrà essere utilizzato in workflow, segmentazioni o processi di automazione.

Si consiglia di verificare la ricezione dell'evento tramite un workflow di prova o controllando l'attività del contatto associato ai dati inviati.

Risultato:

L'immagine seguente mostra un esempio di una richiesta effettuata correttamente da Postman e la risposta restituita da Connectif.

2.5.2 Esempio di invio dati tramite Postman (API)

Una volta configurato l'evento di ricezione e creata la Chiave API, è possibile utilizzare Postman per verificare che Connectif riceva correttamente i dati inviati.

Configura la richiesta

1. Apri Postman e crea una nuova richiesta.
2. Seleziona il metodo HTTP indicato nella documentazione dell'endpoint che utilizzerai.
3. Inserisci l'URL corrispondente all'endpoint dell'API.

Esempio:

https://api.connectif.cloud/custom-events/alias/api-event-example?createContact=true

Configura le intestazioni (Headers)

Aggiungi le credenziali richieste dall'endpoint tramite le intestazioni corrispondenti.

Sostituisci {api_key} con la Key Secret corrispondente.

Configura il corpo della richiesta (Body)

Seleziona Body > raw > JSON e inserisci un payload conforme ai campi definiti nell'evento.

Esempio:

{ 
    "email": "john.doe@example.org", 
    "name": "Hi there!", 
    "phone": "+34666777888" 
}

Invia la richiesta

Clicca su Send per effettuare la richiesta.

Se la richiesta è stata processata correttamente, l'API restituirà una risposta positiva e i dati saranno registrati in Connectif secondo la funzionalità utilizzata.

Risultato:

L'immagine seguente mostra un esempio di una richiesta effettuata correttamente tramite API pubblica utilizzando una Chiave API con permessi di scrittura per eventi personalizzati.

2.6. Sincronizzazione dei dati con le informazioni del contatto

(In questa sezione si spiega come sincronizzare i dati in Connectif tramite un workflow).

18. Accedi a “Workflow”, clicca su Crea nuovo workflow e seleziona Crea workflow vuoto.

19. Crea la struttura del tuo workflow con il nodo di tipo trigger “Trigger [nome della tua integrazione]” e il nodo di tipo azione “Imposta campo”.

20. Nel nodo “Trigger Ricevi dati da…”, clicca su (Modifica configurazione nodo).

21. Verifica che i dati raccolti dal nodo "Trigger Ricevi dati da...", provenienti dall'evento nel sistema esterno, siano corretti.

22. Clicca su Salva.

23. Nel nodo “Imposta campo”, clicca su (Modifica configurazione nodo).

24. Mappa le variabili per assegnare le informazioni raccolte dall'integrazione personalizzata ai campi contatto corrispondenti.

25. Clicca su Aggiorna.

26. Nel workflow, clicca su  Salva per salvare le modifiche e su  Avvia per attivarlo.

2.7. Creazione di un Segmento Dinamico Plus dell'integrazione

Con Connectif, potrai creare un Segmento Dinamico Plus per filtrare per le attività e i campi relativi all'integrazione personalizzata.

Una volta creato un segmento di contatti dell'integrazione personalizzata, questa non potrà essere eliminata. Inoltre, se uno dei suoi campi viene utilizzato come condizione di segmentazione, non potrà essere né cancellato né modificato.

Continua ad imparare!

Per sfruttare tutto il potenziale del tuo account Connectif, ti consigliamo di continuare con i seguenti articoli:

• Integrazione personalizzata per inviare dati, per inviare dati da Connectif a sistemi o applicazioni esterne.

• Rilevare e reagire ai link web creati fuori da Connectif, per identificare e rispondere ai clic su qualsiasi link del tuo sito web.

• Integrazione con Facebook e Instagram, per gestire le audience del tuo account Facebook Ads con Connectif.

• Moduli integrati, per rilevare e raccogliere in Connectif moduli già esistenti nel tuo sito web.