API Conversions per Google Tag Manager (GTM) lato server

L'API Conversions è progettata per creare una connessione diretta tra i dati di marketing e i sistemi, favorendo in tal modo l'ottimizzazione della targetizzazione delle inserzioni, la diminuzione del costo per azione e la misurazione dei risultati tramite le tecnologie di Meta. Puoi impostare un server configurato su Google Cloud Platform (GCP) o su qualsiasi altro provider di servizi cloud in modo che invii dati sugli eventi web e offline chiave mediante l'API Conversions. Con questo tipo di configurazione, dopo aver impostato Google Analytics 4 (GA4) Web Tag, puoi inviare tali dati al tuo server ospitato su Google Cloud Platform (GCP) e, infine, a Meta tramite l'API Conversions.

Il tag dell'API Conversions viene scritto e gestito da Meta in base al modello di tag personalizzato di Google. Contatta Google per qualsiasi domanda sulla configurazione dei prodotti Google o sulla documentazione per sviluppatori di Google.

Questo documento descrive i seguenti elementi:

• Prerequisiti, compresa la modalità di creazione di un contenitore del server
• Modalità di configurazione del contenitore per supportare l'implementazione di GA4 Web Tag
• Modalità di invio dei dati dal sito web al server GCP
• Modalità di condivisione di tali dati con Meta utilizzando l'API Conversions
• FAQ

Prerequisiti

Prima di procedere con questa integrazione, ti consigliamo di intraprendere le seguenti azioni:

1. Acquisisci familiarità con l'integrazione dell'API Conversions e le best practice per la configurazione.
2. Acquisisci familiarità con l'aggiunta di tag lato server e il modello di tag personalizzato.

Se il sistema utilizza una versione precedente a Google Analytics 4, prima di procedere con questa integrazione dovrai aggiornare la configurazione dello strumento di gestione dei tag esistente per utilizzare Google Analytics 4.

Integrazione

Creazione di un contenitore del server GTM

Dovrai configurare un contenitore del server e un contenitore web:

• Contenitore web: se è la prima volta che utilizzi GTM, inizia con l'installazione di un contenitore web sul tuo account. Ulteriori informazioni qui.
• Contenitore del server: dovrai creare un contenitore del server nel tuo portale GTM per configurare un URL del server per l'aggiunta di tag. Scopri di più su questo passaggio.

La configurazione di un contenitore del server richiede la configurazione di un server per l'aggiunta di tag. L'implementazione GCP predefinita può essere completata durante la configurazione del contenitore del server; fai riferimento alle seguenti linee guida. Per qualsiasi altro provider di servizi cloud (ad esempio, AWS o Microsoft Azure), fai riferimento alla guida alla configurazione manuale del server.

Configurazione dei contenitori web e del server

1. Sul contenitore web, crea i seguenti artefatti:
   • Configurazione Google Analytics 4 per configurare l'URL del server per l'aggiunta di tag.
   • Evento Google Analytics 4 per configurare lo schema di eventi da consegnare al server.
2. Sul contenitore del server, crea i seguenti artefatti:
   • Client Google Analytics 4, un listener per l'evento che attiva l'evento su Meta.
   • Tag dell'API Conversions di Meta, un tag lato server che converte il modello di eventi standard dal client Google Analytics 4 allo schema di eventi dell'API Conversions e lo invia a graph.facebook.com.

Passaggio 1: configurazione Google Analytics 4, configurazione dell'URL del server per l'aggiunta di tag

Configura il contenitore web per inviare i dati del sito web al server per l'aggiunta di tag creato. Scopri di più sulla modalità di configurazione di Google Analytics: tag della configurazione Google Analytics 4.

• Se selezioni Invia al contenitore del server, imposta l'URL del contenitore del server come URL del server per l'aggiunta di tag.
• Se non selezioni Invia al contenitore del server, in Campi da impostare, clicca su Aggiungi riga e imposta:

  • Nome del campo: transport_url
  • Valore del campo: URL del server per l'aggiunta di tag

Puoi configurare campi aggiuntivi per qualsiasi altro parametro che desideri inviare per tutti gli eventi.

• Imposta il flag first_party_collection su true. Devi eseguire questa operazione per poter passare i parametri user_data al GTM lato server. In Campi da impostare, clicca su Aggiungi riga e imposta:

  • Nome del campo: first_party_collection
  • Valore del campo: true

Utilizzo di un tag della configurazione Google Analytics 4 esistente

Se hai già una configurazione Google Analytics 4 impostata, puoi modificarla o creare un ulteriore tag della configurazione per GTM lato server.

Se stai configurando GTM lato server per la prima volta, l'aggiunta dell'URL del contenitore del server inizierà a inviare tutto il traffico al contenitore del server. Se desideri continuare a inviare dati a Google Analytics 4, dovrai aggiungere il tag lato server Google Analytics 4 nel contenitore del server, assicurandoti che si attivi su tutti gli eventi. Potresti dover creare tag dell'evento di Google Analytics 4 aggiuntivi o modificare quelli esistenti per garantire una mappatura completa per gli eventi del pixel di Meta.

Invio di ID browser di Meta e ID clic di Meta

Se hai configurato un dominio personalizzato e il dominio del server per l'aggiunta di tag GTM è proprietario, l'ID browser di Meta e l'ID clic di Meta vengono inviati automaticamente.

Se usi il dominio predefinito fornito o noti che i campi ID browser e ID clic non vengono inviati in Gestione eventi, puoi configurare questi campi nel modo seguente:

• Passa alla sezione delle variabili e crea una nuova variabile definita dall'utente sia per l'ID browser di Meta sia per l'ID clic di Meta. Utilizzare il cookie proprietario del tipo di variabile.

  • Per l'ID browser di Meta, imposta il nome del cookie su _fbp
  • Per l'ID clic di Meta, imposta il nome del cookie su _fbc
• Salva queste variabili.
• Nel tag della configurazione Google Analytics 4, in Campi da impostare, clicca su Aggiungi riga e imposta:

  • Nome del campo: x-fb-ck-fbp
  • Valore del campo: variabile dell'ID browser di Meta
• Aggiungi una riga aggiuntiva per l'ID clic:
• Nome del campo: x-fb-ck-fbc
• Valore del campo: variabile dell'ID clic di Meta

Crea una variabile di livello dati per ognuno dei parametri user_data dello schema di eventi comuni GTM. Scopri di più sulla configurazione delle variabili di livello dati. Ad esempio, per passare un indirizzo e-mail a GTM lato server, crea una variabile (ad esempio, user_data_email_address) che può essere mappata sul nome della variabile di livello dati, eventModel.user_data.email_address.

Se non usi il livello dati, configura le variabili da usare per ciascun parametro come indicato di seguito. La lista seguente mostra tutte le mappature per i parametri user_data di Meta e GTM e la relativa priorità generale nell'aiutare ad aumentare la qualità dell'associazione degli eventi. Per sfruttare al meglio le inserzioni di Meta, ti consigliamo di seguire le best practice per l'API Conversions durante la configurazione di un'integrazione. Se hai già configurato l'API Conversions, ti consigliamo di prendere in considerazione tali best practice per migliorare la configurazione esistente. Le best practice per l'API Conversions possono aiutarti a migliorare le prestazioni delle inserzioni riducendo il costo per azione.

Passaggio 2: evento di Google Analytics 4, configurazione dello schema di eventi da consegnare al server

• Configura il contenitore web per inviare i dati del sito web al server per l'aggiunta di tag creato per aggiungere Google Analytics. Scopri di più sulla modalità di configurazione di Google Analytics: tag della configurazione Google Analytics 4.

• Aggiungi il tag Google Analytics: evento di Google Analytics 4 all'area di lavoro dalla galleria modelli.

  • Configura un nome dell'evento per il tag. Puoi impostarlo come valore statico o configurarlo affinché sia letto in base alla variabile. Per alcuni eventi standard, mapperemo gli eventi standard di Google Analytics agli equivalenti di Meta. Per questi eventi, puoi utilizzare il nome dell'evento di Google Analytics o il nome dell'evento di Meta. Per tutti gli altri eventi standard, utilizza il nome dell'evento di Meta. Per gli eventi personalizzati, usa il nome dell'evento personalizzato. Ulteriori informazioni qui.

• Nella sezione Parametri dell'evento:

  • Se utilizzi il pixel di Meta, aggiungi il parametro ID evento. Utilizza event_id come nome del parametro e la variabile creata per l'ID evento come valore del parametro. Fai riferimento alla sezione Deduplicazione per indicazioni sulla creazione della variabile ID evento e sulla modifica del pixel di Meta.
  • Mappa tutti i parametri che desideri configurare. Il nome della variabile sarà letta dall'evento usando lo schema di eventi comuni. Ad esempio, per configurare e-mail come parametro dell'evento, devi definirlo come Nome del parametro: user_data.email_address e configurare il Valore come il nome della variabile che legge email_address (definito nella precedente Sezione 1).
  • Per una lista completa, consulta la sezione Parametri dei dati personalizzati di seguito.

Passaggio 3: creazione di un listener per l'evento che attiva l'evento su Meta

Ogni contenitore lato server GTM prevede un client Google Analytics 4 predefinito per l'ascolto degli eventi configurati da GA4 Web Tag. Il client Google Analytics 4 ascolta il percorso /g/collect sull'URL del server per l'aggiunta di tag e invia eventModel al tag a valle. Se il client Google Analytics 4 predefinito è già installato nel contenitore del server nella sezione Client, puoi procedere al passaggio 4.

Passaggio 4: creazione del tag dell'API Conversions di Meta, un tag lato server che converte il modello di eventi standard dal client Google Analytics 4 allo schema di eventi dell'API Conversions e lo invia al sito web graph.facebook.com

Per inviare l'evento all'API Conversions, devi installare il tag dell'API Conversions di Meta dalla galleria modelli. Il modello di tag viene denominato tag dell'API Conversions da facebookincubator. Questo tag può essere configurato per essere attivato su eventi ricevuti dal client Google Analytics 4 (nel passaggio precedente) e inviato all'API Conversions. Per installare il tag dell'API Conversions di Meta, dovrai disporre di un ID del pixel, un token d'accesso e specificare come origine delle azioni "sito web". Usando l'API Conversions, dichiari che il parametro action_source, per quanto ne sai, è accurato.

Test dell'integrazione

Consigliamo di usare la modalità di anteprima di Google Tag Manager per testare le integrazioni prima di pubblicare le modifiche. Sia i contenitori web sia i contenitori del server dispongono di modalità di anteprima e si possono eseguire entrambi contemporaneamente.

Puoi verificare che gli eventi del tuo server vengano ricevuti come previsto utilizzando la funzione Testa gli eventi in Gestione eventi. Per trovare lo strumento, accedi a Gestione eventi > Origini dei dati > Il tuo pixel > Testa gli eventi.

Lo strumento Testa gli eventi genera un ID di test. Invia l'ID di test come parametro test_event_code nel tag dell'API Conversions per iniziare a vedere comparire l'attività degli eventi nella finestra Testa gli eventi. Assicurati di rimuoverlo prima di pubblicare eventuali modifiche.

Lo strumento Testa gli eventi ti consente di vedere se gli eventi vengono ricevuti e deduplicati correttamente. Se gli eventi non vengono visualizzati dopo uno o due minuti, controlla il debugger lato server GTM per assicurarti che la richiesta sia andata a buon fine:

1. Nel debugger lato server, scegli l'evento pertinente che desideri controllare nel menu a sinistra.
2. Verifica che il tuo tag venga visualizzato nella sezione Tag attivati. In questo caso, visualizzerai il tag dell'API Conversions "riuscito" o "non riuscito".
   • Tag non attivato: controlla l'attivazione del tag dell'API Conversions e l'attivazione dell'evento di Google Analytics 4 pertinente sul contenitore web. Verifica che l'evento di Google Analytics 4 è stato attivato nel debugger web.
   • Tag attivato: riuscito: clicca sul tag e controlla che il codice evento di prova sia corretto. Aggiorna il codice dell'evento di prova se necessario e riavvia la modalità di anteprima.
   • Tag attivato: non riuscito: apri la tab Richiesta e clicca sulla richiesta in uscita inviata a https://graph.facebook.com. Controlla il corpo della risposta in fondo ai dettagli della richiesta per visualizzare quale è stato l'errore e aggiorna la tua integrazione, se necessario. Ricorda di riavviare la modalità di anteprima dopo aver apportato le eventuali modifiche.

Dopo la visualizzazione degli eventi, verifica che gli ID evento per ciascuno di essi siano stati inviati correttamente e che tutte le chiavi di corrispondenza previste e i parametri dei dati personalizzati vengano visualizzati correttamente. Lo strumento Testa gli eventi viene visualizzato se gli eventi vengono deduplicati correttamente. Se gli ID evento sono diversi, assicurati che i tag di Google Analytics 4 e del pixel di Meta vengano attivati ​​sullo stesso attivatore e controlla l'implementazione della variabile ID evento.

Deduplicazione

Ti consigliamo di utilizzare una configurazione di eventi ridondante e di condividere gli stessi eventi sia dall'API Conversions sia dal tuo pixel di Meta. Assicurati che entrambi gli eventi usino l'event_name identico e che siano inclusi event_id o una combinazione di external_id e fbp.

Ciò consentirà a Meta di deduplicare gli eventi e ridurre la doppia segnalazione di eventi identici. Scopri di più sulla deduplicazione, quando è necessaria e come configurarla. external_id e fbp sono soluzioni alternative per la deduplicazione e aiutano anche a migliorare la qualità della configurazione. Consigliamo di includere questi tre parametri quando possibile.

GTM dispone di una varietà di modi per impostare un parametro con lo stesso valore su un tag browser e un tag server. Un modo consiste nell'usare lo stesso evento di Google Analytics 4 per attivare il tag del pixel di Meta e l'evento del server. Ecco come fare:

• Usa lo stesso attivatore per il tag HTML personalizzato del pixel di Meta e il tag dell'evento di Google Analytics 4. Ad esempio, la condizione di attivazione può essere basata sull'URL della pagina di conferma.
• Usa lo stesso event_id in entrambi i tag:

  1. Imposta un ID univoco dal client: imposta un parametro personalizzato (x-fb-event_id) dall'evento gtag. Genera un ID unico (per evento) sul sito web usando un metodo JavaScript (o utilizzando la variabile del JavaScript personalizzato di Google Tag Manager) e imposta il valore nell'evento come:

  gtag('event', 'purchase', {
   'x-fb-event_id': generateEventId(),
  ...:...
  
   });

  Puoi creare una variabile che punti al JavaScript personalizzato mostrato in precedenza. Ogni volta che si fa riferimento alla variabile, il seguente JavaScript viene caricato in linea:

  function() {
  var gtmData = window.google_tag_manager[{{Container ID}}].dataLayer.get('gtm');
  return gtmData.start + '.' + gtmData.uniqueEventId;
  }

  2. Crea e compila una variabile di livello dati: puoi creare la tua variabile nel contenitore web da cui leggere il valore event_id. Puoi eseguire tale operazione creando una nuova variabile di livello dati, ad esempio FBEventIdVar, il cui nome è eventModel.event_id.
  3. Dopo aver impostato la variabile, potrai collegarla all'evento web nel tuo tag HTML personalizzato e definire l'evento del server come un parametro dell'evento di Google Analytics 4 aggiuntivo.
  4. Sul web, puoi impostare il tag di Meta sui contenitori web di Google Tag Manager per la lettura di event_id da una variabile.

  fbq('track', Purchase, {..}, {eventID: FBEventIDVar });

  Configura l'evento di Google Analytics 4 per inviare un parametro aggiuntivo, denominato event_id, impostato sulla variabile FBEventIdVar.

Parametri dei dati personalizzati

Per inviare i dati personalizzati, usa le mappature seguenti nei tag dell'evento di Google Analytics 4:

Invio dei dati dal sito web al server GCP

Dopo aver configurato i contenitori web e del server, puoi inviare un evento di esempio dal tuo sito web per verificare l'evento del server. Un evento di esempio con i parametri configurati ha una struttura simile a questa:

 gtag('event', 'purchase', 
  {
    'event_id': generateEventId(),
    'transaction_id': 't_12345',
    'currency': 'USD',
    'value': 1.23,
    user_data: {
      email_address: '<HASHED_DATA>',
      phone_number: '<HASHED_DATA>',
      address: {
        first_name: '<HASHED_DATA>',
        last_name: '<HASHED_DATA>',
        city: '<HASHED DATA>',
        region: '<HASHED_DATA>',
        postal_code: '<HASHED_DATA>',
        country: '<HASHED_DATA>'     
      },    
    },
    items: [
      {
        item_id: '1',
        item_name: 'foo',
        quantity: 5,
        price: 123.45,
        item_category: 'bar',
        item_brand: 'baz'     
      }
    ], 
  });      
     

Dopo l'attivazione dell'evento, dovresti visualizzare una richiesta inviata, ad esempio, al link di esempio www.analytics.example.com/g/collect, con i parametri configurati. Puoi aggiungere il codice dell'evento di prova al tag dell'API Conversions di Meta per verificare gli eventi inviati all'API Conversions. Il codice dell'evento di prova deve essere utilizzato solo per il test. Devi rimuoverlo quando invii il payload di produzione.

Dopo aver pubblicato le modifiche, usa la pagina Verifica della configurazione qui per assicurarti che gli eventi vengano inviati correttamente controllando la seguente Verifica della configurazione: API Conversions e controlla che l'integrazione di qualità rispetti le nostre best practice.

FAQ

È prevista l'aggiunta della funzionalità per inviare parametri personalizzati? In caso affermativo, quando sarà disponibile?
R: abbiamo aggiunto la mappatura per la maggior parte dei parametri personalizzati standard dell'API Conversions che sono supportati nello schema di GTM. Abbiamo anche fornito una mappatura personalizzata. Ulteriori informazioni qui.

Esiste un singolo server o cluster in grado di eseguire più contenitori?
R: Al momento, GTM supporta solo la mappatura 1:1. Leggi i consigli su come organizzare i tuoi contenitori.

GTM lato server richiede un tag basato su browser per emettere eventi?
R: Sì.

È possibile mantenere Google Analytics 4 e l'integrazione lato server separati?
R: Per mantenere Google Analytics 4 e un'integrazione GTM lato server separati, puoi creare un ID di misurazione aggiuntivo in Google Analytics. Crea un tag separato della configurazione Google Analytics 4 per GTM lato server utilizzando questo ID di misurazione, seguendo i passaggi precedenti. In questo scenario, il tag della configurazione Google Analytics 4 esistente continuerà a inviare il traffico di Google Analytics attraverso il contenitore web, mentre il nuovo tag della configurazione invierà i dati al contenitore del server. Crea tag degli eventi di Google Analytics 4 aggiuntivi come da passaggio 2 per inviare gli eventi lato server, utilizzando il nuovo tag della configurazione

L'integrazione dell'API Conversions GTM funziona con soluzioni di hosting cloud diverse da GCP?
R: L'integrazione dell'API Conversions GTM dovrebbe funzionare con GCP o qualsiasi altra piattaforma a tua scelta. Scopri di più qui sul provisioning manuale.

Per saperne di più

• API Conversions
• Informazioni sulla deduplicazione degli eventi del pixel di Facebook e dell'API Conversions