👍

This is an improved version of Facebook Ads Integration

Current integration is using Conversions API and now supports App Events along with Web-to-App events and can be used for Aggregated Event Measurement. Supports both iOS and Android apps.

What is Conversions API?

The Facebook Conversions API is intended to establish a link between an advertiser's marketing information — including web events, app events, business messaging, and offline conversions — and Meta's systems. This connection is meant to enhance ad targeting, reduce costs per result, and improve measurement.

Apphud events are linked to a Dataset and are processed like events sent via the Meta Pixel, Facebook SDK for iOS or Android, mobile measurement partner SDK, offline event set, or .csv upload. This means that Apphud events may be used in measurement, reporting, or optimization in a similar way as other connection channels for both iOS and Android devices.

Support for Meta's Attribution (Aggregated Event Measurement)

Meta's attribution – Aggregated Event Measurement is a protocol that allows for measurement of web and app events from people using iOS 14.5 and later devices, including those who’ve opted out of tracking on Facebook or Instagram apps, while still respecting people’s privacy choices. Apphud Events sent to Facebook using Conversions API now support Aggregated Event Measurement.

How to add integration?

To get started with Conversions API integration you need to follow steps in the Events Manager:

• Create Dataset ID if you haven't already. This can be done in Data Sources page in the Business Manager.
• Link Dataset ID with your Facebook App ID. This can be done in the settings of your Data Source in Meta Events Manager.

• Check app eligibility for Aggregated Event Measurement (iOS only). This can be done in the settings of your Data Source in Meta Events Manager. Your app must be eligible for App Events Promotion for selected event:

• Pass Device Attribution Data to Apphud. See below.
• Generate Access Token. See below.

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.

Generate Access Token

To generate Access Token find Generate access token button in the settings of your Data Source in Meta Events Manager. Note that access token is displayed only once. You will not be able to view the token once the page is refreshed.

📘

Keep in mind

You can re-generate access token and update the value in the integration settings in Apphud at any time.

How to add integration?

Step 1

• Go to Apphud integrations page and select Facebook Ads (Conversions API) integration.

Step 2

• Enter your Dataset ID (you can get in the settings of your Data Source in Events Manager)
• Enter your Access Token (you can generate it in the settings of your Data Source in Events Manager)

Step 3

• Configure events mapping. Apphud Events must be mapped to one of Facebook Standard Events. You can disable events that you don't need.

Step 4

• Enable Integration and Save.

Validate Setup

1. If everything works correctly, you should start seeing Apphud events sent by Conversions API in the Events Manager:

2. Your App Event sent via Conversions API should be eligibile for Aggregated Event Measurement (iOS only). You can check this in the settings of your Data Source in Meta Events Manager.

Using Meta's Attribution (Aggregated Event Measurement)

In the ad campaign set up, select Meta's attribution instead of SKAdNetwork:

Using Conversions API for Web-to-App campaign optimization

📘

Web-to-App integration

All the documentation below is related to Web-to-App campaigns

Conversions API integration can also be used to run Web-to-App (or Web2App) campaigns in Facebook with event optimization. Learn more.

Web-to-App campaign is a web campaign targeted to your app’s landing page which has a link to the App Store.

👍

Important Note

Facebook Conversions API integration supports both App Events and Web Events. This allows you to run App Promotion campaigns and Web campaigns simultaneously.

About Cross-Channel Campaign Optimization

When a user is successfully attributed to a click, their events are sent to Facebook as Web Events, with the action_source parameter set to website. These events are sent as Web Events only if a Click ID is found for the current user.

For users who are organic or not part of web campaign, and if device attribution is available (e.g., extinfo and anon_id are found), their events are sent to Facebook as App Events, with the action_source parameter set to app.

If Apphud fails to match a web click to an app installation, it can still send the event to Facebook as an App Event (without the fbc parameter). However, by default, App Events and Web Events cannot be optimized within the same campaign. These App Events will not appear in Ads Manager because web campaigns only accept Web Events.

There is an exception: in special cross-channel campaigns, developers can send both App Events and Web Events.

If you're running such cross-channel campaigns on Facebook, both app and web events should appear in a single campaign. If both event types are present, sum their counts and revenue values to get the total amount. Learn more: Facebook Business Help.

If you're running such cross-channel campaigns on Facebook, you can enable the "Send App Events for Web Campaigns" checkbox in Apphud. This option allows Apphud to send App Events even if a Click ID is not found for a user. If both event types are present, sum their counts and revenue values to get the total amount. Learn more: [Facebook Business Help] (https://www.facebook.com/business/help/187685303269334)

How to enable Web-to-App integration?

To use the integration for Web-to-App campaigns, update it by checking the checkbox as on the screenshot below:

After saving you will see Apphud Pixel Script:

You will need to use this Script code only if you are using your own landing page for web campaigns. If you're planning to use our Landing Pages generated in the Landing Page Editor, you can skip a script installation step, since the script will be already installed.

Install Apphud Pixel to your Landing Page

Follow this guide to Install Apphud Pixel script on your own landing page.

For more information about Web-to-App campaigns visit this link.

How to increase Event Match Quality

You can add custom parameters, like email or date of birth, in order to increase match quality. Here is a list of acceptable additional optional parameters that you can send from Apphud SDK via user properties method for your Conversions API:

For more information about customer parameters visit this link.

Receive Web-to-App and Web-to-Web Attribution Data

In order to get attribution data from Facebook web campaigns, you will need add URL parameters to understand where visitors are coming from.

Paste these parameters to URL parameters field in Tracking section of your ad set up page.

campaign_name={{campaign.name}}&adset_name={{adset.name}}&ad_name={{ad.name}}&network=facebook

More information about URL parameters for attribution can be found here and here.

Attribution Parameter Mapping

You can replace campaign_name, adset_name, and ad_name with alternative UTM parameters for campaign attribution. The mapping options are:

• Campaign Name:
  Use one of the following: campaign_name, utm_campaign, c.

• Adset Name:
  Use one of the following: utm_content, adset, adgroup, adgroup_name, af_adset, adgroup_id.

• Ad Name:
  Use one of the following: utm_term, adname, ad, ad_id, ad_name, af_ad.

Analyze Web-to-App and Web-to-Web campaigns in Apphud

Since integration is a part of Web-to-App solution, analytics is described in this guide.

Testing Web-to-App and Web-to-Web

To test your Web-to-App or Flows (Web-to-Web) setup, ensure the following requirements are met:

• The mobile app is deleted from the testing device.
• You have **deleted a user page **in the Apphud sandbox Users tab. To do this, find your Apphud User ID (printed in the Xcode console), and enter the User ID in the search bar on the Apphud Users page.
• Temporarily remove the code that sends device attribution to Apphud. Specifically, do not send extinfo and anon_id via the Apphud.addAttribution(...) method. This will help avoid confusion about how the event was sent to Facebook.

Follow these steps:

• Add the following query parameters to the URL:
  • fbclid with random string value
  • network=facebook
  • Optionally add UTM parameters to test attribution: utm_campaign=test1&utm_source=meta_ads

Full example URL:

https://yourwebsite.com/?network=facebook&fbclid=123&utm_campaign=test1&utm_source=meta_ads

Open the link with the appended query parameters on your testing device. Browser's incognito mode is recommended to avoid previous cookies.

Steps for Flows (Web-to-Web):

• Make a test purchase on the flow.
• View Sandbox Events page in Apphud web app.
• View event logs, Facebook Conversions API purchase event for your user should be sent. If state is Pending, wait a few minutes.

Steps for Web-to-App:

• Click the install button on the landing page. You will be navigated to the App Store. Do not download the app from the App Store at this time.
• Install the app from TestFlight or Xcode and launch.
• Make test In-App purchase.
• View Sandbox Events page in Apphud web app.
• View event logs, Facebook Conversions API event should be sent. If state is Pending, wait a few minutes.
• If state is Skipped, double check Testing steps, and try again. Or contact support manager for assistance.

Using Conversions API for Web-to-Web Flows

Setting up the Meta Conversions API for web-to-web campaigns is similar to the process for web-to-app campaigns, utilizing the same iOS or Android integration depending on the device platform.

1. Select the Appropriate Platform

   • For web-to-web campaigns targeting an iOS app, create a Conversions API integration for iOS.
   • For Android campaigns, create an integration for Android.
   • If you already have an existing Conversions API integration, no additional action is required.

2. Enable Web events
   Ensure the checkbox for "Enable if the integration will also be used to attribute in-app events to web campaigns" is selected.

3. Install Meta Pixel
   Install Meta Pixel on your website through Framer page settings or your preferred web editor.

4. Disable Automatic Event Tracking
   Turn off automatic event tracking in Meta Events Manager.

The Apphud Web SDK will automatically capture Facebook Click ID parameters (e.g., fbc and fbp) from Meta Pixel and use them for sending purchase events.

Troubleshooting

App Events Troubleshooting (Aggregated Event Measurement)

📘

Important Note

Please note that Apphud is not a marketing platform. Our integration with the Facebook Conversions API follows the guidelines outlined in Facebook's official documentation. While we strive to assist with any issues, we do not have direct contact with Meta developers and cannot provide marketing support related to the App Eligibility for Aggregated Event Measurement of specific Apphud events for particular App IDs.

Our integration has been thoroughly tested across multiple App IDs and has consistently produced accurate results.

If Apphud events are successfully sent to Facebook and appear in the Events Manager, this indicates that Apphud has completed its function. While this marks the conclusion of Apphud's role, we remain committed to assisting with any support requests to the best of our ability.

Event doesn't show up in the Eligibility Results

If your event doesn't show up in the Eligibilty Results page, collect more events. Probably it's not visible due to low amount of events.

Advertiser Tracking Enabled parameter volume out of range

This error indicates that there is an issue with the number of events that include the "Advertiser Tracking Enabled" parameter. Specifically, it suggests that Facebook is not receiving enough events with IDFA (Identifier for Advertisers) included in the payload.
To resolve this, try the following:

• Increase the acceptance rate for IDFA consent.
• Send only events that you need. Do not send events to Facebook before IDFA consent alert, such as user_created, paywall shown, etc.

Learn more

Ineligible Status Workaround

If you see that your event is ineligible for Meta's Attribution, but none of the answers didn't help, try to click "More details" button. There will be an option to "Continue" setup and force event to become eligibile.

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.

Other Issues with App Eligibility for Aggregated Event Measurement

[You can learn more regarding issues with eligibility for AEM in this guide:]
(https://www.facebook.com/business/help/716239976391518)

Web Events Troubleshooting (Web-to-Web)

Please ensure you correctly installed Meta Pixel and entered correct credentials for Integration.

• Still having troubles? Contact us.

Web Events Troubleshooting (Web-to-App)

Please double check the following list in case you experience issues with integration. Make sure the following is correct:

• Your landing page should contain correct script code. Double check this guide.
• Note that re-engagement is not yet supported. It must be a fresh install, or at least the user record must not exist in Apphud.
• Check Testing guide above.
• Events should be correctly mapped with Apphud events in integration settings page. For example, Subscription Started event should be mapped either with Purchase or Subscribe event. It's up to developer to choose desired mapping.
• Double check Dataset ID and Client Token are valid.
• Try to re-generate access token and update it in Apphud.
• Read Facebook's useful docs: https://www.facebook.com/business/help/721422165168355
• Still having troubles? Contact us.
• You may experience low install or purchase rate when running Web-to-App campaign with Purchase event optimization. Consider targeting for less priority events at the beginning, like User Created , Paywall Shown or Paywall Checkout Initiated. You can view and edit event mapping in Facebook Conversions API integration page.

• Event error: Unsupported post request. Object with ID '1234567890' does not exist, cannot be loaded due to missing permissions, or does not support this operation. Please make sure you entered correct Dataset ID, and access token was created by Facebook User that has correct permissions to view datasource settings in the Events Manager, this user must not be banned, deleted, etc.
• Event error: Error validating access token: The session has been invalidated because the user changed their password or Facebook has changed the session for security reasons. Please re-generate your access token.
• Make sure you are sending device attribution to Apphud, which include both extifno and anon_id.