Skip to main content

​
Overview

Connect Meta Ads to send installs, registrations, purchases, and custom app events from Linkrunner to Meta. Use this guide to connect your Meta app and ad account, configure Conversions API, and map the events Meta should receive.

​
What You’ll Get

  • Automatic attribution tracking — Track installs and conversions from your Meta ad campaigns
  • View-through attribution — Attribute installs from users who viewed but didn’t click your ads (setup required)
  • Event mapping — Map your in-app events to Meta events for postback conversion tracking
  • Revenue tracking — Share revenue data with Meta to optimize for value
  • Default events included — App Install events and Sign up events are captured automatically

​
Setup Process

Setting up Meta Ads integration involves configuring your Meta app credentials, mapping events, and setting up conversion tracking in Meta Events Manager.
Running iOS App Promotion campaigns? Meta measures iOS installs via SKAdNetwork. After completing this guide, follow the Meta SKAN Setup guide.

​
1. Configure Meta App Integration

This process connects your app and Meta ad account with Linkrunner.

​
Step 1: Get Your Meta App ID

Meta App ID and Referrer Key
  1. Go to Meta for Developers
  2. Navigate to your App Dashboard
  3. Go to Settings → Basic
  4. Copy your App ID

​
Step 2: Get Your Referrer Decryption Key

Meta App ID and Referrer Key
  1. In the same App Dashboard under Settings → Basic
  2. Scroll down to the Android section
  3. Copy the Install Referrer Decryption Key
The Install Referrer Decryption Key is required for Android attribution tracking. Make sure you have this configured in your Meta app settings.

​
Step 3: Configure in Linkrunner Dashboard

  1. Go to Meta App Integration
  2. Enter your App ID in the designated field
  3. Enter your Referrer Decryption Key
  4. Click Save
Meta App Integration tab in Linkrunner

​
Step 4: Connect Meta Ad Account

  1. Go to Ad Account Integration
  2. Click Add Meta Account
  3. Log in with Meta and connect your ad account
Meta Ad Account Integration tab in Linkrunner

​
Step 5: Configure CAPI

  1. Click Configure CAPI for the connected ad account
  2. Select the dataset in Meta Events Manager and copy its Dataset ID into Linkrunner
  3. In that same dataset, open Settings → Conversions API, generate an access token, and paste it into CAPI access token in Linkrunner
  4. Click Check access & save
Linkrunner checks whether the token can access the dataset before saving. If the check fails, see CAPI dataset access errors. Configure CAPI modal in Linkrunner

​
2. Set Up Event Mapping

Map your app events to Meta events so Linkrunner can send postback conversions.
MobileAppInstall and CompleteRegistration are sent to Meta by default. You do not need mappings for these events.
  1. Go to Meta Ads Event Mapping
  2. Click Add Mapping
  3. Select your event under Your Events
  4. Select the matching Meta Ads Event
  5. Turn on Send Revenue only for revenue events, then choose the Currency
  6. Click Save
  7. Click the paper plane Send event to ad network icon to fire a test event
Meta Ads event mapping table in Linkrunner
After Linkrunner fires an event, it can take up to 1 hour to appear in Meta Events Manager.
If you cannot see MobileAppInstall or CompleteRegistration in Meta Events Manager, click the paper plane Send event to ad network icon for that event.

​
3. Configure Events in Meta Events Manager

Use Meta Events Manager to verify that Meta receives events from Linkrunner.
  1. Go to Meta Ads Dashboard
  2. Open Events Manager → Datasets
  3. Select your app dataset, or click Create Dataset
  4. Go to Settings → Conversions API and confirm the dataset can receive Conversions API events
  5. Open the Events tab to view events from Linkrunner
  6. Create custom conversion events for the events you want to optimize campaigns on
If events do not appear in Meta Events Manager after 1 hour, verify your App ID and Referrer Decryption Key are correct.

​
4. Create Your First Campaign

With the integration configured, launch an App Promotion campaign in Meta Ads Manager. No tracking links are needed. Linkrunner attributes installs through the Meta install referrer (Android) and SKAdNetwork (iOS), and campaigns appear in Linkrunner automatically as installs come in.
Your app must be registered in Meta for Developers with its store listing URL, and linked to the ad account you run campaigns from. Running website campaigns that send users to your app through a landing page? Follow Meta Web to App instead.

​
Step 1: Start a New Campaign

  1. Open Meta Ads Manager and select the ad account you connected to Linkrunner
  2. Click + Create
Meta Ads Manager Campaigns tab with the Create button highlighted
  1. Keep the buying type as Auction, select the App promotion objective, and click Continue
Create new campaign dialog with the App promotion objective selected
  1. Enter a campaign name and click Next
Meta enables Advantage+ by default, which automates audience and placements. You can switch to a manual setup during configuration. Linkrunner attributes both the same way.

​
Step 2: Configure the Ad Set

  1. Under App promotion, select your Mobile app store (Google Play Store or App Store) and search for your app under App name
Ad set editor with the Mobile app store dropdown and App name field highlighted
  1. Set your Budget & schedule. Keep the budget low for the first campaign.
  2. Define your Audience (locations, age, interests)
  3. Leave Advantage+ placements on unless you have a reason not to
  4. Click Next
If your app is not listed under App name, it is not registered with Meta or not linked to this ad account.

​
Step 3: Create the Ad

  1. Choose the Facebook Page and Instagram account for the ad’s Identity
  2. Upload your creative and write the primary text and headline
  3. In Destination, keep Main destination as App
  4. To open a specific screen after install, add your link in Deferred deep link. See Deferred Deep Linking below.
Ad editor Destination section with the Deferred deep link field highlighted
  1. Click Publish

​
Step 4: Verify the Campaign in Linkrunner

Campaigns and spend sync automatically from your connected ad account. Attribution rows appear after the campaign receives its first install.
  1. Open the Campaigns section in your Linkrunner dashboard
  2. Click All Channels and select Meta to filter your campaigns
  3. Open the campaign to view installs, events, and revenue attributed to it, broken down by ad set and ad creative
Linkrunner Campaigns section with the channel filter open and Meta selected
Campaign, ad set, and ad creative rows appear after they receive at least one install, not immediately at launch. New campaigns can also take a few hours to exit Meta’s review and start delivering.

​
5. Deferred Deep Linking

Use deferred deep links when a Meta install should open a specific screen after first app open. Linkrunner returns the selected URL in the SDK getAttributionData() response.
Campaign, ad set, and ad creative rows appear in Linkrunner after they receive at least one install.
For Meta App Promotion campaigns, add the destination in Meta Ads Manager at the ad level. Linkrunner reads the ad creative app_link from Meta and returns it from getAttributionData().
  1. Open the campaign in Meta Ads Manager
  2. Edit the Ad inside your App Promotion ad set
  3. In Destination, choose App
  4. Add your Linkrunner or app-link URL in Deferred deep link
  5. Leave Custom store listing empty unless you want Meta to send users to a specific store listing
  6. Publish the ad
Meta App Promotion Destination section with Deferred deep link and Custom store listing fields The fresh Meta sync runs every 30 minutes for the last 2 days of active clicks and spend. When an active ad has an app_link, Linkrunner stores it on the matching ad creative. If you update or remove the app link in Meta, Linkrunner updates the auto-synced value on the next fresh sync that sees that ad.
Meta app links can use a Linkrunner domain, another app-link domain, an MMP link, or a custom scheme. If Linkrunner imports the link from Meta, the domain does not need to be added in Linkrunner.
Linkrunner syncs Deferred deep link. It does not currently sync Meta’s Custom store listing value. That field controls the store page Meta opens when the app is not installed and is separate from the deep link returned by getAttributionData().
Do not use a Play Store or App Store URL as the app link. Meta exposes store destinations separately, and Linkrunner only returns the app link.

​
Priority Order

Linkrunner uses manual ad entity values before auto-synced Meta values:
  1. Manual Ad Creative Level: Used first
  2. Manual Ad Set Level: Used when the ad creative has no manual deep link
  3. Meta App Promotion App Link: Used when Meta returns an ad creative app_link
  4. Campaign Level: Used as the fallback
Use this when every ad in the campaign should open the same destination.
  1. Navigate to the Campaigns section in your Linkrunner Dashboard
  2. Find your Meta campaign in the list
  3. Click the Edit button on the campaign row
  4. In the campaign settings, locate the Deferred Deep Link field
  5. Enter your deep link URL, such as https://myapp.com/product/12345
  6. Click Save to apply the changes
Use this when an ad set should open a different destination from the campaign default. Manual ad set links use your Linkrunner project domain and override auto-synced Meta app links.
  1. Navigate to the Campaigns section in your Linkrunner Dashboard
  2. Find your Meta campaign in the list
  3. Click on the ad set name to open the ad set details
  4. In the ad set configuration, locate the Deferred Deep Link field
  5. Enter your deep link URL, such as https://myapp.com/category/electronics
  6. Click Update to apply the changes
Edit ad set deep link modal If no ad set deep link is set, Linkrunner uses the campaign deep link. Use this when one ad should open a specific product, offer, or screen. Manual ad creative links use your Linkrunner project domain and override auto-synced Meta app links.
  1. Navigate to the Campaigns section in your Linkrunner Dashboard
  2. Find your Meta campaign in the list
  3. Click on the ad creative name (or ad name) to open the ad creative details
  4. In the ad creative configuration, locate the Deferred Deep Link field
  5. Enter your deep link URL, such as https://myapp.com/product/12345?promo=summer
  6. Click Update to apply the changes
Edit ad creative deep link modal If no ad creative deep link is set, Linkrunner checks the ad set, then the campaign.

​
6. Enable Meta View-Through Attribution (Android)

By default, Linkrunner attributes installs from Meta ads using click-based attribution. To also attribute installs from users who viewed your ad but didn’t click on it (view-through conversions), you need to enable Meta Install Referrer support. Meta Install Referrer allows Linkrunner to receive ad campaign metadata directly from the Facebook or Instagram app installed on the user’s device. This enables view-through conversion tracking, giving you a more complete picture of your Meta campaign performance.

​
How It Works

  1. A user views your Meta ad but doesn’t click on it
  2. The user later installs your app organically
  3. The Linkrunner SDK retrieves campaign metadata stored by the Facebook/Instagram app on the device
  4. Linkrunner attributes the install back to the original Meta ad view

​
Setup

To enable this, you need to make your Facebook App ID available to the Linkrunner SDK in your Android app’s AndroidManifest.xml.
Add the following to your AndroidManifest.xml:
And add your App ID to strings.xml:

​
Requirements

  • Android SDK version 3.5.2 or higher
  • Flutter SDK version 3.6.2 or higher
  • React Native SDK version 2.6.2 or higher
  • Users must have Facebook app version 428.x.x+ or Instagram app version 296.x.x+ installed on their device
View-through attribution requires the Facebook or Instagram app to be installed on the user’s device. If neither app is present, only click-based attribution will be available.
For more details, see the Meta Install Referrer documentation. Test the complete preview, install, and first attribution response with Meta Android attribution testing.

​
FAQ and Discrepancies

For answers to common questions and an explanation of why numbers in Meta Ads Manager may not exactly match Linkrunner, see Meta Ads FAQ and Discrepancies.

​
Troubleshooting

​
CAPI dataset access errors

A missing CAPI configuration means the ad account needs a dataset ID and token saved in Linkrunner. An error after Check access & save means the save attempt failed or could not be confirmed. Follow the message shown in the modal. If the modal says it could not verify dataset access or asks you to check dataset permissions, Linkrunner rejected the new configuration before saving. The dataset ID and token may not match, or the token may lack access. A valid Events Manager token can also be rejected because of a Linkrunner validation limitation. The error alone does not prove that you need a new token or broader permissions.
  1. Open Meta Events Manager and select the dataset that should receive your events. Check that its ID matches Dataset ID in Linkrunner, not your App ID or ad account ID.
  2. For an Events Manager token, confirm that it was generated under Settings → Conversions API for that same dataset and was pasted completely. If it belongs to another dataset, use a token for the intended dataset. If you see Saved token, click Replace token only when you need to replace it.
  3. If you cannot access the dataset or need help generating a replacement, ask the dataset owner or business admin. For a token generated through your own Meta app, have the admin check that the dataset/pixel is assigned to the system user that generated it. See Meta’s access token setup guide. Do not grant broad permissions to unrelated assets as a workaround.
  4. After correcting a mismatch or access assignment, click Check access & save again. If an Events Manager token for the correct dataset is still rejected, contact Linkrunner support using the details below instead of repeatedly generating tokens or expanding permissions. Linkrunner must investigate validation failures on its side; do not change your credentials solely to work around them.
For other messages:
  • Invalid or expired token: Generate a new token for the same dataset, replace the token in Linkrunner, and retry.
  • Meta unavailable, rate limited, or unexpected response: These validation errors leave your saved configuration unchanged. Wait and retry rather than changing permissions.
  • Save could not be confirmed: Click Reload configuration and review the saved values before retrying. Your changes may already have been saved.
  • Configuration changed during the check: Reopen the configuration before trying again.
Configuration saved with Dataset access checked confirms access to the dataset, not event delivery. Continue with event mapping and verify receipt in Meta Events Manager separately. If the error persists, contact support@linkrunner.io with the dataset ID, ad account ID, exact error, and a screenshot with the token masked. Never send access tokens, app secrets, or referrer decryption keys in WhatsApp, email, or screenshots.

​
Events Not Showing Up in Meta

  • Verify your Referrer Decryption Key is correct
  • Check that your dataset is configured to receive Conversions API events
  • Wait up to 1 hour for events to appear in Meta Events Manager
  • Test your event mappings using the paper plane Send event to ad network icon in Linkrunner

​
Campaigns Not Appearing in Dashboard

Campaigns will only appear in the Linkrunner dashboard after the first install comes through that campaign, not immediately when the campaign is launched. Before troubleshooting, verify:
  • App is live with Linkrunner SDK — Ensure your app is deployed with the Linkrunner SDK integrated and has 100% rollout to users
  • Meta decryption key is configured — Verify the Install Referrer Decryption Key is correctly added in your Linkrunner dashboard settings
  • Campaigns are running — Confirm your Meta ad campaigns are active and serving impressions
  • First install received — Campaigns appear only after the first user installs your app via that campaign
Campaigns do not appear immediately after launch. You must wait for at least one install to come through the campaign before it will show up in your dashboard.

​
Revenue Data Not Tracking

  • Confirm “Send Revenue” is enabled in your event mapping
  • Verify the correct currency is selected
  • Ensure your app is sending revenue values with events
Need help? Contact support@linkrunner.io.