@caplugins/capacitor-meta-sdk

Capacitor plugin for Meta SDK integration. Fully typesafe, modular, and designed to support standard App Events, Purchases, and Advanced Matching via the Conversions API.

Install

npm install @caplugins/capacitor-meta-sdk
npx cap sync

Configuration

It is highly recommended to inject your Meta App ID and Client Token via Environment Variables or programmatic initialization.

iOS

If you are using programmatic initialization, no Info.plist changes are strictly required as you will pass the credentials via initialize().

However, if you want Facebook to auto-initialize or if you use deep linking, add the following to your Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
  <key>CFBundleURLSchemes</key>
  <array>
    <string>fb[YOUR_APP_ID]</string>
  </array>
  </dict>
</array>
<key>FacebookAppID</key>
<string>[YOUR_APP_ID]</string>
<key>FacebookClientToken</key>
<string>[YOUR_CLIENT_TOKEN]</string>
<key>FacebookDisplayName</key>
<string>[YOUR_APP_NAME]</string>

Note: You can use xcconfig files to inject these [YOUR_APP_ID] values via CI/CD environment variables.

Privacy Manifest (PrivacyInfo.xcprivacy)

Starting in Spring 2024, Apple requires third-party SDKs to include a privacy manifest.

The FBSDKCoreKit (which this plugin wraps) already includes its own PrivacyInfo.xcprivacy file starting from version 17.0.0. This manifest declares the data types the SDK collects by default and its tracking domains.

What you need to do: You do not need to manually copy Facebook's tracking domains into your app's privacy manifest (doing so may actually disrupt functionality). However, you must still ensure your app's own ios/App/PrivacyInfo.xcprivacy file accurately reflects any additional data you choose to send to Meta (e.g., specific custom events, user data for Advanced Matching) and your overall app's tracking practices.

Android

In your android/app/src/main/AndroidManifest.xml, add the following inside the <application> tag:

<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"/>

In your android/app/src/main/res/values/strings.xml, define the values:

<string name="facebook_app_id">[YOUR_APP_ID]</string>
<string name="facebook_client_token">[YOUR_CLIENT_TOKEN]</string>

Note: You can also inject these into strings.xml or via manifestPlaceholders in build.gradle using environment variables.

CI/CD and Publishing

This project includes fully configured GitHub Actions workflows for continuous integration and deployment.

• CI: Automatically runs npm run fmt, npm run lint, and npm run build on every Pull Request and push to main to catch regressions.
• Publishing: Whenever a new GitHub Release is published (e.g., v1.0.1), the release workflow will automatically build and publish the package to NPM using JS-DevTools/npm-publish.
  • Requirement: Ensure you have configured an NPM authentication token as a GitHub repository secret named NPM_TOKEN.

API Usage

1. App Tracking Transparency (iOS Only)

Apple requires applications to request permission before tracking users across apps and websites. In order to pass the correct Advertiser Tracking Enabled (ATE) flag to the Meta SDK, you must request tracking permission before initializing the SDK.

You can use the community plugin @capacitor-community/app-tracking-transparency for this:

import { AppTrackingTransparency } from '@capacitor-community/app-tracking-transparency';
import { MetaSDK } from '@caplugins/capacitor-meta-sdk';
import { Capacitor } from '@capacitor/core';

async function requestTrackingAndInitialize() {
  if (Capacitor.getPlatform() === 'ios') {
    const { status } = await AppTrackingTransparency.requestPermission();
    // Enable advertiser tracking if the user authorized it
    await MetaSDK.setAdvertiserTrackingEnabled({ enabled: status === 'authorized' });
  }

  // Then initialize the Meta SDK
  await MetaSDK.initialize({
    appId: process.env.VITE_META_APP_ID, // Use environment variables!
    clientToken: process.env.VITE_META_CLIENT_TOKEN,
    disabledPlatforms: ['web'], // Disable the web pixel if desired
    debug: true,
  });
}

Note: setAdvertiserTrackingEnabled is a safe no-op on Android and Web, so you can call it unconditionally if preferred.

2. Logging Standard Events:

await MetaSDK.logEvent({
  name: 'CompletedTutorial',
  parameters: {
    success: true,
    time_taken: 120,
  },
});

3. Logging Purchases:

await MetaSDK.logPurchase({
  amount: 29.99,
  currency: 'USD',
  parameters: {
    item_id: 'sub_123',
    tier: 'premium',
  },
});

4. Advanced Conversions API Matching: Set user data to improve match rates for Conversions API.

await MetaSDK.setUserData({
  email: '[email protected]',
  phone: '16505551234',
  external_id: 'user_xyz123',
});