Conversions API for App Events

The Conversions API enables advertisers to send web, app, physical store and business messaging events to Meta through a single endpoint rather than across multiple sources. This consolidation will simplify an advertiser’s tech stack and create a more comprehensive view within Meta Events Manager by using datasets.

This documentation provides guidance for integrating app events to the Conversions API.

Prerequisites

1. Dataset

App events sent through the Conversions API must be associated with a dataset.

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.

You can make the GET call to https://graph.facebook.com/v16.0/{ads-pixel-id}/is_consolidated_container to detect if the advertiser’s dataset is consolidated and thus eligible for passing app events via the Conversions API.

2. Permissions

To implement a direct integration as an advertiser, please follow the instructions here for prerequisites and permissions.
To implement a partner platform integration, please follow the instructions here for prerequisites and permissions.

Configuration

Sending App Events to the Conversions API

a. Linking dataset ID and app ID

In Events Manager, there are two ways to link your app with a dataset:

Select the “Data Sources” tab, find your app’s “Setting” tab and perform the linking.
Select the “Data Sources” tab, in the “Overview” tab of your app, use the “Link to dataset” button in the “All Activity” section.

Once you complete the linking, the dataset includes the connected app.

b. Required fields

You can refer here to the current set of parameters that can be sent over the Conversions API. For sending app events, the following server_event fields can be shared in the payload:

The parameter action_source must contain the value app for app events.
The event_id is required for the deduplication setup case.
app_data fields
user_data fields
custom_data fields

App Data Fields

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.

Customer Information Parameters

Parameter	Description
`anon_id` string	Do not hash. Your install ID. This field represents unique application installation instances.
`madid` string	Do not hash. Your mobile advertiser ID, the advertising ID from an Android device or the Advertising Identifier (IDFA) from an Apple device.

Custom Data

Parameter	Description
`description` string	Optional. String, event description, custom.
`level` string	Optional. String, Level of a game, custom.
`max_rating_value`	Optional. Long, Upper bounds of a rating scale, for example 5 on a 5 star scale, custom.
`success` boolean	Optional. `1` for yes, `0` for no, custom.

In summary, the app events shared using the Conversions API will require the following data parameters:

action_source: Must be set to ‘app’. (By using the Conversions API, you agree that the action_source parameter is accurate to the best of your knowledge)
event_id: Required for the deduplication setup, see details in ‘Set up deduplication for multiple channels’ section.
advertiser_tracking_enabled
application_tracking_enabled
extinfo

Below is an example of extinfo. Make sure all the sub parameters below are filled and in sequential order. If anything is missing, use an empty string as a placeholder.

Subparameter Name	Required	Data Type	Example
extinfo version	Yes	string	`i2` (version must be a2 for Android, must be i2 for iOS)
app package name	No	string	`com.facebook.sdk.samples.hellofacebook`
short version	No	string	`1.0`
long version	No	string	`1.0 long`
os version	Yes	string	`13.4.1`
device model name	No	string	`iPhone5,1`
locale	No	string	`En_US`
timezone abbr	No	string	`PDT`
carrier	No	string	`AT&T`
screen width	No	string	`320`
screen height	No	string	`568`
screen density	No	string	`2`
cpu core	No	string	`2`
external storage size	No	string	`13`
free space in external storage size	No	string	`8`
device time zone	No	string	`USA/New York`

c. Set Up Deduplication for Multiple Channels

The deduplication mechanism will be required to remove duplicate event traffic between the Conversions API integration and all other existing integrations you have with app events including SDK, MMPs and App Events API.

For app events, we apply the same deduplication functionality that exists for web events. The logic leverages the field event_id and event_name based deduplication (Conversions API and SDK / App Events API events that carry the same event_id). The event_id parameter is an identifier that can uniquely distinguish between similar events. Inaccurate event IDs may cause your conversion to be wrongly deduplicated, further impacting conversion reporting and campaign performance.

You can refer to the following developer documentation to implement the deduplication setup:

Here is an example of how to log a custom event. To do so, pass the name of the event as an AppEvents.Name in iOS SDK:

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

For app install events, there is already a deduplication mechanism that makes sure only one install is attributed in the last 90-day window. We keep the first event and drop the later ones no matter the action source they are from. There is no requirement for implementing deduplication for app events related to install events.

d. Sending Events

To send new events, make a POST request to Conversions API from this path: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}. When you post to this edge, Meta creates new app server events. For more details, please refer to the following developer document.

Here is an overview of how the parameters fit into the overall schema in the payload:

** Troubleshooting**

You can use the Payload Helper tool to generate payload data:

Choose app action source when applicable
Fill info for the events that will be sent to Meta
This will generate event payload, which can be used as a template for your Conversions API integration

Use the Test Events tool in Events Manager for testing.