Meta Conversions API per i link brevi: cosa funziona oggi

Oggi Elido non inoltra le conversioni alla Conversions API di Meta. Se sei arrivato qui dall'elenco delle integrazioni aspettandoti un interruttore da attivare, non c'è, e preferisco dirlo subito piuttosto che mandarti su un percorso di configurazione che non porta da nessuna parte. Quello che segue è cosa registra Elido, cosa richiede la documentazione di Meta (consultato il 2026-10-25) e come costruire da solo la chiamata lato server, con o senza un link breve nel percorso.

In breve: Elido ti dà i click per link e, per Shopify e Stripe, il ricavo per link. Meta vuole un evento con un event_id, dati del cliente sottoposti a hash e, idealmente, l'ID del click fbc. Lo assembli tu.

Cosa fa e cosa non fa oggi Elido per Meta

Ecco lo stato del codice, verificato nel repository il 2026-10-25:

• ID del pixel Meta: un workspace può memorizzarne uno. Viene usato per il pixel del browser sulle pagine splash e interstitial di Elido. È un tag lato browser, non CAPI.
• Chiamata Meta lato server: la pipeline dei click contiene un percorso di codice Meta che invierebbe un PageView con IP e user agent. Viene eseguito solo quando esistono sia un ID del pixel sia un access token, e le impostazioni non memorizzano mai un token, quindi non scatta mai.
• Conversioni: gli ordini arrivano solo tramite i webhook di Shopify e Stripe e sono collegati a un link da un valore elido_link_id che passi tu. Non esiste un endpoint pubblico per le conversioni né un header o cookie con l'ID del click.
• fbclid: Elido non lo cattura né lo inoltra.

La pagina della funzione di tracciamento delle conversioni descrive lo stesso modello a webhook. Considera qualsiasi vecchio articolo che prometta l'inoltro a Meta con una sola chiamata come la descrizione di un piano, non di un prodotto.

Workspace demo con dati di esempio sintetici, non risultati di clienti.

Questa schermata resta utile accanto a Meta. Il ricavo per campagna dei tuoi ordini verifica ciò che dichiara Ads Manager. I due raramente concordano al centesimo.

Come funziona la Conversions API di Meta

Secondo la documentazione della Conversions API di Meta (consultato il 2026-10-25), invii una POST a https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events con un access token. L'esempio attuale della documentazione usa la v26.0. Alcuni limiti da conoscere prima di scrivere codice:

• Una richiesta può contenere fino a 1.000 eventi.
• event_time può risalire a un massimo di 7 giorni prima. Se un solo evento del batch è più vecchio, Meta rifiuta l'intera richiesta.
• Invia un event_id con ogni evento. Se Meta vede due volte lo stesso event_id e event_name, tiene la prima copia, il che rende sicuri i retry.

Per il token, la guida introduttiva di Meta (consultato il 2026-10-25) consiglia di generarlo in Events Manager: scegli il pixel, apri Impostazioni e usa "Generate access token" nella sezione Conversions API. Quel link è visibile solo agli utenti con privilegi da sviluppatore per l'azienda. Conserva il token in un secret del server.

Costruiscilo da solo, passo per passo

Gli stessi passaggi valgono che il click provenga da un link breve, da un QR code o da un annuncio diretto.

1. Conserva l'ID del click. La guida a fbp e fbc di Meta (consultato il 2026-10-25) dice di leggere fbclid dall'URL della landing sul server quando è presente e di formattarlo come fb.1.<creation time in ms>.<fbclid>. Memorizzalo come valore fbc insieme alla sessione del visitatore, poi copialo sull'ordine. Memorizza anche il valore del cookie _fbp se il pixel ne ha impostato uno.
2. Scegli l'ID dell'evento. Usa l'ID dell'ordine, e usa la stessa identica stringa nella chiamata del pixel del browser (eventID) e nell'evento server (event_id). Due formati diversi per lo stesso ordine, come ord_98231 e 98231, non verranno deduplicati.
3. Normalizza e applica l'hash. Secondo i parametri delle informazioni sul cliente di Meta (consultato il 2026-10-25), l'email viene ripulita dagli spazi e messa in minuscolo, poi sottoposta a hash con SHA-256. I numeri di telefono perdono simboli, lettere e zeri iniziali e devono includere il prefisso del paese prima dell'hash. fbc, fbp e client_ip_address non vengono mai sottoposti a hash.
4. Invia l'evento quando l'ordine è pagato, dal tuo backend o dal gestore del webhook degli ordini.
5. Verifica in Test Events, poi rimuovi il codice di test.

Un esempio minimo in Node:

import { createHash } from "node:crypto";

const sha256 = (v) => createHash("sha256").update(v).digest("hex");

const event = {
  event_name: "Purchase",
  event_time: Math.floor(Date.now() / 1000),
  event_id: order.id, // same string the browser pixel uses as eventID
  action_source: "website",
  event_source_url: order.thankYouUrl,
  user_data: {
    em: [sha256(order.email.trim().toLowerCase())],
    fbc: order.fbc,
    fbp: order.fbp,
    client_ip_address: order.ip,
    client_user_agent: order.userAgent,
  },
  custom_data: { currency: "EUR", value: 89.5 },
};

await fetch(
  `https://graph.facebook.com/v26.0/${PIXEL_ID}/events?access_token=${TOKEN}`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ data: [event] }),
  },
);

Aggiungi test_event_code al body mentre testi. Non registrare nei log l'URL completo in produzione, perché contiene il token.

Deduplicazione e Test Events, le due trappole

La guida alla deduplicazione di Meta (consultato il 2026-10-25) descrive il match su event_id più event_name, confrontando l'eventID del pixel con l'event_id del server, entro una finestra di 48 ore. Dice che funziona soprattutto quando l'evento del browser arriva per primo e quello del server segue. Dice anche che la deduplicazione non avviene affatto se usi una sola fonte.

Lo strumento Test Events nasconde una trappola. Il test_event_code è pensato solo per i test, e la pagina using the API di Meta afferma che gli eventi inviati con esso non vengono scartati: confluiscono in Events Manager e sono usati per il targeting e la misurazione. Quindi un acquisto di prova "innocuo" da 500 EUR conta comunque. Invia pochi eventi di prova di piccolo importo e rimuovi il codice dal payload di produzione.

Dopo che inizi a inviare, Meta dice che dovresti poter verificare gli eventi entro circa 20 minuti nella panoramica di Events Manager. Controlla che il nome dell'evento corrisponda a quello inviato dal tuo pixel e che l'evento mostri dati utente associati.

Dove entra in gioco un link breve

Un link breve non cambia il funzionamento di CAPI. Conta in due punti, e solo due.

Primo, l'ID del click. Meta aggiunge fbclid all'URL di destinazione che imposti sull'annuncio. Se quella destinazione è un link breve, il parametro arriva al link breve. Nel percorso di redirect di Elido non ho trovato codice che copi la query string in ingresso sulla destinazione. Quindi per gli annunci Meta punterei l'annuncio all'URL finale della landing con le UTM e riserverei i link brevi a email, SMS, QR code e post organici. Se vuoi comunque un link breve in un annuncio, provalo prima con un ?fbclid=test fittizio e controlla cosa riceve la tua landing page.

Secondo, il reporting. Tagga il checkout di Shopify o Stripe con elido_link_id. Il report delle conversioni di Elido mostra poi il ricavo per link e campagna, dai tuoi ordini. La guida a Shopify tratta il lato webhook. Per il quadro più ampio sul perché il conteggio solo nel browser perde eventi, vedi il tracciamento delle conversioni lato server e l'attribuzione senza cookie spiegata.

Consenso e privacy

L'hash non è anonimizzazione. Un hash SHA-256 di un indirizzo email resta un dato personale ai sensi del GDPR, perché Meta può confrontarlo con i propri archivi. Nell'UE serve una base giuridica, che per la misurazione pubblicitaria è normalmente il consenso, e la chiamata server deve rispettare la stessa scelta fatta dal visitatore nel tuo banner. Consent Mode v2 per il tracciamento e Schrems II e pixel di tracciamento trattano le questioni di consenso e trasferimento. Se un visitatore ha rifiutato, non inviare nulla.

Cosa manca in Elido

L'inoltro degli acquisti a Meta con una sola chiamata, la cattura di fbclid al redirect e un campo per l'access token nelle impostazioni Meta non sono ancora stati realizzati. Sono tracciati nel backlog del prodotto, e questo articolo cambierà quando saranno disponibili. Fino ad allora la configurazione onesta è quella descritta sopra: il tuo server invia l'evento, ed Elido fornisce intorno ad esso i dati di click e ricavo a livello di link.

Correlati sul blog

• Tracciamento delle conversioni lato server
• Click ID: gclid e fbclid
• Tracciare le UTM end to end
• Il retargeting dei link, spiegato
• Shopify URL shortener