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:

App Data Fields

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

vendor_id
string

Optional

Vendor ID.

windows_attribution_id
string

Optional

Attribution token used for Windows 10.

Customer Information Parameters

ParameterDescription
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

ParameterDescription
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:

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 NameRequiredData TypeExample

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.