3: implementazione per sviluppatori

Questa pagina descrive l'integrazione manuale e tratta i seguenti argomenti:

Costruire il payload per l'integrazione CRM
Generare un token d'accesso e preparare una chiamata API
Invio di un payload di prova
Invio dati di produzione

Questa sezione è applicabile solo se decidi di completare questa integrazione utilizzando un'integrazione manuale e le risorse per gli sviluppatori. Se invece decidi di completare l'integrazione utilizzando un partner, segui le rispettive istruzioni per l'integrazione. Puoi passare alla sezione 4: verifica i tuoi dati di questa guida una volta completata l'integrazione del partner.

Per completare questi passaggi di integrazione, avrai bisogno dell'accesso come amministratore al Business Manager. Puoi acquisire l'accesso dall'e-mail che hai ricevuto se sei stato invitato come sviluppatore. Altrimenti, contatta un amministratore del Business Manager per richiedere l'accesso.

Passaggio 1: crea un payload

Questo passaggio descrive le specifiche del payload per l'integrazione di Contatti di conversione e fornirà alcuni consigli su come inviarla dal tuo server.

Apri la guida all'integrazione CRM dalla tab Impostazioni del tuo pixel CRM per iniziare.

Consulta la Guida per gli sviluppatori dell'API Conversion per capire come funziona l'API Conversions.

Ti consigliamo di usare lo Strumento di assistenza per il payload per creare il tuo payload. Tale strumento formatta il tuo payload e controlla se ci sono errori Una volta risolti tutti gli errori del payload, clicca sul pulsante Ottieni il codice all'interno dello Strumento di assistenza per il payload per generare un modello di codice per il tuo linguaggio di programmazione.

Ecco la lista dei parametri richiesti. Consulta la guida Integrazione di Contatti di conversione - Specifica payload per vedere la descrizione completa di ogni parametro. Questa specifica del payload deve essere usata solo per gli eventi di ottimizzazione dei Contatti di conversione. Ciò significa che gli eventi devono riguardare solo le inserzioni per acquisizione contatti di Meta e avere un ID contatto valido. Evita di usare questa specifica del payload per altri tipi di eventi, come i contatti sul sito web.

Parametri

Nome	Descrizione
`event_name` stringa	Campo libero per l'acquisizione delle fasi di contatto che usi all'interno del tuo CRM. Il parametro `event_name` deve indicare un contatto che si muove attraverso il funnel di vendita nel tuo CRM. Assicurati di inviare tutte le fasi man mano che vengono aggiornate, compresi i contatti non qualificati.
`event_time` intero	Una marca temporale Unix in secondi che indica quando l'evento di aggiornamento della fase di contatto viene aggiornato dal tuo CRM. La marca temporale deve indicare un momento successivo a quello della generazione del contatto, altrimenti l'evento potrebbe essere eliminato.
`action_source` stringa	Valore:`system_generated` (Utilizzando l'API Conversions, dichiari che il parametro `action_source`, per quanto nei sai, è accurato)
`lead_id` intero	Il `leadgen_id` di 15 o 16 cifre dai tuoi contatti scaricati.
`lead_event_source` stringa	Il nome del CRM da cui provengono gli eventi.
`event_source` stringa	Valore:`crm`

Esempio
Un esempio di payload può assomigliare a questo. Nota: devi usare un lead_id valido, altrimenti il sistema rifiuterà il tuo evento.

{
    "data": [
        {
            "event_name": "initial_lead",
            "event_time": 1629424350,
            "action_source": "system_generated",
            "user_data": {
                "lead_id": 525645896321548
            },
            "custom_data": {
                "event_source": "crm",
                "lead_event_source": "salesforce"
            }
        }
    ]
}

Se gli eventi non rispettano le specifiche del payload o non corrispondono a un'inserzione per acquisizione contatti di Meta, non saranno riconosciuti per l'integrazione né usati per l'addestramento del modello.
Ad esempio, il payload Web verrebbe accettato dall'API Conversions e visualizzato in Gestione eventi, ma non sarà riconosciuto per questa integrazione. Devi anche usare un lead_id valido, altrimenti il sistema rifiuterà il tuo evento.
Solo il payload di Contatti di conversazione sarà riconosciuto per l'integrazione e utilizzato per l'addestramento.

Passaggio 2: crea un token d'accesso e una chiamata API

Una volta configurato ciò che invierai, il passaggio successivo è configurare dove invierai i dati.

Questo passaggio ti aiuterà a generare un token d'accesso per il tuo pixel di Meta, che verrà poi usato per stabilire una connessione tra il tuo server e l'API Conversions.

Puoi tornare alla guida all'integrazione CRM dalla tab Impostazioni del tuo pixel CRM.

Scorri verso il basso fino alla sezione Crea endpoint e clicca sul pulsante Genera token d'accesso. Il token d'accesso verrà usato per creare la tua chiamata API.
Puoi generare un nuovo token d'accesso tornando alla guida all'integrazione o dalla tab Impostazioni in Gestione eventi accedendo alla sezione API Conversions e cliccando sul link Genera token d'accesso.

Il resto di questa guida varierà a seconda che usi o meno l'SDK di Meta. Si consiglia di usare l'SDK Business di Meta perché consente di ottenere messaggi di errore e diagnostici migliori. Avrai bisogno del tuo ID pixel e del token d'accesso per effettuare la chiamata API tramite l'SDK Business di Meta. Puoi ottenere il token d'accesso cliccando su Copia token d'accesso nella guida all'integrazione CRM e salvandolo. Esempi di chiamate all'API SDK sono disponibili nella Guida per sviluppatori dell'API Conversions o nella funzionalità Ottieni il codice all'interno dello Strumento di assistenza per il payload di Meta.

Questo è il formato di endpoint per inviare una richiesta POST all'API Conversions senza l'SDK. Puoi ottenere l'intero endpoint cliccando su Copia endpoint nella guida all'integrazione CRM e salvandolo.
```
https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN
```
- API_VERSION: l'attuale versione dell'API Marketing
- PIXEL_ID: l'ID pixel può essere ottenuto da Gestione eventi per ogni pixel
- ACCESS_TOKEN: il token d'accesso generato sopra
Puoi consultare le date di rilascio e di scadenza dell'API Marketing nella documentazione sulle versioni dell'API. Assicurati di aggiornare la versione API o l'SDK Business di Meta nel tuo codice prima della data di scadenza dell'API Marketing. L'uso di una versione obsoleta nel tuo codice potrebbe comportare errori e i tuoi eventi potrebbero essere eliminati dal sistema.

Passaggio 3: prova un payload (facoltativo)

A questo punto puoi inviare un payload di prova al tuo pixel prima di implementare il codice sul tuo server. Puoi farlo usando la tab Testa gli eventi in Gestione eventi.

Nella sezione Testa gli eventi del server, clicca sul link Tool di esplorazione per la API Graph. Usando questo link unico, alcune informazioni verranno precompilate dal tuo pixel. (Se lo desideri, puoi anche accedere direttamente al Tool di esplorazione per la API Graph) Prendi nota del valore test_event_code, che può cambiare nel tempo.

Completa quanto segue nello strumento Tool di esplorazione per la API Graph:
1. Assicurati di essere in modalità POST.
2. Verifica che la tua versione API e l'ID pixel siano corretti.
3. Passa alla vista JSON.
4. Inserisci il tuo payload. Questo può essere creato o generato manualmente utilizzando lo Strumento di assistenza per il payload. Assicurati di includere il parametro test_event_code del passaggio precedente e un lead_id valido.
Inserisci il tuo token d'accesso del pixel e clicca sul pulsante Invia.

Se il tuo payload non contiene errori di sintassi o API, dovresti ricevere un messaggio di operazione eseguita correttamente con un fbtrace_id.

Dopo pochi minuti, l'evento di test dovrebbe essere visualizzato sotto la tab Testa gli eventi in Gestione eventi.

Passaggio 4: invia dati di produzione

I dati di produzione devono essere nello stesso formato del payload generato nel passaggio 3, ad eccezione del fatto che provengono direttamente dal tuo server. Questo passaggio varia per ogni integrazione, quindi questa sezione fornisce delle linee guida e non istruzioni specifiche.

Invia il lead_id invece delle IIP per l'associazione.

Assicurati di inviare tutte le fasi del contatto man mano che vengono aggiornate, compreso l'evento di contatto non qualificato che rappresenta tutti i contatti generati su Meta e scaricati nel tuo CRM. Di seguito è riportato un funnel di esempio. I nomi e le fasi degli eventi sono definiti dall'inserzionista, quindi non devono conformarsi a questo esempio.

Se le tue campagne generano 100 contatti, ci aspettiamo che 100 eventi "Contatto non qualificato" caricati rappresenteranno la prima fase di contatto. Inviando la prima fase di contatto, il sistema saprà che il contatto è stato ricevuto ed elaborato. Man mano che i contatti avanzano nel funnel di vendita, ci aspettiamo che vengano caricate 70 fasi "Contatti qualificati per il marketing", 30 "Opportunità di vendita" e 15 "Convertiti".

Ricapitolando, dalle campagne vengono generati 100 contatti, ma in questo scenario di esempio ci aspettiamo che vengano caricati 215 eventi.

Crea una funzione che recupera aggiornamenti dall'API o dal database del tuo CRM ogni volta che lo stato dei contatti si aggiorna. Quindi invia il tuo payload all'API Conversions di Meta usando una funzione personalizzata o l'SDK Business di Meta. L'opzione più adatta per la tua integrazione dipenderà dal tuo CRM e dalla configurazione del database.

Si consigliano variabili per:
- lead_id
- event_name
- event_time
Ad esempio, un payload che indica esplicitamente i valori dei parametri può essere simile a questo:
```
{
  "event_name": "initial_lead",
  "event_time": 1628294742,
  "user_data": {
    "lead_id": 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
```
Un payload che passa in valori dal tuo database usando variabili può essere simile a questo:
```
{
  "event_name": lead_stage // "initial_lead"
  "event_time": unix_time // 1628294742
  "user_data": {
    "lead_id": fb_lead_id // 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
```

Carica i dati almeno una volta al giorno. Idealmente, le chiamate al tuo CRM devono essere effettuate in tempo reale, ma puoi utilizzare metodi di batch orari o giornalieri se non è fattibile eseguire un'integrazione in tempo reale.
Se scegli i metodi in batch, assicurati di acquisire la cronologia delle modifiche di stato dei contatti e non un'istantanea del contatto al momento dell'operazione in batch. Ad esempio, se lo stato di un contatto si aggiorna 3 volte tra un batch e l'altro, ci aspettiamo 3 eventi per questo contatto e non solo l'aggiornamento finale.
Nota: ogni batch può includere al massimo 1000 eventi. Se c'è un errore nel batch, l'intero batch verrà eliminato, quindi consigliamo VIVAMENTE di utilizzare batch più piccoli e di aggiungere logica per la riesecuzione delle operazioni non riuscite.

Facoltativo. Consigliamo di registrare messaggi di errore dalla chiamata CAPI e di creare avvisi in caso di problemi. Sarebbe anche una buona idea gestire le eccezioni per questi errori.

Puoi eseguire il backfill dei tuoi dati per un massimo di 7 giorni nel passato. La differenza di tempo è calcolata tra event_time e upload_time. Il backfill di alcuni dati potrebbe accelerare il processo di addestramento.
ATTENZIONE: non cercare di eseguire il backfill più di 7 giorni di dati modificando i valori event_time. Il modello si basa su una marca temporale accurata per l'ottimizzazione. Così facendo, potresti determinare l'eliminazione di tutti i dati di cui è stato eseguito il backfill.
Assicurati che i tuoi valori event_time siano successivi alla marca temporale di generazione dei contatti, altrimenti i tuoi eventi potrebbero essere eliminati.

Se la tua integrazione sta caricando eventi su Meta, dovresti iniziare a vedere gli eventi in Gestione eventi per il tuo pixel entro un'ora. Affinché gli eventi vengano visualizzati, ricorda di usare un lead_id valido nei tuoi payload. Apri ogni evento inviato per l'integrazione CRM di Contatti di conversione in Gestione eventi e controlla che abbiano i parametri personalizzati lead_event_source e event_source popolati. Se l'evento non ha questi parametri, non verrà registrato come evento Contatti di conversione.
Il sistema verificherà se i tuoi eventi sono eventi Contatti di conversione validi. Dopo 1 giorno, se viene rilevato un evento valido, verrà visualizzato un segno di spunta verde accanto al passaggio Invia un evento CRM dell'integrazione.

< 2: Getting Started With the CRM Integration

4: verifica i tuoi dati >