@capgo/capacitor-facebook-analytics

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

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

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

await FacebookAnalytics.enableAdvertiserTracking();
await FacebookAnalytics.initAppEvents();

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',
});

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

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.

If automatic Meta App Event logging is disabled (FacebookAutoLogAppEventsEnabled = false) so initialization can wait for consent, call initAppEvents() only after that consent and ATT flow. On iOS this initializes FBSDK before activating App Events. On Android, FacebookInitProvider normally performs basic sdkInitialize() at startup while AutoInitEnabled and AutoLogAppEventsEnabled control full initialization and automatic event logging; initAppEvents() completes basic init when needed (for example if the provider was removed) and then calls activateApp(). Do not call ApplicationDelegate.shared.initializeSDK() from AppDelegate in that flow; it would start Meta before those gates pass.

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>

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.

• initAppEvents()
• logEvent(...)
• logPurchase(...)
• enableAdvertiserTracking()
• disableAdvertiserTracking()
• getAdvertiserTrackingStatus()
• getPluginVersion()
• Interfaces
• Type Aliases

Facebook App Events analytics bridge.

initAppEvents() => Promise<void>

Initialize the Facebook SDK and activate App Events.

Call this when automatic app event logging is disabled and you want to start sending events after your consent / ATT flow.

On iOS this initializes FBSDK on the main thread, then activates App Events.

On Android, FacebookInitProvider normally runs basic SDK setup via FacebookSdk.sdkInitialize() at app start. com.facebook.sdk.AutoInitEnabled controls whether that path also calls FacebookSdk.fullyInitialize() (server communication). com.facebook.sdk.AutoLogAppEventsEnabled controls automatic activateApp() logging. When the provider was removed (for example by @capgo/capacitor-social-login) or basic init never completed, this method calls sdkInitialize() and waits for its InitializeCallback, then enables full initialization via setAutoInitEnabled(true) before calling activateApp(). activateApp() alone is not enough when the SDK was never initialized or only basic initialization completed.

Do not initialize Facebook from AppDelegate for consent-gated apps; call this method after the user grants advertising measurement consent.

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

Log a Facebook App Event.

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

Log a Facebook purchase event.

enableAdvertiserTracking() => Promise<void>

Enable advertiser tracking.

On iOS 16 and below this sets Settings.shared.isAdvertiserTrackingEnabled. On iOS 17 and above FBSDK v17+ reads App Tracking Transparency directly. On Android this enables advertiser ID collection.

disableAdvertiserTracking() => Promise<void>

Disable advertiser tracking.

On iOS 16 and below this sets Settings.shared.isAdvertiserTrackingEnabled. On iOS 17 and above FBSDK v17+ reads App Tracking Transparency directly. On Android this disables advertiser ID collection.

getAdvertiserTrackingStatus() => Promise<AdvertiserTrackingStatusResult>

Get the current advertiser tracking status.

On iOS 17 and above this reflects App Tracking Transparency authorization.

Returns: Promise<AdvertiserTrackingStatusResult>

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Facebook standard event names.

(typeof FacebookEventName)[keyof typeof FacebookEventName]

Event parameters keyed by Facebook standard parameter names or custom names.

Record<FacebookEventParameterName | string, FacebookEventParamValue>

Construct a type with a set of properties K of type T

{ [P in K]: T; }

Values accepted by the native Facebook App Events SDKs.

Boolean values are converted to Facebook toggle strings: true becomes "1" and false becomes "0".

string | number | boolean | null

Facebook standard event parameter names.

(typeof FacebookEventParameterName)[keyof typeof FacebookEventParameterName]