@capgo/capacitor-facebook-analytics

Capacitor plugin for Meta/Facebook App Events analytics on iOS and Android.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-facebook-analytics` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-facebook-analytics
bunx cap sync

Usage

import {
  FacebookAnalytics,
  FacebookEventName,
  FacebookEventParameterName,
} from '@capgo/capacitor-facebook-analytics';

await FacebookAnalytics.enableAdvertiserTracking();

await FacebookAnalytics.logEvent({
  event: FacebookEventName.CompletedRegistration,
  params: {
    [FacebookEventParameterName.RegistrationMethod]: 'email',
  },
});

await FacebookAnalytics.logEvent({
  event: FacebookEventName.AddedToCart,
  valueToSum: 19.99,
  currency: 'USD',
  params: {
    [FacebookEventParameterName.ContentType]: 'product',
    [FacebookEventParameterName.ContentId]: 'sku-123',
  },
});

await FacebookAnalytics.logPurchase({
  amount: 9.99,
  currency: 'USD',
});

Native Setup

Configure the Meta app id and client token in your native app. This plugin does not create those values for you.

iOS

Add your Meta values to the app Info.plist:

<key>FacebookAppID</key>
<string>YOUR_FACEBOOK_APP_ID</string>
<key>FacebookClientToken</key>
<string>YOUR_FACEBOOK_CLIENT_TOKEN</string>
<key>FacebookDisplayName</key>
<string>YOUR_APP_NAME</string>

When advertiser tracking is allowed by your consent flow, call enableAdvertiserTracking() before logging events.

Android

Add your Meta values to the app AndroidManifest.xml:

<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id" />
<meta-data android:name="com.facebook.sdk.ClientToken" android:value="@string/facebook_client_token" />

Add the string resources in android/app/src/main/res/values/strings.xml:

<string name="facebook_app_id">YOUR_FACEBOOK_APP_ID</string>
<string name="facebook_client_token">YOUR_FACEBOOK_CLIENT_TOKEN</string>

Troubleshooting

"FacebookAnalytics" plugin is not implemented on android

This usually means Capacitor did not register the native Android plugin. Check the following:

1. Run bunx cap sync after installing or upgrading the plugin.
2. Confirm @capgo/capacitor-facebook-analytics is listed in the Android sync output.
3. Add the Meta ApplicationId and ClientToken entries from the Android setup section above.
4. Upgrade to @capgo/capacitor-facebook-analytics@8.1.7 or newer if you are on an older build.

If Meta SDK setup is missing, event calls can still reject with a clear error, but the plugin itself should register on Android once sync succeeds.

API

initAppEvents() => Promise<void>

logEvent(options: LogEventOptions) => Promise<void>

logPurchase(options: LogPurchaseOptions) => Promise<void>

enableAdvertiserTracking() => Promise<void>

disableAdvertiserTracking() => Promise<void>

getAdvertiserTrackingStatus() => Promise<AdvertiserTrackingStatusResult>

getPluginVersion() => Promise<PluginVersionResult>