Enviar eventos offline con la API de conversiones

La API de conversiones es el método de integración recomendado por Meta para enviar eventos offline y de la tienda física a Meta para usarlos en la medición, la atribución y la segmentación de anuncios. En esta página se detalla cómo enviar eventos offline mediante una integración directa o con socios de la API de conversiones.

Requisitos previos

Conjunto de datos

Los eventos offline enviados mediante la API de conversiones deben estar asociados a un conjunto de datos.

Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up:

Meta Pixel (website events)
App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs))
Offline Conversions API (Meta’s legacy API for offline events)
Messaging Events API (messaging events)

Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations.

In Events Manager, advertisers have different options to create a dataset depending on their starting point. Or you can create a brand new dataset in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more details and instructions here.

Puedes hacer la llamada GET a https://graph.facebook.com/v16.0/{ads-pixel-id}/?fields=is_consolidated_container para detectar si el conjunto de datos del anunciante está consolidado y, por lo tanto, cumple los requisitos para pasar eventos offline con la API de conversiones.

Permisos

Para implementar una integración directa como anunciante, consulta los requisitos previos y los permisos en estas instrucciones.
Para implementar la integración de la plataforma de socios, consulta los requisitos previos y los permisos en estas instrucciones.

Configuración

1. Configurar los parámetros de los eventos offline

Los anunciantes pueden usar la configuración mencionada aquí y consultar el conjunto actual de parámetros que se pueden enviar mediante la API de conversiones. Para enviar eventos offline y de la tienda, se pueden compartir los siguientes campos en la carga útil:

Los anunciantes deben enviar action_source como physical_store para todos los eventos offline y de la tienda. Ten en cuenta que este parámetro es obligatorio para todos los tipos de eventos del servidor. Al utilizar la API de conversiones, aceptas que el parámetro action_source es adecuado hasta donde tú sabes.
Se deben respetar todos los campos de los eventos del servidor obligatorios para la API de conversiones.
Parámetros de información del cliente (consulta a continuación la lista adecuada de parámetros de los eventos offline y de la tienda).
Parámetros de datos personalizados (consulta a continuación la lista adecuada de parámetros de los eventos offline y de la tienda).
Parámetro opcional: el parámetro upload_tag se sigue admitiendo con las subidas de eventos offline para anunciantes que usan la API heredada para eventos offline.

Parámetros de información del cliente

En la siguiente lista se incluyen los parámetros de información del cliente que se suelen usar para los eventos offline y de la tienda:

Nombres de los parámetros	Parámetro	Cifrado obligatorio
Direcciones de correo electrónico	`email`	SÍ
Números de teléfono	`phone`	SÍ
Género	`gen`	SÍ
Fecha de nacimiento	`db`	SÍ
Apellidos	`ln`	SÍ
Nombre	`fn`	SÍ
Ciudad	`ct`	SÍ
Estados de EE. UU.	`st`	SÍ
Códigos postales	`zip`	SÍ
País	`country`	SÍ
Identificador de publicidad de Apple	`madid`	SÍ
Identificador de publicidad de Android	`madid`	SÍ
Identificador de usuario de terceros	`external_id`	Altamente recomendado
Identificador de cliente potencial de los anuncios para este tipo de clientes	`lead_id`	NO aplicar hash

Parámetros de datos personalizados

En la siguiente sección se incluyen los parámetros personalizados comunes que utilizan los eventos offline y de la tienda. Consulta otros campos de datos personalizados en la lista completa que aceptamos para la API de conversiones en el siguiente enlace.

Parámetro Descripción

Parámetro	Descripción
`event_time` Tipo: entero	Obligatorio. Marca de tiempo UNIX del evento de conversión. Ejemplo: `'1456870055'`
`event_name` Tipo: cadena	Obligatorio. Tipo de evento. Ejemplo: `ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other`
`store_data` Tipo: diccionario JSON	Opcional. Almacena los datos de ubicación sobre el evento de conversión. Ejemplo: "store_data": { "store_page_id": 8576093908, // FBID "brand_page_id": 10236898932// FBID }
`currency` Tipo: cadena	Obligatorio. Código de divisa ISO de tres letras de este evento de conversión. Obligatorio para los eventos `Purchase`. Ejemplo: `USD`
`value` Tipo: doble	Obligatorio. Valor del evento de conversión. Obligatorio para los eventos `Purchase`. Ejemplo: `16.00`
`content_type` Tipo: cadena	Opcional. Cualquier valor de `content_type` válido de los anuncios de catálogo de Advantage+. Ejemplo: `product`
`contents` Tipo: matriz JSON	Opcional. Obligatorio si integras los anuncios con el catálogo. Obligatorios: `id`, `quantity` Recomendados: `price`, `brand`, `category` Obligatorios: `[ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]` Recomendados: `[ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]`
`custom_data` Tipo: diccionario JSON	Opcional. Información sobre este evento de conversión Ejemplo: `{category: 'ICECREAM'}`
`order_id` Tipo: cadena	Opcional. Identificador único de cada transacción o pedido en un conjunto de eventos offline. Por ejemplo, para el comercio minorista, este puede ser un identificador de recibo. Ejemplo: `ATN10001`, `123456`
`item_number` Tipo: cadena	Opcional. Identificador único para distinguir los eventos del mismo pedido o la misma transacción. Ejemplo: `1`, `a`

event_time

Tipo: entero

Obligatorio.

Marca de tiempo UNIX del evento de conversión.

Ejemplo:
'1456870055'

event_name
Tipo: cadena

Obligatorio.

Tipo de evento.

Ejemplo:
ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other

store_data
Tipo: diccionario JSON

Opcional.

Almacena los datos de ubicación sobre el evento de conversión.

Ejemplo:

"store_data":
    {
        "store_page_id": 8576093908, // FBID
        "brand_page_id": 10236898932// FBID
    }

currency
Tipo: cadena

Obligatorio.

Código de divisa ISO de tres letras de este evento de conversión. Obligatorio para los eventos Purchase.

Ejemplo:
USD

value
Tipo: doble

Obligatorio.

Valor del evento de conversión. Obligatorio para los eventos Purchase.

Ejemplo:
16.00

content_type Tipo: cadena

Opcional.

Cualquier valor de content_type válido de los anuncios de catálogo de Advantage+.

Ejemplo:
product

contents

Tipo: matriz JSON

Opcional. Obligatorio si integras los anuncios con el catálogo.

Obligatorios: id, quantity

Recomendados: price, brand, category

Obligatorios: [ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]

Recomendados: [ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]

custom_data

Tipo: diccionario JSON

Opcional.

Información sobre este evento de conversión

Ejemplo: {category: 'ICECREAM'}

order_id

Tipo: cadena

Opcional.

Identificador único de cada transacción o pedido en un conjunto de eventos offline. Por ejemplo, para el comercio minorista, este puede ser un identificador de recibo.

Ejemplo: ATN10001, 123456

item_number

Tipo: cadena

Opcional.

Identificador único para distinguir los eventos del mismo pedido o la misma transacción.

Ejemplo: 1, a

2. Enviar eventos

Para enviar nuevos eventos, haz una solicitud POST a la API de conversiones desde esta ruta: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}.

Al realizar una publicación en este perímetro, Meta crea nuevos eventos offline y de la tienda. Para obtener más información, consulta el siguiente documento para desarrolladores.

A continuación se ofrece información general sobre cómo se ajustan los parámetros al esquema general de la carga útil:

curl -X POST \
  -F 'data=[
       {
  "event_name": "Purchase",
  "event_time": 1674000041,
  "user_data": {
    "em": [
      "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
    ],
    "ph": [
      "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
      "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
    ]
  },
  "custom_data": {
    "currency": "usd",
    "value": 123.45,
    "contents": [{
      "id": "product123",
      "quantity": 1
    }]
  },
  "action_source": "physical_store"
}
]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v15.0/<DATASET_ID>/events

Te recomendamos llevar a cabo la subidas en tiempo real o diariamente para obtener resultados óptimos de optimización, de modo que los datos offline puedan compararse de manera efectiva con el rendimiento de cualquier anuncio que hayas publicado.

El valor de event_time puede ser hasta siete días antes del envío de un evento a Meta. Si algún valor de event_time en data es de hace más de siete días, se devuelve un error para la toda la solicitud y no se procesa ningún evento. En el caso de los eventos offline y de la tienda física con physical_store como action_source, debes subir las transacciones en los 62 días posteriores a la conversión.

Como los datos que subes se procesan en tiempo real, normalmente podrás ver los resultados en cuanto los añadas. Puedes consultar el documento del Servicio de ayuda sobre las prácticas recomendadas para datos de eventos offline.

3. Configurar la eliminación de duplicados

A diferencia de la eliminación de duplicados configurada en los eventos de la API de conversiones y el píxel de Meta, los eventos offline duplicados pueden eliminarse solo en relación con otros eventos offline. Admitimos dos métodos de eliminación de duplicados: la eliminación basada en order_id o basada en el usuario. La eliminación de duplicados utiliza la combinación de campos dataset_id, event_time, event_name, item_number y el campo de la clave en función del método de la carga útil del evento específico.

La eliminación de duplicados predeterminada utiliza order_id con una combinación de los campos anteriores. Si order_id no está en la carga útil, se usará la lógica de la eliminación de duplicados basada en el usuario.

Por ejemplo, cuando haya dos pedidos con valores idénticos de event_time, event_name con el mismo valor de order_id o el mismo conjunto de parámetros de información del cliente sin order_id, los consideraremos eventos duplicados y tomaremos el primer evento. El método de eliminación de duplicados basado en el usuario solo funciona con los mismos campos de parámetros de información del cliente en las dos cargas útiles.

El intervalo máximo de eliminación de duplicados es de siete días.

4. Solucionar problemas de eventos

Puedes usar el asistente de carga útil para generar datos de cargas útiles:

Elige el origen de acción physical_store cuando proceda. Al utilizar la API de conversiones, aceptas que el parámetro action_source es adecuado hasta donde tú sabes.
Rellena la información de los eventos que se enviarán a Meta.
De esta forma, se generará la carga útil de los eventos, que se puede usar como plantilla para la integración de la API de conversiones.

Utiliza la herramienta para probar eventos en el Administrador de eventos con fines de pruebas. Ten en cuenta que la herramienta para probar eventos solo admite eventos web y de la aplicación.

Enviar eventos offline con la API de conversiones

Requisitos previos

Conjunto de datos

Permisos

Configuración

1. Configurar los parámetros de los eventos offline

Parámetros de información del cliente

Parámetros de datos personalizados

2. Enviar eventos

3. Configurar la eliminación de duplicados

4. Solucionar problemas de eventos

Más información

Artículos del Servicio de ayuda para empresas