快速入门

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-facebook-analytics`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/facebook-analytics/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

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

然后使用以下 prompt：

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

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

npm install @capgo/capacitor-facebook-analytics
npx cap sync

导入

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

快速入门

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

// Initialize only after your consent or ATT flow allows analytics.
if (userGrantedAnalyticsConsent) {
  await FacebookAnalytics.initAppEvents();
}

示例：logEvent

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

await FacebookAnalytics.logEvent({ event: "fb_mobile_complete_registration" });

示例：logPurchase

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

await FacebookAnalytics.logPurchase({
  amount: 1,
  currency: "USD",
});

常见坑点

原生同步：运行 npx cap sync 在插件升级后。
唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

原生配置

在原生应用中配置您的 Meta app id 和 client token。该插件不会为您自动创建这些值。

iOS

将您的 Meta 配置添加到 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>

Android

将您的 Meta 配置添加到 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" />

在以下文件中添加字符串资源 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>

启用广告追踪

请在用户通过同意流程允许追踪后调用此方法。

await FacebookAnalytics.enableAdvertiserTracking();

在 iOS 17 及更高版本中，FBSDK v17+ 会直接读取 App Tracking Transparency。请在记录依赖追踪的事件之前，先执行应用的 ATT 流程。

记录标准事件

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

查看追踪状态

const { status } = await FacebookAnalytics.getAdvertiserTrackingStatus();
console.log('Advertiser tracking enabled:', status);

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 要规划原生插件工作，请将其与使用 @capgo/capacitor-facebook-analytics 在使用 @capgo/capacitor-facebook-analytics 时，获取原生能力的方法： Capgo 插件目录查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件查看由 Capgo 提供的 Capacitor 插件中的实现细节，添加或更新插件关于“添加或更新插件”中的实现细节，以及 Ionic Enterprise 插件替代方案关于“Ionic Enterprise 插件替代方案”中的产品工作流。