Meta Ads (App Events API)

The Meta Ads (App Events API) integration sends Apphud subscription and purchase events to Meta Ads Manager (Facebook Ads Manager) and Events Manager, so you can analyze app metrics, build Lookalike audiences based on subscription events (renewals, trials), and maximize ROI.

🚧

Deprecated

We no longer recommend App Events API for new integrations. The Conversions API now supports web, app, and offline events, so we recommend that advertisers use the Conversions API instead of App Events API. Existing App Events API users can continue to use it, but we will discontinue development of this API. Future innovation will be developed on the Conversions API. See Meta Ads (Conversions API).

How to Add Integration?

Step 1 - Install SDKs

• Install Apphud SDK.
• Create a new Facebook app, if you don't have one.
• Install or update the Facebook SDK to the latest version.
• Collect Device Identifiers (required). See below.
• Pass Device Attribution Data (required). See below.
• Request IDFA consent (required, iOS 14.5+). See below.

🚧

Disable Automatic Purchase Events Logging

Make sure you disabled Facebook Automatic Purchase Events Logging in app settings, or change event mapping so that native Facebook SDK events are not mixed with Apphud events. Otherwise you may see duplicated numbers in Ads Manager. See Step 2 - Preparations in Facebook below.

Step 2 - Preparations in Meta (Facebook)

Complete the following in your Meta (Facebook) app settings before configuring the connection in Apphud.

App ID

Open your Facebook app settings and copy your App ID:

Client Token

Under the Advanced section, copy the Client Token:

Test app (optional)

If you don't want to mix test and live data, create a separate test app on Facebook and copy its App ID and Client Token as well.

Disable Automatic Purchase Events Logging

For both live and test apps, disable Automatic Purchase Events Logging. This is required to prevent revenue double counting in Facebook Analytics and Ads Manager. The switch is in app Basic settings:

Step 3 - Authentication

In Apphud, open Connections → Integrations (the All or Attribution tab). Click Add Connection for Facebook Ads (App Events API) and choose a Source in the pop-up.

Enter:

• App ID (required) — copied from your Facebook app settings.
• Client Token (required) — copied from your Facebook app Advanced settings.
• Test App ID and Test Client Token (optional) — if you maintain a separate Facebook test app.

Step 4 - Additional Configuration

Environment and Revenue

Configure generic Environment and Revenue settings as described on Integrations overview → Configuration tab.

Set up filters (optional)

Navigate to Filters tab. Set up filters if needed as described on Integrations overview → Filters tab.

Step 5 - Set up Events list

Open the Events tab of the configuration. For some events you can enter custom names; for others, choose between Facebook built-in events. You can also specify event aliases that will be sent as event properties under the alias key.

❗️

Event name restrictions

Use only letters (a–z), numbers (0–9), and underscore (_) for event names and aliases. You can also disable sending some events using the switches.

Step 6 - Test connection (optional)

Save the connection.

For the general integrations configuration testing flow see Integrations overview → Test connection.

To verify Facebook integration end-to-end:

• Make sure the Facebook SDK is properly integrated and the Apphud Facebook integration is configured.
• Make sure Apphud.setAttribution(...) (or Apphud.addAttribution(...)) is called after both SDKs initialize.
• Make a test purchase in your app.
• In Apphud Events, click the Integrations: sent link on a relevant event and verify it appears in the log.
• In Facebook Events Manager → Overview, check Recent Activity for Subscribe, Purchase, or your mapped events.

📘

Events may take time to appear

Events sometimes appear in Events Manager / Ads Manager after up to 24 hours.

Step 7 - Enable and save

Once you confirmed the connection works — Enable integration and Save.

Pass Device Attribution Data to Apphud

🚧

This is a required step

If Apphud didn't receive device attribution from the SDK, any subscription events from this device will not be forwarded to Facebook.

📘

Update to the latest Apphud SDKs

Update to the latest SDKs: Flutter v2.5.4, Android v2.7.0, iOS v3.4.0, or above.

Passing device attribution data is required. Call this after both Facebook and Apphud SDKs have been initialized.

// in future versions of Facebook SDK getting extinfo may change, update if necessary.
// call this after both Facebook and Apphud SDKs have been initialized
let extInfo = _AppEventsDeviceInfo.shared.encodedDeviceInfo
let anonId = AppEvents.shared.anonymousID
let data = ["extinfo": extInfo ?? ""]
Apphud.setAttribution(data: ApphudAttributionData(rawData: data), from: .facebook, identifer: anonId, callback: nil)

import com.facebook.appevents.AppEventsLogger
import com.facebook.internal.Utility
...

// in future versions of Facebook SDK getting extinfo may change, update if necessary.
// call this after both Facebook and Apphud SDKs have been initialized
val json = JSONObject()
Utility.setAppEventExtendedDeviceInfoParameters(json, application)
val extInfo = json.get("extinfo")
val anonID = AppEventsLogger.getAnonymousAppDeviceGUID(application)
val map = mapOf("fb_anon_id" to anonID, "extinfo" to extInfo)
Apphud.addAttribution(ApphudAttributionProvider.facebook, map, anonID)

// Step 1. Install additional facebook plugin:
// https://pub.dev/packages/apphud_facebook_sdk
// This plugin installs native ios/android facebook sdks, so you need to remove flutter fb sdk to avoid conflicts.

// Step 2. Init Apphud Facebook Plugin.
// Pass attribution data to Apphud (requires Flutter Apphud SDK 2.5.4 or higher):

Future<void> _initFacebook() async {
    final apphudFacebookSdk = ApphudFacebookSdk();
    final facebookData = await apphudFacebookSdk.getFacebookData();
    if (facebookData != null) {
      await Apphud.addAttribution(
        provider: ApphudAttributionProvider.facebook,
        identifier: facebookData.anonId,
        data: {
          'extinfo': facebookData.extInfo ?? '',
        },
      );
    }
  }

// See Unity-specific steps below

Pass Device Attribution Data – Unity

Passing Attribution Data on Unity is not directly supported using the Facebook Unity SDK. However, it is possible with native iOS/Android Facebook SDKs.

The solution below installs native iOS/Android Facebook SDK dependencies and calls a special Apphud method to collect attribution data.

Unity – Step 1

Install the native iOS/Android dependency by calling:

Apphud → Choose your platform [iOS/Android] → ActivateFacebookSDK

Unity – Step 2

After activation complete:

iOS: Assets → External Dependency Manager → iOS Resolver → Settings → Link frameworks statically: set to false

Android: Assets → External Dependency Manager → Android Resolver → Force Resolve

Unity – Step 3

After that you can call:

ApphudSDK.AddFacebookAttribution();

This method automatically fetches the necessary attribution data and passes it to Apphud.

Collect Device Identifiers (required)

iOS: Call setDeviceIdentifiers(idfa: String?, idfv: String?) method immediately after the SDK initialization. If the advertising identifier (IDFA) is not available, pass only the IDFV.
When IDFA becomes available, you can call setDeviceIdentifiers(idfa: String?, idfv: String?) again.

Android: Call Apphud.collectDeviceIdentifiers() method after the SDK initialization.
When targeting Android 13 and above, you must also declare AD_ID permission in the manifest file.

For more details, refer to Device Identifiers guide.

Request IDFA Consent (required)

Starting iOS 14.5, access to IDFA requires user consent. You should request IDFA manually using the AppTrackingTransparency framework and pass it to Apphud. Read more here.

📘

Note

You can read more about subscription events here and parameters here.

Facebook Ads and Ad Reports

View subscription metrics directly in Facebook Ads Manager. Open Facebook Ads Manager, click on Columns, and select Customize Columns…:

Add necessary columns. For example, subscriptions and trials total count, value, and cost:

You may optionally save this customized view as a preset. From now on, you will be able to see these metrics directly in Facebook Ads Manager:

You can also add subscription metrics to a Facebook Ads report:

Facebook Lookalike Audience

Create a Lookalike audience and launch Facebook Ads targeted at people who most likely will perform a desired event. For example, create a Lookalike audience based on people who recently purchased a subscription.

Step 1

Open Facebook Audiences Tool and select your Facebook Ads account in the dropdown in the top-left corner.

Step 2

Select Create Audience → New Lookalike audience:

Step 3

Click on Create New Source → Custom Audience:

Step 4

Select App Activity:

Step 5

Select your app and the Subscribe event. You may optionally choose a date range to include only users who made a purchase recently:

Step 6

Name your audience and save.

Step 7

Select the location of people in your future audience and define audience size. Audience size ranges from 1% to 10%, where 1% is closest to the target audience.

Step 8

Once created, you can choose this Lookalike audience while setting up an Ad Set:

📘

Note

Read 4 tricks on launching Facebook Ads for iOS app with subscriptions on the Apphud blog, where we describe several tactics to launch successful Facebook ad campaigns.

Troubleshooting

If you don't see events in Facebook Analytics and Ads Manager, check the following:

• SKAdNetwork priority. If you run SKAdNetwork campaigns, make sure your target app event is in top priority of the SKAdNetwork App Events configuration. If your main goal is the Purchase event, it should have the greatest conversion value. You can view and edit your App Events configuration for SKAdNetwork in your app's settings in Events Manager.

  

• IDFA consent. The integration works only for users that consented to tracking. IDFA is required for an App Event to be processed by Facebook. Learn more.

• Low number of installs. If you have a low number of installs, SKAdNetwork may report null conversion values due to Apple Privacy Threshold. The more app installs you get, the more accurate the SKAdNetwork campaign will be. Learn more.

• Invalid Subscribe Value Parameter. One or more of your Subscribe events has invalid characters in the value field — try to disable refund events from integration setup.

• Events take time to appear. Wait a few more hours, sometimes events appear in Events Manager / Ads Manager after up to 24 hours.

• Event mapping category. Make sure you are viewing events in the correct category. Events sent by Apphud are mapped to Facebook Standard events, like Purchase, Subscribe, etc. You can view and edit event mapping on the Facebook integration page in Apphud. In the example below, Trial Converted is mapped to the Subscribe standard event in Facebook.

  

• Verify events are sent. In Apphud Events page, find a recent event with a type that was enabled to be sent to the destination. In Integration Status column click on the status and then click View Details.
  In Events tab, You can also apply a filter to the Connection by Status of the events submission to define successful, failed, skipped, or pending ones.

  

• SDK versions. Make sure you are using the latest Facebook iOS SDK or Facebook Android SDK.

• Recent Activity in Events Manager. In the Overview tab in Events Manager, you can see Recent Activity of your events, like Subscribe:

  

• Detailed information about events. View detailed information about the last 100 events received, including parameters sent by Apphud:

  

• App events Diagnostics. View your app events Diagnostics: