Recopilar
La API de conversiones de Meta, explicada
La API de conversiones de Meta, explicada. El Pixel del navegador puede perder un evento. Un servidor que controlas puede enviar la misma acción, con un id compartido para que Meta la cuente una vez. Esta página construye ese JSON y se detiene.
Entender el laboratorioCómo usarlo y por qué querrías hacerlo
Por qué querrías hacerlo
Un correo y un teléfono se normalizan y se hashean en este navegador, y luego se muestran como un payload de servidor de muestra y una línea de píxel. Ambos se quedan en la página, y los datos de usuario se omiten cuando el consentimiento está apagado.
Cómo usarlo
- Mira cómo el correo y el teléfono se normalizan antes del hash.
- Con el consentimiento apagado se omiten los datos de usuario de la muestra.
- Las claves de coincidencia son los nombres de la documentación.
- El payload y la línea del píxel se quedan en esta página.
Una llamada de servidor junto al Pixel
El Meta Pixel es JavaScript en la página. Llama a Meta desde el navegador. La API de conversiones es el mismo tipo de evento, publicado por tu servidor en graph.facebook.com con un Pixel id y un access token.
Puedes ejecutar ambos. El Pixel sigue viendo la sesión del navegador. El servidor sigue viendo la acción cuando la llamada del navegador no sale del dispositivo. Meta necesita entonces una forma de distinguir esos dos informes de dos acciones distintas.
El laboratorio de lado servidor es la misma idea para un beacon de primera parte. El laboratorio de conversiones offline es el Measurement Protocol de Google. Esta página es el evento de servidor de Meta.
Por qué no basta la copia del navegador
Un bloqueador de anuncios, un navegador estricto o una cookie rechazada pueden parar el Pixel. La compra puede seguir siendo real. Un servidor que ya registró el pedido puede decírselo a Meta sin pedir al navegador que termine la llamada.
La calidad de emparejado es lo bien que Meta puede unir ese evento a una cuenta. Ayudan el correo y el teléfono hasheados. También el click id, el browser id, la dirección IP y el user agent. Un payload fino sigue llegando. Es más difícil de atribuir.
El access token se queda en el servidor. El navegador no debería verlo nunca. Hashea el correo y el teléfono una vez, antes de que Meta los vea. No hashees la IP, el user agent, fbp ni fbc.
Qué contiene el JSON
El cuerpo es data, un array de eventos. Cada evento tiene event_name, event_time en segundos unix, event_id, action_source en website, y event_source_url.
user_data.em y user_data.ph son arrays de hex SHA-256. fbp, fbc, client_ip_address y client_user_agent se envían en claro. custom_data puede llevar value y currency.
test_event_code va junto a data, no dentro del evento. Events Manager muestra esos hits en Test events. Déjalo fuera del tráfico de producción.
Prueba en seco
Elige un evento y, si quieres, escribe un correo o un teléfono. El hash se calcula en este navegador. El JSON es lo que contendría una llamada con consentimiento. No se publica nada en Meta, y la dirección y el teléfono se quedan en esta pestaña.
Normalizado y luego con hash
El correo se recorta y se pasa a minúsculas. El teléfono conserva los dígitos, quita los ceros iniciales y conserva el prefijo de país. fbp, fbc, la IP y el user agent se quedan como están. El correo y el teléfono vacíos se dejan fuera.
- Correo normalizado
- —
- SHA-256 em
- —
- Teléfono normalizado
- —
- SHA-256 ph
- —
Campos de muestra, no de este navegador: IP 203.0.113.10, fbp fb.1.1710000000000.1234567890, fbc fb.1.1710000000000.IwAR_sample_click_id. User agent: Mozilla/5.0 (compatible; CAPI-Lab-Sample/1.0). URL de la página en el payload: https://www.example.com/checkout.
Pixel
La llamada del navegador usa eventID. El evento de servidor usa event_id. El mismo valor, el mismo nombre de evento.
Conversions API
El consentimiento está activado en esta vista previa. Esta página sigue sin publicar el cuerpo.
Una acción, dos copias
Meta descarta la copia posterior cuando el evento del Pixel y el evento de servidor comparten nombre de evento y event id, llegan al mismo Pixel id y llegan en 48 horas. Si llegan en unos 5 minutos, Meta se queda con el evento del navegador.
Pixel
event Purchase
eventID …
mismo id
Conversions API
event_name Purchase
event_id …
Resultado en Events Manager: un Purchase, no dos. Dos copias solo de navegador, o dos copias solo de servidor, no se descartan con esta regla.
Lista de coincidencia
0 de 0 claves de enseñanza están presentes. Events Manager calcula el Event Match Quality. Esta lista solo indica qué campos enviaría la vista previa.
El consentimiento sigue aplicando
Un evento de servidor sigue siendo medición. Si el visitante rechazó, o Global Privacy Control está activo, no envíes el evento. No adjuntes un correo, un teléfono o un click id que no te hubieran dejado leer.
En este sitio, Google Analytics espera a Aceptar, y Global Privacy Control fuerza la medición apagada. La prueba en seco sigue el mismo interruptor para la vista previa. Nunca guarda la dirección ni el teléfono. El laboratorio de consentimiento es el control en sí.
Conversions API Gateway
Gateway es el camino alojado de Meta. Apuntas un subdominio que controlas hacia él, y el navegador puede reenviar eventos allí sin que tú ejecutes la llamada a Graph. Sigues necesitando consentimiento, y sigues compartiendo un event id con el Pixel cuando ambos están activos. La prueba en seco de arriba es la forma del payload en ambos casos. Este sitio no ejecuta un Gateway.
Muestras listas para copiar
Esto es texto. PIXEL_ID y META_CAPI_ACCESS_TOKEN son nombres para tu propio servidor. La versión de Graph en la URL es un ejemplo. Usa la versión que nombren los docs actuales de Meta. Este sitio no tiene una ruta que acepte un correo para Meta.
Node
Hashea, construye el cuerpo y para. El fetch a Graph está comentado.
// Display only. This lab does not run the request.
// Hash on your server. Keep META_CAPI_ACCESS_TOKEN off the page.
import { createHash, randomUUID } from "node:crypto"
const sha256 = (value) => createHash("sha256").update(value).digest("hex")
const email = "ada@example.com".trim().toLowerCase()
const phone = "16505551212"
const eventId = randomUUID()
const body = {
data: [
{
event_name: "Purchase",
event_time: Math.floor(Date.now() / 1000),
event_id: eventId,
action_source: "website",
event_source_url: "https://www.example.com/checkout",
user_data: {
em: [sha256(email)],
ph: [sha256(phone)],
client_ip_address: "203.0.113.10",
client_user_agent: "Mozilla/5.0 (compatible; Example/1.0)",
fbp: "fb.1.1710000000000.1234567890",
fbc: "fb.1.1710000000000.IwAR_sample_click_id",
},
custom_data: { value: 42.5, currency: "USD" },
},
],
test_event_code: "TEST12345",
}
const pixelId = process.env.PIXEL_ID
const token = process.env.META_CAPI_ACCESS_TOKEN
const url = `https://graph.facebook.com/v21.0/${pixelId}/events?access_token=${token}`
// Replace v21.0 with the version in the current Conversions API docs.
// await fetch(url, {
// method: "POST",
// headers: { "content-type": "application/json" },
// body: JSON.stringify(body),
// })
console.log(url)
console.log(JSON.stringify(body, null, 2))
Python
La biblioteca estándar hashea los mismos campos. El POST sigue comentado.
# Display only. This lab does not run the request.
# Hash before the call. Keep the token in the environment.
import hashlib, json, os, time, uuid
def sha256(value: str) -> str:
return hashlib.sha256(value.encode("utf-8")).hexdigest()
event_id = str(uuid.uuid4())
body = {
"data": [
{
"event_name": "Purchase",
"event_time": int(time.time()),
"event_id": event_id,
"action_source": "website",
"event_source_url": "https://www.example.com/checkout",
"user_data": {
"em": [sha256("ada@example.com".strip().lower())],
"ph": [sha256("16505551212")],
"client_ip_address": "203.0.113.10",
"client_user_agent": "Mozilla/5.0 (compatible; Example/1.0)",
"fbp": "fb.1.1710000000000.1234567890",
"fbc": "fb.1.1710000000000.IwAR_sample_click_id",
},
"custom_data": {"value": 42.5, "currency": "USD"},
}
],
"test_event_code": "TEST12345",
}
pixel_id = os.environ["PIXEL_ID"]
token = os.environ["META_CAPI_ACCESS_TOKEN"]
url = f"https://graph.facebook.com/v21.0/{pixel_id}/events?access_token={token}"
# Replace v21.0 with the version in the current Conversions API docs.
# urllib.request.urlopen(urllib.request.Request(
# url, data=json.dumps(body).encode(), headers={"content-type": "application/json"}, method="POST"
# ))
print(url)
print(json.dumps(body, indent=2))
Route handler de Next.js
Una ruta que alojarías tú. Devuelve el cuerpo cuando el token no está definido y no vive en este sitio.
// Display only. Do not add this file on this site.
// app/api/capi/route.ts on a server you control.
import { createHash, randomUUID } from "node:crypto"
import { NextResponse } from "next/server"
const sha256 = (value: string) => createHash("sha256").update(value).digest("hex")
export async function POST(request: Request) {
const input = (await request.json()) as {
event_name?: string
event_id?: string
email?: string
phone?: string
value?: number
currency?: string
event_source_url?: string
client_ip_address?: string
client_user_agent?: string
fbp?: string
fbc?: string
}
const email = input.email?.trim().toLowerCase()
const phone = input.phone?.replace(/\D/g, "").replace(/^0+/, "")
const eventId = input.event_id || randomUUID()
const userData: Record<string, string | string[]> = {}
if (email) userData.em = [sha256(email)]
if (phone) userData.ph = [sha256(phone)]
if (input.client_ip_address) userData.client_ip_address = input.client_ip_address
if (input.client_user_agent) userData.client_user_agent = input.client_user_agent
if (input.fbp) userData.fbp = input.fbp
if (input.fbc) userData.fbc = input.fbc
const body = {
data: [
{
event_name: input.event_name || "Purchase",
event_time: Math.floor(Date.now() / 1000),
event_id: eventId,
action_source: "website",
event_source_url: input.event_source_url,
user_data: userData,
custom_data:
input.value != null ? { value: input.value, currency: input.currency || "USD" } : undefined,
},
],
}
const pixelId = process.env.PIXEL_ID
const token = process.env.META_CAPI_ACCESS_TOKEN
if (!pixelId || !token) return NextResponse.json({ sent: false, event_id: eventId, body })
const version = "v21.0" // replace with the version in the current docs
const response = await fetch(
`https://graph.facebook.com/${version}/${pixelId}/events?access_token=${token}`,
{ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) },
)
return NextResponse.json({ sent: response.ok, event_id: eventId })
}
Fragmento de navegador
Un event id para fbq y para tu servidor. El servidor hashea. Esta página no ejecuta el fragmento.
// Display only. Send the same event_id to the Pixel and to your server.
// Your server hashes email and phone. The browser never sees the access token.
// This page does not call fbq and does not POST this body.
const eventId = crypto.randomUUID()
fbq("track", "Purchase", { value: 42.5, currency: "USD" }, { eventID: eventId })
await fetch("/api/capi", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
event_name: "Purchase",
event_id: eventId,
event_source_url: location.href,
email: "ada@example.com",
phone: "+1 650 555 1212",
value: 42.5,
currency: "USD",
fbp: document.cookie.match(/(?:^|; )_fbp=([^;]+)/)?.[1],
fbc: document.cookie.match(/(?:^|; )_fbc=([^;]+)/)?.[1],
}),
})
La misma idea en otras redes
Cada red nombra las piezas de otra forma. El patrón es una etiqueta de navegador, una llamada de servidor, un id compartido y datos de contacto hasheados.
| Red | Navegador | Servidor | Id compartido | Datos de contacto |
|---|---|---|---|---|
| Meta | Pixel | Conversions API | event_id with event_name | SHA-256 email and phone |
| gtag | Enhanced Conversions and Measurement Protocol | client_id, plus transaction_id on a purchase | SHA-256 for Enhanced Conversions | |
| TikTok | Pixel | Events API | event_id | SHA-256 email and phone |
| Insight Tag | Conversions API | a conversion event id | SHA-256 email | |
| Snapchat | Pixel | Conversions API | client_dedup_id | SHA-256 email and phone |
La documentación de Meta
RecorridoCómo lo hicimosMostrarOcultar
El ajuste de proveedor de ejemplo está marcado abajo. Los números de eVar y de event son ejemplos. Este laboratorio no llama a Adobe.
El laboratorio de Conversions API normaliza un correo y un teléfono, les hace hash en este navegador y arma un payload de servidor de muestra y una línea de píxel que se quedan en la página. El laboratorio no llama a Adobe.
Normalizar antes del hash
normalizeEmail recorta y pasa a minúsculas. normalizePhone se queda con los dígitos, quita los ceros iniciales y puede anteponer 1 a un número de Estados Unidos de 10 dígitos. sha256Hex hace hash de la cadena normalizada.
Omitir los datos de usuario cuando el consentimiento está apagado
buildCapiPreview siempre escribe event_name, event_time, event_id, action_source y la URL de origen de evento de muestra. user_data se añade solo cuando consentGranted es true.
Usar claves de coincidencia de la documentación
Los datos de usuario rellenos usan la IP de la documentación, un user agent de muestra, un fbp de muestra y un fbc de muestra. Los hashes de correo y teléfono se añaden solo cuando los campos tienen valor. Este sitio no fija fbp ni fbc.
Dejar el payload en la página
Value y currency se añaden para ViewContent, AddToCart y Purchase. Un test event code se copia cuando el campo está relleno. La línea del píxel es una cadena. Este componente no llama a trackLabEvent y no hace POST del payload.
Del código
Normalizar, hacer hash y luego el objeto del evento. user_data se añade después, y solo con consentimiento.
export async function buildCapiPreview(draft: CapiDraft): Promise<CapiBuild> {
const normalizedEmail = normalizeEmail(draft.email)
const normalizedPhone = normalizePhone(draft.phone, draft.usCountryCode)
const emailHash = normalizedEmail ? await sha256Hex(normalizedEmail) : null
const phoneHash = normalizedPhone ? await sha256Hex(normalizedPhone) : null
const phoneNeedsCountry = Boolean(normalizedPhone && normalizedPhone.length === 10)
const currency = draft.currency.trim().toUpperCase() || "USD"
const includeValue = VALUE_EVENTS.has(draft.eventName) && Number.isFinite(draft.value)
const event: Record<string, unknown> = {
event_name: draft.eventName,
event_time: draft.eventTime,
event_id: draft.eventId,
action_source: "website",
event_source_url: DOC_URL,
}El consentimiento rellena las claves de coincidencia de muestra. La cadena del píxel no se envía.
if (draft.consentGranted) {
const userData: Record<string, string | string[]> = {
client_ip_address: DOC_IP,
client_user_agent: DOC_UA,
fbp: DOC_FBP,
fbc: DOC_FBC,
}
if (emailHash) userData.em = [emailHash]
if (phoneHash) userData.ph = [phoneHash]
event.user_data = userData
}
if (includeValue) event.custom_data = { value: draft.value, currency }
const payload: CapiBuild["payload"] = { data: [event] }
const testEventCode = draft.testEventCode.trim()
if (testEventCode) payload.test_event_code = testEventCode
const custom = includeValue ? `, {value: ${draft.value}, currency: "${currency}"}` : ""
const pixel = `fbq("track", "${draft.eventName}"${custom}, {eventID: "${draft.eventId}"});`Google y Adobe
Este laboratorio no encola un evento propio. El bloque de Google muestra un ejemplo de cómo rastrearías la interacción. Adobe también es un ejemplo.
Este laboratorio no encola un evento de analítica propio. Después de Aceptar, el sitio sigue encolando virtual_page_view de la página, con page_path y page_title. Los clics dentro de una región data-track-ignore no se registran. El push de abajo es un ejemplo, no una llamada de esta página. Este sitio no llama a gtag('set') ni a Adobe.
Solo ejemplo. Esta página no hace push de este objeto.
// Example only. This lab does not queue this event.
dataLayer.push({
event: "capi_preview_example",
event_name: "Purchase",
withheld: true,
})Implementación de ejemplo. Este sitio no llama a Adobe. eVar54, prop54 y event54 son números de variable de ejemplo. En Launch, un elemento de datos lee el valor y una regla lo envía cuando el valor cambia. En el report suite, habilita eVar54 con asignación Most Recent y haz que expire en el hit. Una processing rule no hace falta si el elemento de datos se mapea directo a esa eVar.
Payload de alloy de ejemplo. _example es un esquema de relleno, no un inquilino real.
alloy("sendEvent", {
xdm: {
eventType: "web.webinteraction.linkClicks",
_example: {
capiEvent: "Purchase",
},
},
})Hit de ejemplo. eVar54 tiene alcance de hit en este ejemplo. prop54 muere en el mismo hit.
s.eVar54 = "Purchase"
s.prop54 = "Purchase"
s.events = "event54"
s.linkTrackVars = "eVar54,prop54,events"
s.linkTrackEvents = "event54"
s.tl(true, "o", "capi_preview_example")Traducción
Cada campo del laboratorio, el nombre en GA4 y la variable de Adobe de ejemplo. El alcance es la parte que suele perderse en la traducción.
Nombre del evento
GA4. No se envía. El event_name de la vista previa es PageView, ViewContent, AddToCart, Purchase o Lead.
Adobe. eVar54 de ejemplo, expira en el hit.
Alcance. Hit. Un nombre de evento con alcance de usuario se quedaría después de la vista previa.
Id de evento
GA4. No se envía. La vista previa lo comparte entre el payload y la cadena del píxel.
Adobe. prop54 de ejemplo, que muere en el hit.
Alcance. Hit. El id es un sello aleatorio de esta vista previa, no un pedido guardado.
Correo con hash
GA4. No se envía. em es un SHA-256 en el payload solo cuando el consentimiento está encendido y el campo está relleno.
Adobe. Ejemplo: no copies el hash en eVar54.
Alcance. Ni un parámetro de evento ni una propiedad de usuario. Se queda en la vista previa.
Consentimiento
GA4. No se envía. Con el consentimiento apagado se omite user_data y el armado queda retenido.
Adobe. prop54 de ejemplo si enviaras withheld. No se envía.
Alcance. Una compuerta de esta vista previa. No es una propiedad de la visita.
Recomendado a continuación
Por qué estas propuestasLeyendo las transiciones de recorrido…