<!--
AppSprint docs markdown
Canonical HTML: https://appsprint.app/docs/meta-ads
Markdown URL: https://appsprint.app/docs/meta-ads.md
Docs index: https://appsprint.app/docs.md
Sitemap: https://appsprint.app/sitemap.xml
LLM guide: https://appsprint.app/llms.txt
-->

# Meta Ads

A Meta Signal Campaign uses an AppSprint Signal link as the Website URL in Meta Ads Manager. AppSprint captures the Meta click, routes users to the store, forwards selected post-install events to Meta's Conversions API, and reports spend beside attributed installs and revenue.

## Requirements

- The AppSprint SDK installed and sending installs/events for this app.
- Full/Admin access to the Meta business portfolio, ad account, dataset, and Meta app used for OAuth.
- A Meta web dataset for this app in Events Manager.
- A Conversions API access token generated for the same dataset.
- A Meta Signal link in AppSprint, added as the Website URL in Meta ads.
- The AppSprint tracking domain added to the dataset Traffic Permissions / allowed websites.

## Available metrics and definitions

| Metric | Definition |
|--------|------------|
| Spend | Amount spent on the Meta campaign over the selected window. |
| Installs | Installs attributed by AppSprint. Falls back to Meta's reported conversion actions when AppSprint has no match. |
| CPI | Cost per install. Spend divided by attributed installs. |
| IPM | Installs per 1,000 impressions. |
| Impressions | Times the ad was shown, reported by Meta. |
| CPM | Cost per 1,000 impressions. |
| Clicks | Ad clicks, reported by Meta. |
| CPC | Cost per click. |
| CTR | Click-through rate. Clicks divided by impressions. |
| CTI | Click-to-install rate. Installs divided by clicks. |
| ROAS | Return on ad spend. Attributed revenue divided by spend. |
| Revenue | Revenue from in-app events attributed to this Signal Campaign. Falls back to Meta's reported value when AppSprint has no match. |

## Available in-app events and definitions

| Event | Definition |
|-------|------------|
| Achieve level | User reaches a level or milestone. |
| Add payment info | User enters or saves payment details. |
| Add to cart | User adds an item to the cart. |
| Complete registration | User finishes account creation. |
| Initiate checkout | User starts checkout. |
| Session | App open that creates a user session. |
| View content | User views a key screen or content item. |
| Start trial | User starts a free trial. |
| Subscribe | First paid subscription period begins. |
| Purchase | One-time purchase or non-subscription revenue event. |

## Default event mapping

AppSprint sends AppStack-style custom events prefixed with `appsprint_`. Leave a row blank in the dashboard to disable forwarding for that event.

> **All mapped events are sent:** The selected dataset receives mapped SDK, RevenueCat, and Superwall events. AppSprint sends these events to Meta; it does not receive event data back from Meta.

| AppSprint event | Meta custom event | Dashboard |
|-----------------|-------------------|-----------|
| install | appsprint_install | Optional row |
| purchase | appsprint_purchase | Primary row |
| subscribe | appsprint_subscribe | Primary row |
| start_trial | appsprint_start_trial | Primary row |
| add_payment_info | appsprint_add_payment_info | Primary row |
| add_to_cart | appsprint_add_to_cart | Primary row |
| initiate_checkout | appsprint_initiate_checkout | Primary row |
| view_content / view_item | appsprint_view_content | Primary row |
| sign_up / register | appsprint_complete_registration | Primary row |
| session_start | appsprint_session | Optional row |
| achieve_level / level_complete | appsprint_achieve_level | Optional row |

## Setup

### 1. Connect Meta Ads

OAuth lets AppSprint load ad accounts, datasets, and Signal Campaign reporting. It is separate from the Conversions API token used for server-side event forwarding.

1. In AppSprint, open your app and go to **Integrations > Meta Ads**.
2. Click **Connect Meta Ads** and sign in with the Meta user that has business and ad account access.
3. In Meta's access flow, select the correct business portfolio, ad account, and app access, then approve the requested permissions.
4. Back in AppSprint, select the ad account that owns the dataset and campaigns for this app.

### 2. Configure the Dataset ID and Conversions API token

> **Use one dataset for the whole setup.** The Dataset ID and Conversions API token must come from the same dataset. The dataset receives all mapped app events, not only AppSprint-attributed events, so choosing the wrong dataset sends your app's events to the wrong destination.

1. Open [Meta Events Manager](https://eventsmanager.facebook.com/) from the sidebar.
2. Click **+ Connect data**, choose **Web**, then select an existing dataset or create a new dataset for this app.
3. Choose **Setup Conversions API**, click **See other ways to setup**, then select manual setup.
4. If Meta asks you to select events or parameters, continue as lightly as possible. AppSprint only sends events to Meta; it does not receive events from Meta, and required parameters are sent automatically by AppSprint.
5. If Meta requires at least one event before continuing, select **Purchase**. This only unlocks Meta's setup flow; AppSprint still controls which events are sent.
6. On the **Using the Conversions API** page, scroll to **Generate an Access Token** and copy the token. Meta's official token instructions are here: https://developers.facebook.com/docs/marketing-api/conversions-api/get-started/#access-token
7. Copy the Dataset ID, test event code, and Conversions API token into AppSprint, then save.

### 3. Create the Signal link and allow the domain

1. In AppSprint, create or select the Meta Signal link, then copy the Website URL.
2. In Meta Events Manager, open the same dataset, go to **Settings**, then scroll to **Traffic Permissions / Websites**.
3. Click **Create an allow list**, add the AppSprint tracking domain from the Signal link, usually **api.appsprint.app**, then click **Confirm**. This is a dataset website allow-list, not DNS business-domain verification.
4. Meta custom-event review may appear only after the first test or production events arrive.

### 4. Test the Conversions API

In Meta Events Manager, open the dataset's **Test Events** view and copy the test event code. Paste it in AppSprint and send a test event.

> **A visible test event proves the dataset path.** If the event appears in Meta Test Events, the Dataset ID, token, and AppSprint backend route are working. Live campaign delivery still requires a real Meta click with `fbclid`, a matched install, and a mapped app/revenue event.

> **Meta may ask you to confirm custom events.** If Events Manager shows **Confirm custom event(s) that belong to you**, click **Review events**, acknowledge Meta's Business Tools terms, select all incoming events that start with `appsprint_`, click **Next**, choose **Confirm the custom event**, then click **Confirm**. AppSprint event names are generic and must not contain health, financial, consumer-report, or other sensitive data.

### 5. Map events and confirm custom events

In **Integrations > Meta Ads > Event mapping**, choose the AppSprint events you want to forward. AppSprint sends them as custom `appsprint_` events to the selected dataset.

> **Confirm custom events before optimizing.** After test or production events arrive, Meta may ask you to review custom events that belong to you. Click **Review events**, acknowledge the prompt, select every incoming `appsprint_` event, then confirm them before using them as campaign optimization goals.

Meta can take 30 to 90 minutes after receiving production event data before events appear in Events Manager and campaign setup. Test events are useful for debugging, but they do not unlock campaign optimization.

### 6. Create your first Meta Signal Campaign

1. In Meta Ads Manager, click **+ Create**.
2. Select **Sales** as the recommended objective.
3. At the ad set level, use **Website** as the conversion location, select the same dataset you saved in AppSprint, then choose the `appsprint_` event you want to optimize for.
4. At the ad set level, open **Placements**, choose manual placement controls or **Further limit the reach of your ads** if Meta shows the Advantage+ warning, then select mobile only. In the devices and operating system section, target only the advertised app's platform: iOS only or Android only. In **Platforms**, keep Facebook and Instagram selected, and turn off **Audience Network** for the first test.
5. At the ad level, paste the AppSprint Signal link into **Website URL**. Do not paste the URL parameters again in Meta's Tracking section.
6. Launch the campaign. First production events usually need 30 to 90 minutes before Meta surfaces them in Events Manager or campaign setup.

## Pre-launch checklist

1. **SDK**: The app has shipped with AppSprint configured and install/event tracking verified.
2. **Revenue source**: RevenueCat or Superwall is connected if subscription and purchase revenue should be forwarded.
3. **Meta setup**: OAuth, ad account, Dataset ID, Conversions API token, test event, event mapping, and Signal link are saved.
4. **Campaign setup**: The Meta ad uses the AppSprint Signal link as Website URL, the dataset matches AppSprint, and mobile OS targeting is correct.

## Troubleshooting

| Problem | What to try |
|---------|-------------|
| OAuth connection expired or missing permissions | Reconnect Meta Ads with a user that has access to the business portfolio, ad account, dataset, and Meta app. Approve the ads and business permissions again. |
| Ad accounts or campaigns do not load | Reconnect Meta Ads and confirm the selected Meta user can see the ad account in Business Settings. The Conversions API token does not grant reporting access. |
| Datasets do not load | Select the correct ad account, then click the reload icon next to Dataset ID. If Meta still does not return it, paste the Dataset ID manually. |
| Conversions API token rejected | Generate a new token from the same dataset in Events Manager, paste it in AppSprint, and save again. |
| Test event does not appear | Confirm the test_event_code, Dataset ID, and Conversions API token all belong to the same dataset. Then send the test again and keep the Meta Test Events tab open. |
| Events are not appearing in Events Manager | Wait 30 to 90 minutes after the first production event, then confirm the Signal link is used as the ad Website URL and the tracking domain, usually api.appsprint.app, is in the dataset Traffic Permissions website allow-list. |
| Custom events are not selectable for optimization | Meta may need incoming events before they appear. In Events Manager, click Review events, acknowledge Meta's prompt, select all appsprint_ custom events, choose Confirm the custom event, then retry campaign setup. |
| No deliveries after launching ads | Verify the ad uses the AppSprint Signal link as Website URL, the click URL includes fbclid, the SDK records the install, and the mapped SDK/RevenueCat/Superwall event fired after install. |
| Reporting numbers do not match Meta Ads Manager | AppSprint reports use AppSprint attribution. Meta reports use Meta's dataset and reporting model. Users without a matching Meta click can create differences. |

---

## Docs navigation

Use the Markdown URLs when reading the docs programmatically. Use the HTML URLs when you need the interactive docs UI.

- [Overview](https://appsprint.app/docs) ([Markdown](https://appsprint.app/docs.md)) — Introduction to AppSprint
- [Quickstart](https://appsprint.app/docs/quickstart) ([Markdown](https://appsprint.app/docs/quickstart.md)) — Get up and running in 5 minutes
- [React Native](https://appsprint.app/docs/react-native) ([Markdown](https://appsprint.app/docs/react-native.md)) — React Native / Expo SDK reference
- [iOS (Swift)](https://appsprint.app/docs/ios-swift) ([Markdown](https://appsprint.app/docs/ios-swift.md)) — Native Swift SDK reference
- [Android (Kotlin)](https://appsprint.app/docs/android) ([Markdown](https://appsprint.app/docs/android.md)) — Native Android SDK reference
- [Flutter](https://appsprint.app/docs/flutter) ([Markdown](https://appsprint.app/docs/flutter.md)) — Flutter plugin reference
- [RevenueCat](https://appsprint.app/docs/revenuecat) ([Markdown](https://appsprint.app/docs/revenuecat.md)) — Webhook integration for subscription attribution
- [Superwall](https://appsprint.app/docs/superwall) ([Markdown](https://appsprint.app/docs/superwall.md)) — Webhook integration for paywall attribution
- [Apple Search Ads](https://appsprint.app/docs/apple-search-ads) ([Markdown](https://appsprint.app/docs/apple-search-ads.md)) — Keyword and ad attribution
- [Google Ads](https://appsprint.app/docs/google-ads) ([Markdown](https://appsprint.app/docs/google-ads.md)) — Coming soon
- [TikTok Ads](https://appsprint.app/docs/tiktok-ads) ([Markdown](https://appsprint.app/docs/tiktok-ads.md)) — Events API server-side event forwarding
- [Meta Ads](https://appsprint.app/docs/meta-ads) ([Markdown](https://appsprint.app/docs/meta-ads.md)) — Conversions API server-side event forwarding