Meta Ads (Conversions API)

The Meta Conversions API integration sends Apphud subscription and purchase events directly to Meta's servers — supporting App Events, Web-to-App, and Web-to-Web campaigns for both iOS and Android. A server-side link between your app's revenue data and Meta's systems enables more accurate ad targeting, lower cost per result, and better measurement than traditional pixel-only or SDK-only setups.

What is Conversions API?

The Meta Conversions API establishes a link between an advertiser's marketing information — web events, app events, business messaging, and offline conversions — and Meta's systems. This connection enhances ad targeting, reduces costs per result, and improves measurement.

Apphud events are linked to a Dataset and processed like events sent via the Meta Pixel, Facebook SDK for iOS or Android, mobile measurement partner SDK, offline event set, or .csv upload. Apphud events can 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 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 Meta using Conversions API support Aggregated Event Measurement.

How to Add Integration?

Step 1 - Install SDKs

• Install Apphud SDK.
• Install Facebook SDK (native iOS/Android, Flutter plugin, or via Unity helper — see Pass Device Attribution Data below).
• Pass Device Attribution Data to Apphud (required for App Events). See below.

Step 2 - Preparations in Meta

Complete the following in Meta Events Manager before configuring the connection in Apphud.

Create Dataset ID

Create a Dataset ID if you haven't already. This is done on the Data Sources page in Business Manager.

Link Dataset ID with your Facebook App ID

In the settings of your Data Source in Meta Events Manager, link the Dataset ID with your Facebook App ID.

Check app eligibility for Aggregated Event Measurement (iOS only)

In the settings of your Data Source in Meta Events Manager, verify your app is eligible for App Events Promotion for the selected event.

Generate Access Token

In the settings of your Data Source in Meta Events Manager, click Generate access token. The access token is displayed only once — you will not be able to view the token after the page is refreshed.

Step 3 - Authentication

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

Enter:

• Dataset ID — copied from the settings of your Data Source in Meta Events Manager.
• Access Token — generated in the settings of your Data Source in Meta Events Manager.

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.

Web-To-App Configuration (optional)

If you plan to run Facebook Web-to-App or Web-to-Web campaigns through this connection, enable the Web-To-App Configuration checkbox. See Using Conversions API for Web-to-App campaign optimization for full setup.

Step 5 - Set up Events list

Open the Events tab of the configuration. Apphud Events must be mapped to one of Facebook Standard Events. You can disable events you don't need.

Step 6 - Test connection (optional)

Save the connection.

For the dashboard Test connection action see Integrations overview → Test connection.

To validate the setup end-to-end:

1. If everything works correctly, Apphud events sent via the Conversions API will start appearing in Events Manager.

   

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

   

For testing Web-to-App and Web-to-Web flows specifically, see Testing Web-to-App and Web-to-Web below.

Step 7 - Enable and save

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

Pass Device Attribution Data to Apphud (required)

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

// Your class variables
ApphudFacebookData? _facebookData;
final _apphudFacebookSdkPlugin = ApphudFacebookSdk();

Future<void> _handleInitFacebookEvent(
    PurchaseInitFacebookEvent event,
    Emitter<PurchaseState> emit,
  ) async {

   try {
      _facebookData = await _apphudFacebookSdkPlugin.getFacebookData();
    } catch (e) {
      // ignore
      printError('handleInitFacebookEvent error', e);
    }

  if (_facebookData != null) {
// do not forget to test this implementation: Facebook raw data should appear in Apphud on your test user page.
      await Apphud.setAttribution(
        provider: ApphudAttributionProvider.facebook,
        identifier: _facebookData!.anonId,
        data: ApphudAttributionData(
          rawData: {
            'extinfo': _facebookData!.extInfo ?? '',
          },
        ),
      );
    }
  }

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.

Using Meta's Attribution (Aggregated Event Measurement)

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

Using Conversions API for Web-to-App campaign optimization

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

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

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 a web campaign (i.e., app-based attribution via SDK), 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.

How to enable Web-to-App integration?

Enable the Web-To-App Configuration checkbox in the connection settings (see screenshot in Step 4 → Web-To-App Configuration).

You'll need a landing page that can be created in Apphud via the Screens functionality, or you can create your own landing page.

If you're planning to use the Landing Page generated in the Landing Page Editor, follow the FB-specific guide here that describes how to obtain the Apphud Pixel.

If you'd like to create your own landing page, follow the Facebook official guide.

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 Web-to-App Introduction.

How to increase Event Match Quality

You can add custom parameters such as email or date of birth to increase match quality. The list below shows acceptable additional optional parameters you can send from the Apphud SDK via the user properties method for your Conversions API:

For more information about customer parameters visit Meta's Conversions API best practices.

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

To get attribution data from Facebook web campaigns, add URL parameters to understand where visitors are coming from.

Paste these parameters into the URL parameters field in the Tracking section of your ad setup page:

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

More information about URL parameters for attribution: Facebook Help (1) and Facebook Help (2).

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 — one of: campaign_name, utm_campaign, c.
• Adset Name — one of: utm_content, adset, adgroup, adgroup_name, af_adset, adgroup_id.
• Ad Name — one of: utm_term, adname, ad, ad_id, ad_name, af_ad.

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

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

Using Conversions API for Web-to-Web Flows

Setting up the Meta Conversions API for web-to-web campaigns is similar to 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 "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 (fbc and fbp) from Meta Pixel and use them for sending purchase events.

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. 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 Apphud.addAttribution(...). This helps 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 the Sandbox Events page in Apphud.
• View event logs — the 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 a test in-app purchase.
• View the Sandbox Events page in Apphud.
• View event logs — the 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.

Troubleshooting

App Events Troubleshooting (Aggregated Event Measurement)

Event doesn't show up in the Eligibility Results

If your event doesn't show up in the Eligibility Results page, collect more events. It's probably not visible due to a low amount of events.

Advertiser Tracking Enabled parameter volume out of range

This error indicates 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:

• Increase the acceptance rate for IDFA consent.
• Send only events 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 your event is ineligible for Meta's Attribution and none of the other answers help, click the More details button. There will be an option to Continue setup and force the event to become eligible.

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.

Web Events Troubleshooting (Web-to-Web)

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

Still having troubles? Contact us.

Web Events Troubleshooting (Web-to-App)

Please double-check the following list in case you experience issues with the integration:

• Your landing page should contain the correct script code. Double-check Install Apphud Pixel.

• 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 the Testing guide above.

• Events should be correctly mapped with Apphud events in the integration settings page. For example, Subscription Started event should be mapped either with Purchase or Subscribe event. It's up to the developer to choose the desired mapping.

• Double-check the Dataset ID and Client Token are valid.

• Try to re-generate the access token and update it in Apphud.

• Read Facebook's useful docs: Aggregated Event Measurement.

• Still having troubles? Contact us.

• You may experience low install or purchase rate when running a Web-to-App campaign with Purchase event optimization. Consider targeting less priority events at the beginning, such as User Created, Paywall Shown, or Paywall Checkout Initiated. You can view and edit event mapping in the Meta 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. — Make sure you entered the correct Dataset ID, and the access token was created by a Facebook User with the correct permissions to view data-source 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. — Re-generate your access token.

• Make sure you are sending device attribution to Apphud, which includes both extinfo and anon_id.

FAQ

Q: A user has "Facebook raw data" (anon_id / extinfo) but is attributed to another source, like Apple Search Ads. Does that mean they came from Facebook?

No. anon_id and extinfo are device signals generated by the Facebook SDK for every user who opens your app while the FB SDK is present — regardless of where the install came from. Apphud collects them so it can forward that user's purchase and subscription events to Meta via the Conversions API (as App Events). They are not an attribution signal.

A user is attributed to a Facebook ad only when a Click ID (fbc / fbclid, added automatically when someone clicks a Meta ad) is present. In that case the Facebook attribution fields (Campaign / Ad set / Ad) are populated and events are sent as Web Events. If those fields are empty, the user did not come from a Facebook ad — even though FB raw data exists.

In short: sending a user's events to Meta ≠ that user came from Meta. Apphud forwards events for all users that have FB device attribution (so Meta can measure and optimize), including organic users and users acquired through other networks such as Apple Search Ads.

Q: In the Meta (Conversions API) integration I see that far more events were sent to Meta than there are users attributed to the Meta ad network. Is that double-counting or a bug?

No — this is expected. Apphud forwards events to Meta for every user that has Facebook device attribution (anon_id / extinfo), sending them as App Events. That population includes organic users and users acquired through other networks (for example Apple Search Ads) — not just users who came from a Meta ad. Meta wants conversion signals for your whole audience so it can measure and optimize, so Apphud sends broadly.

A user is attributed to the Meta ad network only when a Click ID (fbc / fbclid) matches them to an actual Meta ad — those events go as Web Events and populate the Campaign / Ad set / Ad fields on the charts.

So the two numbers count different things:

Events sent to the integration = everyone whose events Apphud forwards to Meta (all users with FB device attribution).
Users attributed to the Meta ad network = only those matched to a real Meta ad click.
The first being much larger than the second is completely normal — it does not mean events are duplicated or mis-attributed. It simply reflects that Apphud sends App Events for your whole audience, while ad-network attribution counts only ad-driven installs.