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.

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

Customer Information Parameters

Custom Data

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.

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:

• How to set up app events
• Example of 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:

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": 1684389752,
            "action_source": "app",
            "user_data": {
                "em": [
                    "30a79640dfd8293d4f4965ec11821f640ca77979ca0a6b365f06372f81a3f602"
                ],
                "ph": [
                    "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b",
                    "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b"
                ],
                "madid": "bbbbbbbbbbbb",
      "anon_id": "cccccccc"
            },
            "custom_data": {
                "currency": "USD",
                "value": "142.52"
            },
            "app_data": {
                "advertiser_tracking_enabled": "True",
                "application_tracking_enabled": "True",
                "campaign_ids": "aaaaaaaaa",
                "extinfo": [
                    "a2",
                    "com.some.app",
                    "771",
                    "Version 7.7.1",
                    "10.1.1",
                    "OnePlus6",
                    "en_US",
                    "GMT-1",
                    "TMobile",
                    "1920",
                    "1080",
                    "2.00",
                    "2",
                    "128",
                    "8",
                    "USA/New York"
                ]
            }
        }
    ]
}

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.

See Also

• Conversions API Overview
• Using the Conversions API
• Conversions API Parameters
• Best Practices