🚧

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. Learn more about Conversions API for App Events.

Configure this integration and analyze your app metrics right on Facebook Analytics. Send events to Facebook Ads Manager to build lookalike audiences based on subscription events (like renewals) and maximize your ROI.

How to Add Integration?

Disable Automatic Purchase Events Logging

Please make sure that you disabled Facebook Automatic Purchase Events Logging in app settings or consider changing event mapping so that native Facebook SDK events are not mixed with Apphud events. > Otherwise you may see duplicated numbers in Ads Manager.

Step 1

• Create new Facebook app, if you don't have it.
• Integrate or update Facebook SDK to the latest version.
• Collect Device Identifiers (required).
• Collect Attribution Data (required).
• IDFA Consent in iOS 14 on iOS (required).

Step 2

Open your Facebook app settings and copy your App ID:

Step 3

Under Advanced section copy Client Token:

Step 4

Enter App ID and Client Token fields:

Step 5

If you don't want to mix test and live data, create separate test app on Facebook. Paste test App ID and Client Token into corresponding fields.

Step 6

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 can be found in app "Basic" settings:

Step 7

For some events, you can enter custom names. For others, you can choose between Facebook build-in events. You can also specify event aliases that will be sent as event properties under alias key. Please, use only letters (a..z), numbers (0..9), underscore (_) for event names and aliases. You can also disable sending some events using switches.

Step 8

Enable Integration and save changes:

While configuring integration you can also choose between sending revenue as sales or proceeds (without Apple / Google 15%-30% commission).

📘

Note

You can read more how Apple calculates commission here.

Pass Device Attribution Data to Apphud

📘

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.

🚧

This is a required step

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

Passing device attribution data is required now:

// 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 below

Pass Device Attribution Data – Unity

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

The solution below suggests to install native iOS/Android Facebook SDK dependencies and call special Apphud method to collect attribution data.

Unity – Step 1

Install native iOS/Android dependency by calling:

Apphud -> Choose your platform[IOS/Android] -> ActivateFacebookSDK

Unity – Step 2

After activation complete:

On iOS do the following:

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

On Android do the following:

Assets -> External Dependency Manager -> Android Resolver - Force Resolve

Unity – Step 3

After that you can call:

ApphudSDK.AddFacebookAttribution();

This method will automatically fetch the necessary attribution data and pass 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 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 right on 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. Since now, you will be able to see these metrics right on Facebook Ads Manager:

You can also add subscription metrics to Facebook Ads report:

Facebook Lookalike Audience

Create Lookalike audience and launch Facebook Ads targeted on people who most likely will perform desired event. For example, create 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 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 location of people of your future audience and define audience size. Audience size ranges from 1% to 10%, where 1% is the closes to the target audience.

Step 8

Once created, you will be able to choose this Lookalike audience while setting up Ad Set:

📘

Note

Read a post called "4 tricks on launching Facebook Ads for iOS app with subscriptions" in our blog, where we describe several tactics to launch successful Facebook ad campaigns.

Troubleshooting

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

• If you run SKAdNetwork campaigns make sure your target app event is in top priority of SKAdNetwork App Events configuration. If your main goal is Purchase event, then 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.

• Keep in mind that integration works only for users that consented tracking. In other words IDFA is required for App Event to be processed by Facebook. Learn more.
• If you have low number of installs, then SKAdNetwork may report null conversion values due to Apple Privacy Threshold. The more app installs you get, the more accurate 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.
• Try to wait a few more hours, sometimes events appear in Events Manager / Ads Manager after up to 24 hours.
• Make sure you are viewing events in correct category. Events that are being sent by Apphud are mapped to Facebook Standard events, like Purchase, Subscribe, etc. You can view and edit events mapping in Facebook Integration page in Apphud. In the given example, Trial Converted event is mapped to Subscribe standard event in Facebook

• Verify that events are sent in Apphud Events page. Click "Integrations: sent" link and view event logs:

• Make sure you are using latest Facebook iOS SDK or Facebook Android SDK.
• In Overview tab in the Events Manager you can see Recent Activity of your events, like Subscribe:

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

• View your app events Diagnostics: