Cuando cumplas con los requisitos de la página Empezar, consulta esta página para saber cómo enviar eventos y usar la herramienta para probar eventos. Cuando hayas enviado un evento, verifica tu configuración.
La API de conversiones se basa en la API de marketing de Facebook, que, a su vez, se creó a partir de nuestra API Graph. Las API Graph y de marketing tienen diferentes calendarios de obsolescencia según las versiones. Nuestro ciclo de lanzamiento está alineado con la API Graph, para que todas las versiones sean compatibles al menos durante dos años. Esta excepción solo es válida para la API de conversiones.
Información general de la API de conversionesParámetrosLos eventos de la web, las apps y los negocios físicos compartidos mediante la API de conversiones requieren parámetros específicos. Si usas la API de conversiones, aceptas que el parámetro action_source
es preciso, según tus conocimientos. La lista de parámetros obligatorios está disponible aquí.
Para enviar eventos nuevos, haz una solicitud POST
al perímetro /events
de la API desde esta ruta: https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}
. Cuando realizas una publicación en este perímetro, Facebook crea nuevos eventos del servidor.
curl -X POST \
-F 'data=[
{
"event_name": "Purchase",
"event_time": 1732198476,
"user_data": {
"em": [
"309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
],
"ph": [
"254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
"6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
],
"client_ip_address": "123.123.123.123",
"client_user_agent": "$CLIENT_USER_AGENT",
"fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
"fbp": "fb.1.1558571054389.1098115397"
},
"custom_data": {
"currency": "usd",
"value": 123.45,
"contents": [
{
"id": "product123",
"quantity": 1,
"delivery_category": "home_delivery"
}
]
},
"event_source_url": "http://jaspers-market.com/product/123",
"action_source": "website"
}
]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/<PIXEL_ID>/events
Adjunta el token de acceso seguro que generaste usando el parámetro de consulta access_token
. También puedes usar el explorador de la API Graph para realizar la solicitud POST
en el punto de conexión /<pixel_id>/events
.
El cuerpo de una solicitud de ejemplo tiene este aspecto:
{ "data": [ { "event_name": "Purchase", "event_time": 1633552688, "event_id": "event.id.123", "event_source_url": "http:\/\/jaspers-market.com\/product\/123", "action_source": "website", "user_data": { "client_ip_address": "192.19.9.9", "client_user_agent": "test ua", "em": [ "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd" ], "ph": [ "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4", "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6" ], "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890", "fbp": "fb.1.1558571054389.1098115397" }, "custom_data": { "value": 100.2, "currency": "USD", "content_ids": [ "product.id.123" ], "content_type": "product" }, "opt_out": false }, { "event_name": "Purchase", "event_time": 1633552688, "user_data": { "client_ip_address": "192.88.9.9", "client_user_agent": "test ua2" }, "custom_data": { "value": 50.5, "currency": "USD" }, "opt_out": false } ] }
event_time
es la fecha de transacción del evento. Se debe enviar como una marca de tiempo Unix en segundos que indique el momento en que ocurrió el evento. El tiempo especificado puede ser anterior al momento en que se envió el evento a Facebook. Esto permite procesar por lotes y optimizar el rendimiento del servidor.
event_time
puede ser hasta 7 días antes de que envíes un evento a Meta. Si un event_time
en data
excede los 7 días pasados, devolvemos un error para toda la solicitud y no procesamos ningún evento. En el caso de los eventos offline y de tienda física con physical_store
como action_source
, debes subir las transacciones dentro de los 62 días posteriores a la conversión.
Si usas la API de conversiones, aceptas que el parámetro action_source
es preciso, según tus conocimientos.
Puedes enviar hasta 1,000 eventos en data
. Sin embargo, para un rendimiento óptimo, te recomendamos que envíes los eventos cuando se produzcan, e idealmente dentro de la hora posterior al momento en que ocurran. Si alguno de los eventos que envías en un lote no es válido, rechazaremos todo el lote.
Consulta nuestra página parámetros de información de los clientes para ver qué parámetros deben cifrarse antes de enviarlos a Facebook. Si estás usando uno de nuestros SDK para empresas, el SDK realiza el cifrado por ti.
Obtén más información sobre tres funciones específicas del SDK para empresas diseñadas especialmente para usuarios de la API de conversiones: Solicitudes asincrónicas, Creación simultánea de lotes e Interfaz de servicio HTTP. La versión mínima requerida para usar estas características es la siguiente:
El SDK para empresas dejó de ser compatible con PHP 5 desde enero de 2019. Para usar el SDK para empresas, actualiza a PHP 7.
Si debes usar PHP 5, considera usar nuestra implementación de Swagger.
Después de enviar tus eventos, confirma haberlos recibido en el administrador de eventos:
PIXEL_ID
de tu solicitud POST
. Para obtener más información, consulta Servicio de ayuda para empresas: Explorar el administrador de eventos.Puedes verificar que Facebook haya recibido correctamente los eventos de tu servidor mediante la función "Probar eventos" en el administrador de eventos. Para encontrar la herramienta, ve a Events Manager > Data Sources > Your Pixel > Test Events
.
La herramienta "Probar eventos" genera un identificador de prueba. Envía el identificador de prueba como un parámetro test_event_code
para empezar a ver la actividad del evento en la ventana de la herramienta "Probar eventos".
Nota: El campo test_event_code
solo debe usarse para realizar pruebas. Es necesario que lo elimines cuando envías tu carga de producción.
Los eventos que envías con test_event_code
no se omiten. Ingresan en el administrador de eventos y se usan para segmentar y medir anuncios.
Este es un ejemplo de cómo se debe estructurar la solicitud:
Este es un ejemplo de cómo aparece la solicitud en el explorador de la API Graph:
Puedes generar esta carga de prueba usando el asistente de cargas. Ten en cuenta que el código del evento de prueba solo es válido para la carga de prueba.
Los eventos de tu servidor aparecen en la ventana "Probar eventos" una vez que se envía la solicitud.
En estas dos API, implementa opciones de procesamiento de datos agregando data_processing_options
, data_processing_options_country
y data_processing_options_state
en cada evento dentro del parámetro de datos de los eventos.
Nota: Ya no se recomiendan las API de eventos de la app y de conversiones offline para realizar las nuevas integraciones. En cambio, sí se recomienda que uses la API de conversiones, porque ahora admite eventos offline, de la web y de la app. Consulta la API de conversiones de eventos de la app y la API de conversiones de eventos offline para obtener más información.
Si no deseas activar el uso limitado de datos (LDU), especifica una matriz vacía relacionada con los eventos o, simplemente, elimina el campo en la carga útil:
{ "data": [ { "event_name": "Purchase", "event_time": <EVENT_TIME>, "user_data": { "em": "<EMAIL>" }, "custom_data": { "currency": "<CURRENCY>", "value": "<VALUE>" }, "data_processing_options": [] } ] }
Para activar el LDU y que Meta realice la geolocalización:
{ "data": [ { "event_name": "Purchase", "event_time": <EVENT_TIME>, "user_data": { "em": "<EMAIL>", "client_ip_address": "256.256.256.256" }, "custom_data": { "currency": "<CURRENCY>", "value": "<VALUE>" }, "data_processing_options": ["LDU"], "data_processing_options_country": 0, "data_processing_options_state": 0 } ] }
Para activar el LDU y especificar manualmente la ubicación, por ejemplo, California:
{ "data": [ { "event_name": "Purchase", "event_time": <EVENT_TIME>, "user_data": { "em": "<EMAIL>" }, "custom_data": { "currency": "<CURRENCY>", "value": "<VALUE>" }, "data_processing_options": ["LDU"], "data_processing_options_country": 1, "data_processing_options_state": 1000 } ] }
La API de conversiones offline ofrece la opción de subir los eventos de forma manual desde un archivo .csv
. En este caso, las opciones de procesamiento de datos, el país de procesamiento de datos y el estado de procesamiento de datos se agregan como columnas en el archivo. Puedes obtener más información al respecto en la interfaz de usuario de subida.
Obtén más información sobre las opciones de procesamiento de datos.
La API de marketing posee una lógica de limitación de frecuencia propia y es independiente de todas las limitaciones de frecuencia de la API Graph. Por lo tanto, si realizas una llamada a la API de marketing, no se tomará en cuenta para la limitación de la API Graph.
La API de conversiones no tiene un límite de frecuencia específico. Las llamadas a la API de conversiones se consideran como llamadas a la API de marketing. La única limitación es que puedes enviarnos hasta 1.000 eventos a la vez. Consulta Enviar solicitudes para obtener más información.
Limitación de frecuencia de la API de marketingEsta guía te ayudará a explorar las funciones avanzadas del SDK de Meta para empresas, que se diseñaron específicamente para los usuarios del gateway de la API de conversiones. Para obtener información sobre el uso básico del gateway de la API de conversiones, consulta la documentación de este gateway.
Para poder usar cualquiera de las funciones que se enumeran a continuación, debes tener instalado el SDK de Meta para empresas. Consulta Primeros pasos con el SDK de Meta para empresas o sigue las instrucciones del archivo README, que se enumeran aquí:
Por el momento, estas funciones solo están disponibles en el SDK para empresas de PHP y Java. Los otros lenguajes se implementarán a finales de 2023.
Las versiones de lenguaje mínimas obligatorias para usar estas funciones son las siguientes:
PHP >= 7.2
Java >= 8
Nota: Para deduplicar eventos en el punto de conexión de la API de conversiones, pasa el eventId
en tu solicitud. Esto evitará que se muestren eventos deduplicados si se activó la publicación de la API de conversiones.
CAPIGatewayIngressRequest
Parámetro | Descripción |
---|---|
endpointUrl Cadena | El punto de conexión del gateway de la API de conversiones al que se envían los eventos. No se realizará ninguna validación previa, pero sí se verificará si la URL es válida. Ejemplo: https://test.example.com |
accessKey Cadena | La clave de acceso del gateway de la API de conversiones. Esta clave se necesita para enviar eventos al punto de conexión de eventos del gateway de la API de conversiones. Estas son las instrucciones que debes seguir para generarla. |
CAPIGatewayIngressRequest
Parámetro | Descripción |
---|---|
setSendToDestinationOnly Booleano | Indicador booleano que determina si los eventos se envían únicamente al punto de conexión seleccionado. Valor predeterminado: |
setFilter Función CustomEndpointRequest.Filter() | Función de filtro que procesa cada evento. Si la lógica de filtrado es verdadera, se pasa el evento. De lo contrario, el evento se cancela. Debes implementar la función shouldSendEvent en la interfaz que tiene el parámetro Event. Valor predeterminado: |
En el caso de los sistemas que ya utilizan el SDK para empresas, solo debes consultar la nueva CAPIGatewayIngressRequest y adjuntarla al objeto customEndpoint de eventRequest.
// this is the standard event request that we attach events to $event_request = new EventRequest($this->pixel_id); $capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); $event_request->setCustomEndpoint($capiIngressRequest); // pass the events to this event Request object $event_request->setEvents($events); $event_request->execute()
En el caso de los sistemas que ya utilizan el SDK para empresas, solo debes consultar la nueva CAPIGatewayIngressRequest y adjuntarla al objeto customEndpoint de eventRequest.
// this is the standard event request that we attach events to EventRequest eventRequest = new EventRequest(PIXEL_ID, context); CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); eventRequest.setCustomEndpoint(capiSyncRequest); eventRequest.addDataItem(testEvent); eventRequest.execute();
$api = Api::init(null, null, $this->access_token); $api->setLogger(new CurlLogger()); $event_request = new EventRequest($this->pixel_id); $capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); $event_request->setCustomEndpoint($capiIngressRequest); $user_data = (new UserData()) ->setEmails(array('joe@eg.com')) ->setPhones(array('12345678901', '14251234567')) ->setFbc('fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890') ->setFbp('fb.1.1558571054389.1098115397'); $event1 = (new Event()) ->setEventName('Purchase') ->setEventId('125') ->setEventTime(time()) ->setEventSourceUrl('http://jaspers-market.com/product/123') ->setUserData($user_data); $events = array($event1, $event2); $event_request->setEvents($events); $response = $event_request->execute(); print($response->__toString());
EventRequest eventRequest = new EventRequest(PIXEL_ID, context); UserData userData = new UserData() .email("abc@eg.com"); CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); eventRequest.setCustomEndpoint(capiSyncRequest); Event testEvent = new Event(); testEvent.eventId("125").eventName("Purchase") .eventTime(System.currentTimeMillis() / 1000L) .userData(userData) .dataProcessingOptions(new String[]{}).setEventId("134423232"); eventRequest.namespaceId("11") .uploadId("22222") .uploadTag("upload-tag-4") .uploadSource("upload-source-4") .testEventCode("test-event-code-5") .partnerAgent("partner-agent-6"); eventRequest.addDataItem(testEvent); eventRequest.execute();
$api = Api::init(null, null, $this->access_token); $api->setLogger(new CurlLogger()); $event_request = new EventRequestAsync($this->pixel_id); $capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); $capiIngressRequest->setSendToDestinationOnly(true); $event_request->setCustomEndpoint($capiIngressRequest); $event1 = (new Event()) ->setEventName('test Async Event') ->setEventId('134423232') ->setEventTime(time()) ->setEventSourceUrl('http://jaspers-market.com/product/123'); $events = array($event1, $event2); $event_request->setEvents($events); $response = $event_request->execute()->wait();
EventRequest eventRequest = new EventRequest(PIXEL_ID, context); UserData userData = new UserData() .email("abc@eg.com"); CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); capiSyncRequest.setSendToDestinationOnly(true); eventRequest.setCustomEndpoint(capiSyncRequest); Event testEvent = new Event(); testEvent.eventName("test Async Event") .eventTime(System.currentTimeMillis() / 1000L) .userData(userData) .dataProcessingOptions(new String[]{}).setEventId("134423232"); eventRequest.namespaceId("11222") .uploadId("22222") .uploadTag("upload-tag-4") .uploadSource("upload-source-4") .testEventCode("test-event-code-5") .partnerAgent("partner-agent-6"); eventRequest.addDataItem(testEvent); eventRequest.executeAsync();
lass APIFilter implements Filter { public function shouldSendEvent(Event $event): bool { if ($event->getEventId() === '125') { return false; } return true; } } $capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); $event_request->setCustomEndpoint($capiIngressRequest); $capiIngressRequest->setFilter(new APIFilter());
CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); eventRequest.setCustomEndpoint(capiSyncRequest); capiSyncRequest.setFilter(new CustomEndpointRequest.Filter() { @Override public boolean shouldSendEvent(Event event) { if (event.getEventId().equals("125")) { return true; } return false; } });