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

Meta Ads integration with Linkrunner enables you to track conversions and optimize your app campaigns directly within the Meta advertising platform. This integration allows you to send in-app events from your app to Meta as conversion events, providing better insights into your campaign performance and user behavior.

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

## 1. Configure Meta App Integration

This process connects your app with Meta's attribution and conversion tracking systems.

### 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 [Linkrunner Settings - Meta Integration](https://dashboard.linkrunner.io/settings?s=meta-integration)
2. Enter your **App ID** in the designated field
3. Enter your **Referrer Decryption Key**
4. Click **Save**

## 2. Set Up Event Mapping

Map your in-app events to Meta events to enable postback conversion tracking and campaign optimization.

<Note>
  **First app open** and **Sign up** events are captured and shared with Meta by default — no configuration needed for
  these events.
</Note>

### Step 1: Navigate to Event Mapping

1. In your Linkrunner Dashboard, go to the **Event Mapping** section for Meta
2. Click **Add Mapping** to create a new event mapping

### Step 2: Configure Event Mapping

1. **Select your app event** from the dropdown menu
2. **Select the corresponding Meta ad network event** (e.g., Purchase, AddToCart, ViewContent)
3. **Enable Send Revenue** if you want to share revenue data with Meta
   * Select the appropriate currency for revenue tracking
4. Click **Save** to create the mapping

### Step 3: Test Your Event Mappings

1. After creating your event mappings, you can test them by clicking the **Send** button
2. This will send a test event to Meta to verify the integration is working correctly
3. Check your Meta Events Manager to confirm the test event was received

<Tip>
  Start with basic events like Purchase before adding more complex custom events. This helps verify your integration
  is working correctly.
</Tip>

## 3. Configure Events in Meta Events Manager

After setting up event mapping in Linkrunner, you need to configure your Meta Events Manager to receive and process these events.

### Step 1: Access Events Manager

1. Go to [Meta Ads Dashboard](https://business.facebook.com/)
2. Navigate to **Events Manager** → **Datasets**

### Step 2: Select or Create Dataset

1. Select your existing dataset, or
2. Click **"+ Create Dataset"** if you haven't created one yet

### Step 3: Configure Conversions API

1. Navigate to **Settings** → **Conversions API**
2. Ensure your dataset is configured to receive events from Conversions API
3. Verify the connection status shows as active

### Step 4: View Incoming Events

1. Go to the **Events** tab in your dataset
2. You should see incoming events from Linkrunner
3. Events may take a few minutes to appear after initial setup

### Step 5: Create Custom Conversion Events

1. Go to **Conversions** → **Create Conversion Event**
2. To get started, select the **Purchase** event
3. Configure additional conversion events based on your campaign goals

<Note>
  It may take a few minutes for events to start appearing in Meta Events Manager after initial configuration. If
  events don't appear after 15 minutes, verify your App ID and Referrer Decryption Key are correct.
</Note>

## 4. Campaign Tracking

Once your integration is configured, Meta ad campaigns will automatically appear on the Linkrunner Dashboard as they go live.

### Automatic Campaign Detection

* **No manual setup required** — Campaigns are detected automatically
* **Real-time tracking** — See campaign performance as soon as ads start running
* **Attribution data** — Track installs, events, and revenue back to specific campaigns

### Viewing Campaign Data

1. Go to your [Linkrunner Dashboard](https://dashboard.linkrunner.io)
2. Navigate to the **Campaigns** section
3. Filter by **Meta** to see all your Meta ad campaigns
4. View detailed attribution and conversion data for each campaign

## 5. Deferred Deep Linking

Deferred deep linking allows you to direct users to specific in-app content after they install your app from a Meta ad campaign. When a user clicks on your ad and installs your app, the deferred deep link ensures they land on the exact content or screen you want them to see, creating a seamless user experience from ad to app.

Once configured in the Linkrunner dashboard, the deep link will be returned in the `getAttributionData` method of the Linkrunner SDK when the app is installed and opened for the first time. Your app can then use this deep link to navigate the user to the appropriate in-app destination.

<Note>
  Campaigns must generate at least one install before they appear in the Linkrunner dashboard. Once a campaign
  appears, you can configure deferred deep links at the campaign, ad set, or ad creative level.
</Note>

### When to Use Each Configuration Level

Choose the appropriate level based on how granular you want your deep linking strategy to be:

| Configuration Level   | Best For                                                                                                                                                              | Granularity |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Campaign Level**    | Consistent experience across all ads in a campaign. All users from any ad in the campaign will be directed to the same in-app destination.                            | Low         |
| **Ad Set Level**      | Targeting different audiences with different content. Each ad set can direct users to different in-app destinations based on audience segments or targeting criteria. | Medium      |
| **Ad Creative Level** | Highly personalized experiences based on specific ad content. Each individual ad can direct users to unique in-app destinations that match the ad's creative message. | High        |

<Tip>
  Start with campaign-level deep links for simplicity, then move to ad set or ad creative levels as your campaigns
  become more sophisticated and you need more granular control over user experiences.
</Tip>

### Campaign-Level Deep Links

Configure deferred deep links at the campaign level to provide a consistent user experience across all ads within a campaign.

<Note>
  Your Meta campaign must appear in the Linkrunner dashboard before you can add a deferred deep link. Campaigns appear
  automatically after they generate their first install.
</Note>

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 (e.g., `myapp://product/12345` or `https://myapp.com/product/12345`)
6. Click **Save** to apply the changes

All users who install your app from any ad within this campaign will be directed to the specified in-app destination upon first app open.

### Ad Set-Level Deep Links

Configure deferred deep links at the ad set level to provide different user experiences for different audience segments or targeting criteria. Ad set-level deep links can be configured independently from campaign-level deep links, giving you more granular control over where users land in your app.

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 (e.g., `myapp://category/electronics` or `https://myapp.com/category/electronics`)
6. Click **Save** to apply the changes

Users who install your app from ads within this specific ad set will be directed to the ad set's deep link destination. If no ad set-level deep link is configured, the campaign-level deep link (if set) will be used instead.

### Ad Creative-Level Deep Links

Configure deferred deep links at the ad creative level to provide highly personalized user experiences based on the specific ad content. This is the most granular level of deep link configuration, allowing each individual ad to direct users to unique in-app destinations that match the ad's creative message.

**Deep Link Configuration Hierarchy:**

When a user installs your app from a Meta ad, Linkrunner determines which deep link to use based on the following priority order:

1. **Ad Creative-Level** (highest priority) — If configured, this deep link is used
2. **Ad Set-Level** — If no ad creative-level deep link exists, the ad set-level deep link is used
3. **Campaign-Level** (lowest priority) — If neither ad creative nor ad set deep links exist, the campaign-level deep link is used

This hierarchy allows you to set a default deep link at the campaign level while overriding it for specific ad sets or individual ad creatives as needed.

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 (e.g., `myapp://product/12345?promo=summer` or `https://myapp.com/product/12345?promo=summer`)
6. Click **Save** to apply the changes

Users who install your app from this specific ad creative will be directed to the ad creative's deep link destination. This allows you to create highly targeted user journeys that align with the specific message, offer, or product featured in each ad.

<Tip>
  Use ad creative-level deep links when running A/B tests or promoting multiple products within the same campaign. For
  example, if one ad features a specific product, you can deep link directly to that product page in your app.
</Tip>

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

## 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 45 mins - 1 hour for initial events to propagate
* Test your event mappings using the Send button 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).