@capgo/capacitor-facebook-analytics

Send Meta (Facebook) App Events from your Capacitor app on iOS and Android to measure installs, purchases and conversions for your Meta ad campaigns.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-facebook-analytics in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-facebook-analytics to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• App Events: initAppEvents() starts the Facebook SDK and activates App Events.
• Custom events: logEvent() logs any event with parameters.
• Purchases: logPurchase() logs revenue with currency.
• Advertiser tracking: enableAdvertiserTracking(), disableAdvertiserTracking() and getAdvertiserTrackingStatus(). On iOS 17 and later the status reflects App Tracking Transparency. On iOS 16 and earlier the setters change the Facebook SDK flag.
• Platforms: iOS and Android. Uses the official Facebook SDKs. Event logging is not available on web.

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

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.

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.

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/[email protected] 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()
• logEvent(...)
• logPurchase(...)
• enableAdvertiserTracking()
• disableAdvertiserTracking()
• getAdvertiserTrackingStatus()
• getPluginVersion()
• Interfaces
• Type Aliases

Facebook App Events analytics bridge.

initAppEvents()

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

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

Log a Facebook App Event.

logPurchase(...)

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

Log a Facebook purchase event.

enableAdvertiserTracking()

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()

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()

getAdvertiserTrackingStatus() => Promise<AdvertiserTrackingStatusResult>

Get the current advertiser tracking status.

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

Returns: Promise<AdvertiserTrackingStatusResult>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Interfaces

LogEventOptions

LogPurchaseOptions

AdvertiserTrackingStatusResult

PluginVersionResult

Type Aliases

FacebookEventName

Facebook standard event names.

(typeof FacebookEventName)[keyof typeof FacebookEventName]

FacebookEventParams

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

Record<FacebookEventParameterName | string, FacebookEventParamValue>

Record

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

{ [P in K]: T; }

FacebookEventParamValue

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

FacebookEventParameterName

Facebook standard event parameter names.

(typeof FacebookEventParameterName)[keyof typeof FacebookEventParameterName]