> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linkrunner.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Ads

> Configure your Meta app integration settings to enable proper attribution tracking for your mobile app campaigns

## 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.

<iframe width="100%" height="468" src="https://www.youtube.com/embed/rBs69ubSCGk" title="Meta Ads Integration Tutorial" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

### 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](#6-enable-meta-view-through-attribution-android))
* **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.

<Note>
  Running iOS App Promotion campaigns? Meta measures iOS installs via SKAdNetwork. After completing this guide, follow
  the [Meta SKAN Setup](/features/meta-skan-setup) guide.
</Note>

## 1. Configure Meta App Integration

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

### Step 1: Get Your Meta App ID

<img src="https://mintcdn.com/linkrunner-01ef8e08/7y9ZToO29i3tXzl3/images/meta-app-id.png?fit=max&auto=format&n=7y9ZToO29i3tXzl3&q=85&s=3949b5f0773123d51c8211147c4a9625" alt="Meta App ID and Referrer Key" width="1654" height="698" data-path="images/meta-app-id.png" />

1. Go to [Meta for Developers](https://developers.facebook.com/)
2. Navigate to your App Dashboard
3. Go to **Settings** → **Basic**
4. Copy your **App ID**

### Step 2: Get Your Referrer Decryption Key

<img src="https://mintcdn.com/linkrunner-01ef8e08/7y9ZToO29i3tXzl3/images/referrer_key.png?fit=max&auto=format&n=7y9ZToO29i3tXzl3&q=85&s=4456a764bb3f2b3cbf50b1d8b26b8f21" alt="Meta App ID and Referrer Key" width="660" height="356" data-path="images/referrer_key.png" />

1. In the same App Dashboard under **Settings** → **Basic**
2. Scroll down to the **Android** section
3. Copy the **Install Referrer Decryption Key**

<Note>
  The Install Referrer Decryption Key is required for Android attribution tracking. Make sure you have this configured
  in your Meta app settings.
</Note>

### Step 3: Configure in Linkrunner Dashboard

1. Go to [Meta App Integration](https://dashboard.linkrunner.io/dashboard/integrations/meta-ads?tab=integration)
2. Enter your **App ID** in the designated field
3. Enter your **Referrer Decryption Key**
4. Click **Save**

<img src="https://mintcdn.com/linkrunner-01ef8e08/NqmCJqvi7Ia_bd5X/images/meta/app-integration.png?fit=max&auto=format&n=NqmCJqvi7Ia_bd5X&q=85&s=d998fe8f47a5bef297d2e1f0a380a4da" alt="Meta App Integration tab in Linkrunner" width="821" height="614" data-path="images/meta/app-integration.png" />

### Step 4: Connect Meta Ad Account

1. Go to [Ad Account Integration](https://dashboard.linkrunner.io/dashboard/integrations/meta-ads?tab=ad_account)
2. Click **Add Meta Account**
3. Log in with Meta and connect your ad account

<img src="https://mintcdn.com/linkrunner-01ef8e08/NqmCJqvi7Ia_bd5X/images/meta/ad-account-integration.png?fit=max&auto=format&n=NqmCJqvi7Ia_bd5X&q=85&s=0ee6a09199a3bf526f0998aa74f2d249" alt="Meta Ad Account Integration tab in Linkrunner" width="3166" height="1230" data-path="images/meta/ad-account-integration.png" />

### Step 5: Configure CAPI

1. Click **Configure CAPI** for the connected ad account
2. Enter the **Dataset ID** from Meta Events Manager
3. Enter the **CAPI Access Token** from Meta Events Manager → **Settings** → **Conversions API**
4. Click **Save**

<img src="https://mintcdn.com/linkrunner-01ef8e08/NqmCJqvi7Ia_bd5X/images/meta/configure-capi.png?fit=max&auto=format&n=NqmCJqvi7Ia_bd5X&q=85&s=8d85a6ae741f294403ab7afdcebb2916" alt="Configure CAPI modal in Linkrunner" width="1844" height="2002" data-path="images/meta/configure-capi.png" />

## 2. Set Up Event Mapping

Map your app events to Meta events so Linkrunner can send postback conversions.

<Note>
  **MobileAppInstall** and **CompleteRegistration** are sent to Meta by default. You do not need mappings for these
  events.
</Note>

1. Go to [Meta Ads Event Mapping](https://dashboard.linkrunner.io/dashboard/integrations/meta-ads?tab=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

<img src="https://mintcdn.com/linkrunner-01ef8e08/NqmCJqvi7Ia_bd5X/images/meta/event-mapping.png?fit=max&auto=format&n=NqmCJqvi7Ia_bd5X&q=85&s=a503514cc979d17fc04c75c64ff7126f" alt="Meta Ads event mapping table in Linkrunner" width="1080" height="860" data-path="images/meta/event-mapping.png" />

<Note>
  After Linkrunner fires an event, it can take up to 1 hour to appear in Meta Events Manager.
</Note>

<Tip>
  If you cannot see **MobileAppInstall** or **CompleteRegistration** in Meta Events Manager, click the paper plane
  **Send event to ad network** icon for that event.
</Tip>

## 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](https://business.facebook.com/)
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

<Note>
  If events do not appear in Meta Events Manager after 1 hour, verify your App ID and Referrer Decryption Key are
  correct.
</Note>

## 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.

<Note>
  Your app must be registered in [Meta for Developers](https://developers.facebook.com/) 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](/ad-networks/meta-web-to-app) instead.
</Note>

### Step 1: Start a New Campaign

1. Open [Meta Ads Manager](https://business.facebook.com/adsmanager) and select the ad account you connected to Linkrunner
2. Click **+ Create**

<img src="https://mintcdn.com/linkrunner-01ef8e08/ct-QjCqwwf0cx326/images/meta/first-campaign/create-button.png?fit=max&auto=format&n=ct-QjCqwwf0cx326&q=85&s=d34d5ab0f0f9ec2f0802558afaf82f31" alt="Meta Ads Manager Campaigns tab with the Create button highlighted" width="3200" height="2080" data-path="images/meta/first-campaign/create-button.png" />

3. Keep the buying type as **Auction**, select the **App promotion** objective, and click **Continue**

<img src="https://mintcdn.com/linkrunner-01ef8e08/ct-QjCqwwf0cx326/images/meta/first-campaign/objective-app-promotion.png?fit=max&auto=format&n=ct-QjCqwwf0cx326&q=85&s=c2b04973ac1a4594f62ca7b00655e7e3" alt="Create new campaign dialog with the App promotion objective selected" width="3200" height="2080" data-path="images/meta/first-campaign/objective-app-promotion.png" />

4. Enter a campaign name and click **Next**

<Note>
  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.
</Note>

### 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**

<img src="https://mintcdn.com/linkrunner-01ef8e08/ct-QjCqwwf0cx326/images/meta/first-campaign/ad-set-app-store.png?fit=max&auto=format&n=ct-QjCqwwf0cx326&q=85&s=4239fc5b24fe720a54a2e1444d2c392a" alt="Ad set editor with the Mobile app store dropdown and App name field highlighted" width="3200" height="2080" data-path="images/meta/first-campaign/ad-set-app-store.png" />

2. Set your **Budget & schedule**. Keep the budget low for the first campaign.
3. Define your **Audience** (locations, age, interests)
4. Leave **Advantage+ placements** on unless you have a reason not to
5. Click **Next**

<Note>
  If your app is not listed under **App name**, it is not registered with Meta or not linked to this ad account.
</Note>

### 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](#5-deferred-deep-linking) below.

<img src="https://mintcdn.com/linkrunner-01ef8e08/ct-QjCqwwf0cx326/images/meta/first-campaign/ad-destination-deferred-deep-link.png?fit=max&auto=format&n=ct-QjCqwwf0cx326&q=85&s=438caeaf04417a3a6b0edc61caa14fc8" alt="Ad editor Destination section with the Deferred deep link field highlighted" width="3200" height="2080" data-path="images/meta/first-campaign/ad-destination-deferred-deep-link.png" />

5. 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](https://dashboard.linkrunner.io/dashboard) 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

<img src="https://mintcdn.com/linkrunner-01ef8e08/ct-QjCqwwf0cx326/images/meta/first-campaign/linkrunner-campaigns-meta-filter.png?fit=max&auto=format&n=ct-QjCqwwf0cx326&q=85&s=2bfbc6e265d7566d13ad28ff066ad748" alt="Linkrunner Campaigns section with the channel filter open and Meta selected" width="1136" height="596" data-path="images/meta/first-campaign/linkrunner-campaigns-meta-filter.png" />

<Note>
  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.
</Note>

## 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.

<Note>
  Campaign, ad set, and ad creative rows appear in Linkrunner after they receive at least one install.
</Note>

### Meta App Promotion Deep Links

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](https://business.facebook.com/adsmanager)
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

<img src="https://mintcdn.com/linkrunner-01ef8e08/_LPKqZdvkG9FecNA/images/meta/meta-app-promotion-destination.png?fit=max&auto=format&n=_LPKqZdvkG9FecNA&q=85&s=5842f6c91d6aa13eb9fab71fbd032940" alt="Meta App Promotion Destination section with Deferred deep link and Custom store listing fields" width="465" height="446" data-path="images/meta/meta-app-promotion-destination.png" />

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.

<Note>
  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.
</Note>

<Info>
  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()`.
</Info>

<Warning>
  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.
</Warning>

### 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

### Campaign-Level Deep Links

Use this when every ad in the campaign should open the same destination.

1. Navigate to the **Campaigns** section in your [Linkrunner Dashboard](https://dashboard.linkrunner.io)
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

### Ad Set-Level Deep Links

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](https://dashboard.linkrunner.io)
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

<img src="https://mintcdn.com/linkrunner-01ef8e08/NqmCJqvi7Ia_bd5X/images/meta/ad-set-deeplink-modal.png?fit=max&auto=format&n=NqmCJqvi7Ia_bd5X&q=85&s=f7d5ea4f18df0e2a30471afd7a16f7a9" alt="Edit ad set deep link modal" width="580" height="355" data-path="images/meta/ad-set-deeplink-modal.png" />

If no ad set deep link is set, Linkrunner uses the campaign deep link.

### Ad Creative-Level Deep Links

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](https://dashboard.linkrunner.io)
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

<img src="https://mintcdn.com/linkrunner-01ef8e08/NqmCJqvi7Ia_bd5X/images/meta/ad-creative-deeplink-modal.png?fit=max&auto=format&n=NqmCJqvi7Ia_bd5X&q=85&s=85061691d97fa5406e812bdd71d34c85" alt="Edit ad creative deep link modal" width="582" height="351" data-path="images/meta/ad-creative-deeplink-modal.png" />

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`.

<Tabs>
  <Tab title="Without Facebook SDK">
    Add the following to your `AndroidManifest.xml`:

    ```xml theme={null}
    <meta-data android:name="com.linkrunner.FacebookApplicationId" android:value="@string/facebook_application_id" />
    ```

    And add your App ID to `strings.xml`:

    ```xml theme={null}
    <string name="facebook_application_id" translatable="false">YOUR_FACEBOOK_APP_ID</string>
    ```
  </Tab>

  <Tab title="With Facebook SDK">
    If you already have the Facebook SDK integrated, the Linkrunner SDK will automatically read the Facebook App ID from the existing `meta-data` tag. No additional configuration is needed.
  </Tab>
</Tabs>

### 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

<Note>
  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.
</Note>

For more details, see the [Meta Install Referrer](/features/meta-install-referrer) documentation.

Test the complete preview, install, and first attribution response with [Meta Android attribution testing](/testing/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](/ad-networks/meta-ads-discrepancies).

## Troubleshooting

### 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](#step-2-get-your-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

<Warning>
  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.
</Warning>

### 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

***

For any questions or assistance with Meta Ads integration, please contact us at [support@linkrunner.io](mailto:support@linkrunner.io).