OpenAI Pixel e Conversions API: tracking per ChatGPT Ads

OpenAI Pixel e Conversions API servono a misurare ciò che accade dopo un clic su ChatGPT Ads. Il Pixel invia eventi dal browser; la Conversions API li invia dal backend. Per una richiesta contatto affidabile, l’evento lead_created deve partire soltanto dopo che il server ha confermato il successo.

Questo dettaglio separa un tracking utile da una dashboard ingannevole. Se il sito registra un lead quando l’utente apre il form, clicca “Invia” o riceve un errore, Ads Manager ottimizza su azioni che non hanno valore commerciale.

Se stai ancora definendo accesso, obiettivi e struttura dell’account, parti dalla guida completa a ChatGPT Ads in Italia. Per applicare il tracking a un lancio reale, usa anche la checklist su come fare pubblicità su ChatGPT.

Pixel e CAPI misurano la pubblicità, ma non migliorano automaticamente le citazioni organiche: per quel lavoro serve una strategia distinta su come apparire su ChatGPT con SEO e GEO.

Architettura consigliata

Utente da ChatGPT Ads
        ↓
Landing page
        ↓
OpenAI Pixel: page_viewed
        ↓
Invio form al backend
        ↓
Validazione + elaborazione riuscita
        ↓
Pixel: lead_created  +  Conversions API: lead_created
        ↓
CRM / email / pipeline commerciale

La coppia Pixel + CAPI migliora la copertura della misurazione, ma richiede tre garanzie:

1. lo stesso evento descrive la stessa azione;
2. la chiave server non viene esposta al browser;
3. gli invii ripetuti non gonfiano le conversioni.

Pixel, CAPI o entrambi?

Per un sito statico senza backend, il Pixel può essere il punto di partenza. Per lead, registrazioni e acquisti è preferibile una conferma server-side, perché il backend conosce l’esito reale.

1. Crea la fonte dati in Ads Manager

La documentazione di OpenAI indica di creare una fonte dati nell’account pubblicitario e collegare gli eventi usati dalla campagna. Conserva separatamente:

• Pixel ID: identificatore pubblico usato dalla configurazione nel sito;
• chiave Conversions API: credenziale segreta con autorizzazione Bearer;
• eventi standard o personalizzati: nomi che devono corrispondere alla campagna;
• ambiente: produzione, staging o test.

Non usare la stessa fonte senza regole chiare tra più domini, clienti o ambienti. Altrimenti i test possono contaminare i dati di produzione.

2. Installa un solo script di configurazione per pagina

Il codice di inizializzazione va inserito una sola volta nell’head, preferibilmente tramite il layout globale. Il Pixel ID può essere pubblico; la chiave API no.

Esempio con segnaposto:

<script>
  !function(w,d,s,u){
    if(w.oaiq)return;
    var q=function(){q.q.push(arguments)};
    q.q=[];
    w.oaiq=q;
    var j=d.createElement(s);
    j.async=1;
    j.src=u;
    var f=d.getElementsByTagName(s)[0];
    f.parentNode.insertBefore(j,f);
  }(window,document,"script","https://bzrcdn.openai.com/sdk/oaiq.min.js");

  oaiq("init", { pixelId: "<PIXEL-ID>" });
</script>

In produzione evita debug: true salvo una scelta consapevole e temporanea. I log di debug possono generare rumore e non sostituiscono un ambiente di test.

3. Misura la pagina vista senza duplicarla

Un evento di contenuto può essere inviato quando la pagina è realmente caricata:

oaiq("measure", "page_viewed", {
  type: "contents"
});

Nei siti con navigazione client-side, una sola inizializzazione non garantisce una page view per ogni cambio di rotta. Nei siti statici multipagina, invece, lo script può ripartire a ogni documento. Prima di aggiungere listener, controlla il comportamento reale del framework per non inviare due eventi sulla stessa visita.

4. Invia lead_created soltanto dopo il successo

La regola è semplice:

Se il backend risponde con successo reale → invia lead_created
Altrimenti → non inviare la conversione

Esempio browser:

async function submitContact(formData) {
  const response = await fetch("/api/contact", {
    method: "POST",
    body: formData
  });

  const result = await response.json();

  if (!response.ok || !result.success) {
    throw new Error(result.error || "Richiesta non completata");
  }

  window.oaiq?.("measure", "lead_created", {
    type: "customer_action"
  });

  return result;
}

Questo codice evita tre falsi positivi comuni:

• click sul pulsante con campi non validi;
• risposta HTTP di errore;
• risposta formalmente 200 ma con success: false.

Se il backend accoda l’operazione e risponde prima di completarla, devi decidere cosa significa “lead creato”. Per esempio, un record salvato nel CRM può essere sufficiente; una semplice richiesta ricevuta ma non persistita non lo è.

5. Invia la conversione dal backend

La chiamata server utilizza l’endpoint eventi associato al Pixel ID e la chiave Bearer. Un payload minimale può essere:

{
  "validate_only": false,
  "events": [
    {
      "id": "<EVENT-ID>",
      "type": "lead_created",
      "timestamp_ms": 1788278400000,
      "source_url": "https://example.com/contatti",
      "action_source": "web",
      "data": {
        "type": "customer_action"
      }
    }
  ]
}

L’header Authorization deve essere costruito solo sul server:

Authorization: Bearer <CONVERSIONS-API-KEY>

Non inserire mai la chiave:

• nell’HTML;
• in una variabile PUBLIC_*;
• nel bundle JavaScript;
• in un repository Git;
• in screenshot o ticket pubblici;
• nei log applicativi.

Conservala in un secret manager o in una variabile d’ambiente server-side. Se viene incollata in una chat o pubblicata, considerala compromessa e ruotala.

6. Usa un EVENT-ID stabile e deduplicabile

Se Pixel e CAPI rappresentano la stessa conversione, genera un identificativo univoco per l’azione e riutilizzalo nei percorsi previsti dalla documentazione corrente. L’identificativo non deve contenere email, telefono o altri dati personali.

Una strategia robusta:

1. il backend crea un UUID quando accetta il lead;
2. salva l’UUID con lo stato dell’invio;
3. invia l’evento server con quell’ID;
4. restituisce al browser solo l’ID tecnico necessario;
5. retry e deduplicazione usano lo stesso ID.

Non generare un nuovo ID a ogni retry: trasformerebbe un singolo lead in più conversioni.

7. Gestisci retry senza creare eventi doppi

Una chiamata CAPI può fallire per timeout, errore temporaneo o rate limit. Il backend dovrebbe distinguere:

• errore permanente: payload invalido o autorizzazione negata; correggere prima di riprovare;
• errore temporaneo: timeout o risposta 5xx; riprovare con backoff;
• risposta incerta: connessione interrotta dopo l’invio; riutilizzare lo stesso EVENT-ID.

Salva almeno:

Non salvare il payload completo se contiene dati che non servono. Per questi eventi essenziali è spesso sufficiente loggare metadati tecnici.

8. Usa validate_only per i test

Quando disponibile nel flusso di configurazione, validate_only: true permette di verificare il payload senza trattarlo come un evento di produzione. Usalo con una fonte e una procedura di test documentate.

Il test completo deve coprire:

1. caricamento di una pagina;
2. form non valido: nessun lead_created;
3. errore backend: nessun lead_created;
4. successo backend: un solo evento browser;
5. successo CAPI: un solo evento server;
6. doppio clic: un solo lead persistito;
7. timeout CAPI: retry con lo stesso ID;
8. verifica in Ads Manager.

Un log “richiesta inviata” non dimostra che OpenAI abbia ricevuto o attribuito l’evento. Controlla sia la risposta API sia la diagnostica della fonte dati.

9. Collega eventi e obiettivi della campagna

Un evento ricevuto non diventa automaticamente la conversione principale di ogni campagna. Il nome deve corrispondere all’evento configurato e rientrare nella finestra di attribuzione applicabile.

Definisci una tassonomia ridotta:

Evita sinonimi inutili come contact_sent, lead, form_completed e request_created per la stessa azione. Una tassonomia stabile semplifica report, QA e ottimizzazione.

10. Privacy, consenso e minimizzazione

Il Pixel e la Conversions API non sostituiscono la valutazione privacy del sito. Documenta finalità, base giuridica, categorie di dati, destinatari, conservazione e modalità di consenso applicabili al tuo caso.

Principi tecnici utili:

• invia solo i campi richiesti;
• non mettere PII nell’ID evento;
• non registrare la chiave nei log;
• limita l’accesso ai secret;
• separa staging e produzione;
• implementa una Content Security Policy compatibile;
• aggiorna cookie policy e registro delle integrazioni;
• verifica la configurazione con il consulente privacy quando necessario.

Per inquadrare cookie, informative e ruoli del trattamento, consulta anche la guida GDPR per siti web.

Implementazione sul sito: il confine corretto

Su un sito Astro o Next.js la responsabilità può essere separata così:

Layout globale
└── inizializza il Pixel una volta

Modulo tracking client
├── page_viewed
└── lead_created dopo conferma API

Endpoint contatti
├── valida input
├── persiste/inoltra il lead
├── genera EVENT-ID
├── invia CAPI senza bloccare la risposta oltre il necessario
└── registra esito tecnico

Il modulo client non conosce la chiave. L’endpoint non si fida dei dati del browser. Il tracking non deve impedire all’utente di ricevere la conferma se il lead è già stato salvato: l’errore CAPI va gestito come problema di telemetria, con retry, non come motivo per duplicare il contatto.

Quando form, CRM e notifiche attraversano più sistemi, una architettura di automazioni AI per PMI aiuta a rendere espliciti responsabilità, retry e fonte dati autorevole.

Errori frequenti

• inizializzare il Pixel più volte nella stessa pagina;
• inviare lead_created al clic;
• esporre la chiave CAPI in JavaScript;
• usare debug: true permanentemente;
• generare un EVENT-ID nuovo a ogni retry;
• confondere HTTP 200 con successo applicativo;
• inviare eventi di test nella fonte produzione;
• non verificare l’evento ricevuto in Ads Manager;
• ottimizzare oCPC prima di avere conversioni affidabili.

Checklist di produzione

• Una sola inizializzazione Pixel per pagina
• Pixel ID in configurazione pubblica, chiave CAPI solo server-side
• page_viewed senza duplicazioni
• lead_created dopo successo reale
• EVENT-ID privo di PII
• Retry con ID stabile
• Staging separato dalla produzione
• validate_only usato nei test disponibili
• Errori CAPI loggati senza segreti
• Diagnostica controllata in Ads Manager
• Evento collegato all’obiettivo campagna
• Informative e consenso verificati

Metodo e fonti

Questa guida combina la documentazione ufficiale sulla misurazione delle conversioni con un’implementazione reale su sito Astro: Pixel globale, evento page_viewed, lead_created dopo successo di qualsiasi form e invio server-side senza esporre credenziali. Gli esempi usano segnaposto e non contengono chiavi o identificativi reali.

Domande frequenti su Pixel e CAPI

Devo usare Pixel e CAPI insieme?

Non è obbligatorio. Insieme possono migliorare la completezza, ma soltanto se deduplicazione e qualità evento sono corrette.

Il Pixel ID è segreto?

No, compare nel codice client. La chiave Conversions API è invece una credenziale e deve restare nel backend.

Cosa succede se CAPI fallisce dopo aver salvato il lead?

Il contatto non va duplicato. Registra l’errore e riprova con lo stesso EVENT-ID secondo una politica controllata.

Come verifico che il tracking funzioni?

Testa percorso positivo e negativo, controlla rete e log tecnici, quindi conferma la ricezione e la diagnostica nella fonte dati di Ads Manager.

Se vuoi implementare il tracking senza falsi lead o credenziali esposte, posso verificare sito, backend e CRM con un audit AI gratuito.