API de conversiones para eventos de la aplicación

La API de conversiones permite a los anunciantes enviar eventos de la web, de la aplicación, de la tienda física y de mensajes empresariales a Meta mediante un extremo único y no mediante varios orígenes. Esta consolidación simplificará la pila de tecnología de un anunciante y creará una vista más completa en el Administrador de eventos de Meta gracias al uso de conjuntos de datos.

En esta documentación se proporciona orientación para integrar los eventos de la aplicación en la API de conversiones.

Requisitos previos

1. Conjunto de datos

Los eventos de la aplicación 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}/is_consolidated_container para detectar si el conjunto de datos del anunciante está consolidado y, por lo tanto, cumple los requisitos para pasar eventos de la aplicación mediante la API de conversiones.

2. 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

Enviar eventos de la aplicación a la API de conversiones

a. Vincular el identificador del conjunto de datos y el identificador de la aplicación

En el Administrador de eventos, hay dos formas de vincular la aplicación con un conjunto de datos:

Selecciona la pestaña “Orígenes de datos”, busca la pestaña “Configurar” de la aplicación y lleva a cabo la vinculación.
Selecciona la pestaña “Orígenes de datos” y, en la pestaña “Información general” de la aplicación, usa el botón “Vincular con conjunto de datos” en la sección “Toda la actividad”.

Una vez que completes la vinculación, el conjunto de datos incluye la aplicación conectada.

b. Campos obligatorios

Puedes consultar el conjunto actual de parámetros que se pueden enviar mediante la API de conversiones aquí. Para enviar eventos de la aplicación, los siguientes campos de server_event se pueden compartir en la carga útil:

El parámetro action_source debe contener el valor app para los eventos de la aplicación.
El valor de event_id es obligatorio para el caso de configuración de la eliminación de duplicados.
Campos de app_data
Campos de user_data
Campos de custom_data

Campos de datos de la aplicación

Parameter	Description
`advertiser_tracking_enabled` boolean	Required for app events Use this field to specify ATT permission on an iOS 14.5+ device. Set to `0` for disabled or `1` for enabled.
`application_tracking_enabled` boolean	Required for app events A person can choose to enable ad tracking on an app level. Your SDK should allow an app developer to put an opt-out setting into their app. Use this field to specify the person's choice. Use `0` for disabled, `1` for enabled. `
`extinfo` object Please use the down arrow to the right to see the list of `extinfo` values.	Required for app events Extended device information, such as screen width and height. This parameter is an array and values are separated by commas. When using `extinfo`, all values are required and must be in the order indexed below. If a value is missing, fill with an empty string as a placeholder. Note: `version` must be `a2` for Android `version` must be `i2` for iOS
`0` string	Required extinfo version Example: `i2`
`1` string	app package name Example: `com.facebook.sdk.samples.hellofacebook`
`2` string	short version (int or string) Example: `1.0`
`3` string	long version Example: `1.0 long`
`4` string	Required OS version Example: `13.4.1`
`5` string	device model name Example: `iPhone5,1`
`6` string	locale Example: `En_US`
`7` string	timezone abbreviation Example: `PDT`
`8` string	carrier Example: `AT&T`
`9` string	screen width Example: `320`
`10` string	screen height Example: `568`
`11` string	screen density Example: `2`
`12` string	CPU cores Example: `2`
`13` string	external storage size in GB Example: `13`
`14` string	free space on external storage in GB Example: `8`
`15` string	device timezone Example: `USA/New York`
`campaign_ids` string	Optional An encrypted string and non-user metadata appended to the outbound URL (for example, ad_destination_url) or deep link (for App Aggregated Event Manager) when a user clicked on a link from Facebook. Graph API definition: Parameter passed via the deep link for Mobile App Engagement campaigns.
`install_referrer` string	Optional Third party install referrer, currently available for Android only, see here for more.
`installer_package` string	Optional Used internally by the Android SDKs
`url_schemes` array	Optional Used internally by the iOS and Android SDKs.
`windows_attribution_id` string	Optional Attribution token used for Windows 10.

Parámetros de información del cliente

Parámetro	Descripción
`anon_id` Cadena	No aplicar algoritmos hash. Identificador de descarga. Este campo representa instancias únicas de descarga de aplicaciones.
`madid` Cadena	No aplicar algoritmos hash. El identificador de anunciante en móviles, el de publicidad de un dispositivo Android o el de publicidad de un dispositivo Apple (IDFA).

Datos personalizados

Parámetro	Descripción
`description` Cadena	Opcional. Cadena, descripción del evento, personalizado.
`level` Cadena	Opcional. Cadena, nivel de un juego, personalizado.
`max_rating_value`	Opcional. Largo, límite superior de una escala de calificación (por ejemplo, “5” en una escala de cinco estrellas), personalizado.
`success` Booleano	Opcional. `1` para sí y `0` para no, personalizado.

En resumen, los eventos de la aplicación compartidos con la API de conversiones requerirán los siguientes parámetros de datos:

action_source: debe establecerse en “app”. (Al utilizar la API de conversiones, aceptas que el parámetro action_source es adecuado hasta donde tú sabes).
event_id: obligatorio para la configuración de la eliminación de duplicados; obtén más información en la sección “Configurar la eliminación de duplicados para varios canales”.
advertiser_tracking_enabled
application_tracking_enabled
extinfo

A continuación se incluye un ejemplo de extinfo. Asegúrate de que todos los subparámetros siguientes estén rellenados y en orden secuencial. Si falta algo, usa una cadena vacía como marcador de posición.

Nombre del subparámetro	¿Obligatorio?	Tipo de datos	Ejemplo
versión de extinfo	Sí	Cadena	`i2` (la versión debe ser a2 para Android e i2 para iOS)
nombre del paquete de aplicaciones	No	Cadena	`com.facebook.sdk.samples.hellofacebook`
versión corta	No	Cadena	`1.0`
versión larga	No	Cadena	`1.0 long`
versión de SO	Sí	Cadena	`13.4.1`
nombre del modelo de dispositivo	No	Cadena	`iPhone5,1`
configuración regional	No	Cadena	`En_US`
abreviatura de la zona horaria	No	Cadena	`PDT`
operador	No	Cadena	`AT&T`
ancho de la pantalla	No	Cadena	`320`
alto de la pantalla	No	Cadena	`568`
densidad de la pantalla	No	Cadena	`2`
núcleo de la CPU	No	Cadena	`2`
tamaño de almacenamiento externo	No	Cadena	`13`
espacio libre en el tamaño de almacenamiento externo	No	Cadena	`8`
zona horaria del dispositivo	No	Cadena	`USA/New York`

c. Configurar la eliminación de duplicados para varios canales

El mecanismo de eliminación de duplicados será necesario para eliminar el tráfico de eventos duplicados entre la integración de la API de conversiones y todas las demás integraciones existentes que tengas con eventos de la aplicación, incluido el SDK, los MMP y la API de eventos de la aplicación.

Para los eventos de la aplicación, aplicamos la misma funcionalidad de eliminación de duplicados que existe para los eventos web. La lógica usa la eliminación de duplicados basada en el campo event_id y event_name (eventos de la API de conversiones y el SDK o la API de eventos de la aplicación que llevan el mismo valor de event_id). El parámetro event_id es un identificador que puede distinguir de forma única entre eventos similares. Los identificadores de eventos incorrectos pueden causar la eliminación errónea de duplicados de la conversión, lo que tiene un impacto en los informes de conversiones y el rendimiento de las campañas.

Puedes consultar la siguiente documentación para desarrolladores si quieres implementar la configuración de la eliminación de duplicados:

A continuación se incluye un ejemplo de cómo registrar un evento personalizado. Para ello, pasa el nombre del evento como AppEvents.Name en el SDK para iOS:

AppEvents.shared.logEvent(.achievedLevel, parameters: [AppEvents.ParameterName(rawValue: "event_id"): "123"])

Para los eventos de descarga de aplicación, ya existe un mecanismo de eliminación de duplicados que asegura que solo se atribuya una descarga en el intervalo de los últimos 90 días. Mantenemos el primer evento y anulamos los posteriores independientemente del origen de acción del que procedan. No hay ningún requisito para implementar la eliminación de duplicados para los eventos de la aplicación relacionados con eventos de descarga.

d. 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 del servidor de aplicaciones. 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:

** Solución de problemas**

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

Elige el origen de acción app cuando proceda.
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.