@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/[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>

Activate Facebook App Events.

Call this when automatic app event logging is disabled and you want to explicitly mark the app as activated.

logEvent(...)

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

Log a Facebook App Event.

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | LogEventOptions |

logPurchase(...)

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

Log a Facebook purchase event.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | LogPurchaseOptions |

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

| Prop | Type | Description | | ---------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | event | string | Facebook standard event name or a custom app event name. | | valueToSum | number | Optional numeric value to sum for this event. | | currency | string | Optional ISO 4217 currency code for value-bearing standard events. This is forwarded as Facebook's fb_currency event parameter. | | params | FacebookEventParams | Optional event parameters. |

LogPurchaseOptions

| Prop | Type | Description | | -------------- | ------------------------------------------------------------------- | ----------------------------- | | amount | number | Purchase amount. | | currency | string | ISO 4217 currency code. | | params | FacebookEventParams | Optional purchase parameters. |

AdvertiserTrackingStatusResult

| Prop | Type | Description | | ------------ | -------------------- | ----------------------------------- | | status | boolean | Current advertiser tracking status. |

PluginVersionResult

| Prop | Type | Description | | ------------- | ------------------- | ----------------------------------------------------------- | | version | string | Version identifier returned by the platform implementation. |

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]