> For the complete documentation index, see [llms.txt](https://docs.buildnatively.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildnatively.com/natively-platform/features/analytics/facebook.md).

# Facebook

## What is Facebook Analytics?

Facebook (Meta) Analytics lets you track how users interact with your app and measure the performance of your Facebook and Instagram ad campaigns. It logs standard events automatically (app installs, sessions, purchases) and lets you send custom events to understand deeper engagement.

## Prerequisites

{% hint style="success" %}
This feature requires the **Unlimited** or **Lifetime** plan. [See all plans](/getting-started/subscription-plans.md)
{% endhint %}

* A [Facebook Developer](https://developers.facebook.com/) account.
* **iOS:**
  * Your iOS app is already [published](/natively-platform/app-info/ios-build.md) in the Natively Dashboard.
* **Android:**
  * Your Android app is already [published](/natively-platform/app-info/android-build.md) in the Natively Dashboard.
  * Your app is [uploaded](https://support.google.com/googleplay/android-developer/answer/9845334#zippy=%2Cinternal-test-manage-up-to-testers) to the **Google Play Console** - required to access SHA-1 signing certificate fingerprints.

## Facebook Configuration

{% stepper %}
{% step %}

### Create your Facebook app

1. Go to [My Apps](https://developers.facebook.com/apps/) in Meta for Developers and click **Create App**.
2. Select **None** as the app type.
3. Enter your **app name** and **contact email**.

<div><figure><img src="/files/maGo3q81idWqAY3uaVQF" alt="" width="188"><figcaption><p>Step 1</p></figcaption></figure> <figure><img src="/files/t1ACEPCXI8vMyNJ6GVsk" alt="" width="188"><figcaption><p>Step 2</p></figcaption></figure> <figure><img src="/files/DFrHqo9vJge1GhSRLprj" alt="" width="188"><figcaption><p>Step 3</p></figcaption></figure></div>
{% endstep %}

{% step %}

### Configure your platform(s)

1. In your app, go to **Settings** > **Basic**.
2. Scroll down and click **Add platform**.
3. Select **Android** or **iOS**, and click **Next**.

<div><figure><img src="/files/V9nhcrZUDoBIJupqwdVu" alt="" width="188"><figcaption><p>Step 1</p></figcaption></figure> <figure><img src="/files/fYDa4IznKl1eU3syM431" alt="" width="188"><figcaption><p>Step 2-3</p></figcaption></figure></div>

{% tabs %}
{% tab title="Android" %}
{% hint style="info" %}
Natively supports **Google Play**. Other Android app stores may work but are unsupported.
{% endhint %}

1. In **Add platform**, select **Google Play** from the list of stores.
2. Generate your **Key Hash**:
   1. Go to your **Google Play Console**, open your app's page, and navigate to **Protected With Play** > **Play Store protection** > **Protect app signing key** > **Manage Play App Signing**.
   2. Copy the **SHA-1 certificate fingerprint** under **Upload key certificate**.
   3. Go to a [Hex to Base64 converter](https://base64.guru/converter/encode/hex).
   4. Paste your SHA-1 value and click **Convert Hex to Base64**.
   5. Copy the resulting Base64 value.
   6. Repeat for the **App signing key certificate** SHA-1 fingerprint.
3. Paste both Base64 values into the **Key hashes** field.
4. Enter your **Package Name** - found in the Natively Dashboard under **Publish** > **Android Build** > **Bundle Identifier**.
5. Enter your **Class Name**: `{YOUR_ANDROID_APP_BUNDLE_ID}.MainActivity` - e.g. `com.example.natively.MainActivity`
6. Click **Save changes**.
7. Go to **Settings** > **Advanced**, and copy your **Client Token** and **App ID**.

{% hint style="warning" %}
The App ID and Client Token are the same for iOS and Android - if you support both platforms, you only need to enter them once, but you must rebuild each app separately.
{% endhint %}

<div><figure><img src="/files/4auZlfwilmhNVgVyH3be" alt="" width="188"><figcaption><p>Step 1</p></figcaption></figure> <figure><img src="/files/ReoNA0pNzW0p3SHHztJc" alt="" width="188"><figcaption><p>Step 2.a</p></figcaption></figure> <figure><img src="/files/y3t4hsfdD3HXIEFVr62V" alt="" width="188"><figcaption><p>Step 2.b, 2.f</p></figcaption></figure> <figure><img src="/files/epr5k4CsRSZEWagk6Yp6" alt="" width="188"><figcaption><p>Step 2.c-2.e</p></figcaption></figure> <figure><img src="/files/ndUf5KYZOXwb61CuDjsd" alt="" width="188"><figcaption><p>Step 3</p></figcaption></figure> <figure><img src="/files/4hbqVfsEXGaygcg1i6ZA" alt="" width="188"><figcaption><p>Step 4-5</p></figcaption></figure> <figure><img src="/files/ffKlOc1QPJxeXnXcUPtd" alt="" width="188"><figcaption><p>Step 6-7</p></figcaption></figure></div>
{% endtab %}

{% tab title="iOS" %}

1. Enter your **Bundle ID** - found in the Natively Dashboard under **Publish** > **iOS Build** > **Bundle Identifier**.
2. Enter your **iPhone/iPad Store ID** - found in the Natively Dashboard under **Publish** > **iOS Build** > **App Store App ID**. This value is the same for iPhone and iPad (if [iPad Support](/natively-platform/settings.md#ipad-support-only-for-ios) is enabled).
3. Click **Save changes**.
4. Go to **Settings** > **Advanced**, and copy your **Client Token** and **App ID**.

{% hint style="warning" %}
The App ID and Client Token are the same for iOS and Android - if you support both platforms, you only need to enter them once, but you must rebuild each app separately.
{% endhint %}

<div><figure><img src="/files/F7ZdNdvITRl6d8NLzXa4" alt="" width="188"><figcaption><p>Step 1-3</p></figcaption></figure> <figure><img src="/files/s5epe296NKHfAA1J5Emr" alt="" width="188"><figcaption><p>Step 4</p></figcaption></figure></div>
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

## Natively Dashboard Setup

1. Open your Natively app dashboard and navigate to **Features** > **Analytics** > **Facebook**.
2. Toggle the feature to **Enabled**.
3. Enter the **App ID** and **Client Token** you copied from Facebook.
4. *(iOS only)* Enter the **Permission Description**.
5. Click **Save**.
6. Rebuild your app(s).

{% hint style="info" %}
The **Permission Description** is the text shown to iOS users when the OS asks them to grant tracking permission (App Tracking Transparency). This field only applies to iOS. Explain clearly why your app needs this permission - for example: "We use your data to provide personalized advertisements that are relevant to your interests".
{% endhint %}

{% hint style="warning" %}
You must rebuild your app for these changes to take effect.
{% endhint %}

## Implementation

Natively doesn't expose a dedicated Facebook-specific method - standard events (app installs, sessions, and purchases) are logged automatically once configured, with no additional call required.

For any event beyond the automatic ones - such as `registration_completed` or `viewed_product` - send it yourself using [Custom Event](/natively-platform/features/analytics/custom-event.md). These events cannot be configured entirely within the Facebook Events Manager; the dashboard can map, report, and optimize on events, but your app must actually send each event at the moment the action happens.

{% content-ref url="/pages/bhZtyuAB014fEBKEjDEi" %}
[Custom Event](/natively-platform/features/analytics/custom-event.md)
{% endcontent-ref %}

### How to use

{% hint style="warning" %}
Facebook's Events Manager data isn't real-time. Standard events typically appear within seconds to minutes, but delivery timing can vary - Facebook's own documentation notes it can take up to 30 minutes in some cases. Don't assume a missing event is broken until you've allowed for this delay.
{% endhint %}

#### Standard events are logged automatically; no setup needed

Once configured, app installs, sessions, and in-app purchases are tracked without any additional call.

#### Use Custom Event for everything beyond standard events

For engagement, feature usage, or funnel tracking, use [Custom Event](/natively-platform/features/analytics/custom-event.md) - it's forwarded to Facebook automatically once configured.

#### Stick to Facebook's event name limit

Facebook allows up to 1,000 distinct event names per app - reuse a small, consistent set of event names rather than generating dynamic ones per event.

#### Verify your integration before launching campaigns

Use Facebook's Test Events tool (see [Testing](/natively-platform/features/analytics/custom-event.md#facebook) on the Custom Event page) to confirm events are actually reaching Facebook before you spend budget attributing campaigns to it.

## Troubleshooting

<details>

<summary>Standard events aren't showing up on Facebook</summary>

Go through this checklist:

* Confirm the feature is enabled and both the App ID and Client Token are entered correctly in the Natively Dashboard.
* Confirm the app has been rebuilt.
* Confirm you've allowed enough time for data to propagate.

</details>

<details>

<summary>iOS setup fails, or the app isn't recognized</summary>

Confirm your **Bundle ID** and **iPhone/iPad Store ID** exactly match what's configured in the Natively Dashboard.

</details>

<details>

<summary>Android setup fails, or the app isn't recognized</summary>

Confirm both Key Hash values (Upload key and App signing key) were correctly converted from SHA-1 to Base64, and that your **Package Name** and **Class Name** exactly match your app's configuration.

</details>

<details>

<summary>Not working in a web browser or the Natively Preview app</summary>

This is a native feature and does not work in a standard web browser or in the Natively Preview app. Test on a real device using a full Natively build.

</details>