Eventi CAPI

Questa guida spiega come configurare gli eventi Conversions API che AdTarget invia a Meta quando gli utenti entrano nel tuo canale Telegram.

Quando Vengono Inviati gli Eventi CAPI?

AdTarget invia un evento CAPI a Meta solo per le iscrizioni attribuite — cioè le iscrizioni dove AdTarget riesce ad associare l’iscrizione Telegram a uno specifico clic sull’annuncio nella tua landing page. Questo richiede che l’invite_link sia presente nel webhook di Telegram.

Gli eventi CAPI vengono inviati quando un utente clicca il tuo link di invito tracciato e Telegram lo riporta nel webhook (affidabile per i canali privati).

Gli eventi CAPI NON vengono inviati per le iscrizioni organiche — utenti che trovano il tuo canale tramite ricerca, link diretti o messaggi inoltrati. Queste iscrizioni appaiono comunque nella tua dashboard AdTarget ma sono contrassegnate come “organic.”

Limitazione canali pubblici: A causa di una limitazione dell’API Telegram, anche gli utenti che cliccano il tuo link tracciato potrebbero essere trattati come iscrizioni organiche sui canali pubblici. L’app Telegram (specialmente Android) spesso converte le iscrizioni tramite link di invito in “ingressi diretti” per i canali pubblici, eliminando i dati di attribuzione. Scopri di più →

Tipi di Eventi Disponibili

AdTarget può inviare questi eventi standard Meta:

Evento	Ideale Per	Ottimizzazione Meta
Lead	Campagne di lead generation	Ottimizza per l’intento di lead
Purchase	Campagne orientate all’acquisto	Ottimizza per azioni di acquisto
CompleteRegistration	Campagne di registrazione	Ottimizza per azioni di registrazione
Subscribe	Campagne di abbonamento	Ottimizza per l’intento di abbonamento
Custom	Nome evento personalizzato	Per esigenze di tracciamento specializzate

Scegliere l’Evento Giusto

Fai lead gen ads? Usa Lead — Dice a Meta “questa persona è diventata un lead.”

Vendi un prodotto o servizio? Usa Purchase — Migliore quando vuoi che Meta ottimizzi per gli acquirenti. Abbinalo a un value e currency nella configurazione di conversione del tuo canale per l’ottimizzazione basata sul valore.

Fai campagne di registrazione? Usa CompleteRegistration — Segnala un’azione di registrazione completata.

Promuovi l’iscrizione a un canale? Usa Subscribe — Corrisponde all’azione dell’utente (iscriversi = abbonarsi).

Hai bisogno di un evento non standard? Usa Custom — Ti permette di definire il tuo customEventName per scenari di tracciamento specializzati che non rientrano nei tipi standard.

Suggerimento: Abbina il tipo di evento al tuo obiettivo di campagna in Ads Manager per i migliori risultati.

Configurare gli Eventi

I tipi di evento sono configurati per canale. Ogni canale ha come predefinito CompleteRegistration al primo rilevamento.

Per cambiare il tipo di evento di un canale:

Vai nelle Settings del tuo sito → scheda Channels
Clicca Setup (o Edit) sulla riga del canale
Seleziona il tipo di evento nella finestra
Clicca Save

Parametri degli Eventi

Ogni evento che AdTarget invia include questi parametri:

Parametri Obbligatori

Parametro	Descrizione
`event_name`	Il tipo di evento (Lead, ecc.)
`event_time`	Timestamp Unix dell’iscrizione
`action_source`	Sempre “website”

Parametri di Attribuzione

Parametro	Descrizione
`fbc`	Cookie di tracciamento del clic (contiene il `fbclid` dal clic sull’annuncio, formattato come `fb.1.{timestamp}.{fbclid}`)
`fbp`	Valore del cookie di tracciamento del browser (Meta browser ID)

Dati Utente

Se disponibili, AdTarget invia dati utente per il matching:

Parametro	Fonte	Hash?
`external_id`	ID utente Telegram	Sì (SHA-256)
`client_ip_address`	IP dalla visita alla landing page	No (inviato così com’è)
`client_user_agent`	Browser dalla visita alla landing page	No (inviato così com’è)

L’external_id (ID utente Telegram) viene hashato con SHA-256 prima dell’invio, come raccomandato da Meta. Altri parametri come indirizzo IP e user agent vengono inviati così come sono, in modo coerente con le specifiche CAPI di Meta per questi campi.

Dati Personalizzati

AdTarget invia anche questi campi all’interno dell’oggetto custom_data di ogni evento CAPI:

Parametro	Descrizione
`event_source_url`	URL della landing page (costruito dal dominio del sito + percorso della visita)
`value`	Valore dell’evento (se configurato per canale)
`currency`	Codice valuta (predefinito `"USD"`)
`content_name`	Titolo del canale o nome personalizzato dalla configurazione del canale

Deduplicazione degli Eventi

AdTarget include un event_id univoco con ogni evento per prevenire duplicati:


event_id: "adtarget_{conversion_id}"

Questo garantisce che la stessa conversione non venga contata due volte, anche in caso di retry.

Testare gli Eventi

Evento di Test di Validazione

Quando salvi il tuo pixel durante la configurazione, AdTarget invia automaticamente un evento di test PageView con il codice ADTARGET_TEST. Puoi vederlo in Meta Events Manager nella scheda Test Events — conferma che il tuo Pixel ID e il token di accesso funzionano.

Test in Produzione

Il modo più affidabile per testare end-to-end:

Clicca il tuo stesso annuncio (o usa un annuncio di test)
Visita la tua landing page
Entra nel tuo canale Telegram tramite il link di invito tracciato
Controlla Events Manager entro 5 minuti

Matching degli Eventi

Meta associa i tuoi eventi agli utenti per l’attribuzione. Maggiore qualità di matching = migliore ottimizzazione.

Fattori di Qualità del Matching

Fattore	Impatto
fbc presente (contiene fbclid)	Alto - Attribuzione diretta del clic
User agent + IP	Medio - Matching probabilistico
External ID	Medio - Matching cross-device

Migliorare la Qualità del Matching

Cattura il fbclid: Assicurati che l’URL della tua landing page preservi il parametro fbclid
Invia eventi tempestivamente: Un tempo più breve tra clic e conversione migliora il matching
Percorso utente coerente: Mantieni gli utenti sul tuo dominio prima di reindirizzarli a Telegram

Configurazioni di Evento Comuni

Lead Generation


Tipo Evento: Lead
Quando: L'utente entra nel canale
Caso d'uso: Campagne "ottieni iscritti"

Tracciamento Acquisti


Tipo Evento: Purchase
Quando: L'utente entra nel canale
Caso d'uso: Campagne "acquista ora" con ottimizzazione basata sul valore

Abbonamento a Contenuti


Tipo Evento: Subscribe
Quando: L'utente entra nel canale
Caso d'uso: Campagne "iscriviti al canale"

Configurazione Multi-Canale


Canale A (contenuti gratuiti): Lead
Canale B (premium): Purchase
Canale C (abbonamento): Subscribe

Risoluzione dei Problemi

Gli eventi non corrispondono?

Verifica che il fbclid sia nell’URL della landing page
Verifica che il Meta Pixel sia anche sulla landing page
Assicurati che i cookie non siano bloccati

Il punteggio di qualità dell’evento è basso?

Aumenta i dati che invii (IP, user agent)
Riduci il tempo tra clic e conversione
Verifica che il fbclid venga catturato

Eventi duplicati?

AdTarget gestisce la deduplicazione automaticamente
Se vedi duplicati, contatta il supporto

Buone Pratiche

Abbina il tipo di evento all’obiettivo della campagna per una migliore ottimizzazione
Usa lo stesso tipo di evento in modo coerente all’interno di una campagna
Monitora la qualità degli eventi in Events Manager settimanalmente
Testa prima di scalare la spesa pubblicitaria

Prossimi Passi

La tua integrazione Meta è completa! Inizia a far girare annunci e guarda le tue conversioni affluire in Meta.

Hai bisogno di aiuto per ottimizzare? Contatta il nostro team di supporto.