# @capgo/capacitor-facebook-analytics 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/

版本：8\.1\.19
npm 元数据更新时间：2026-10-15T06:49:40.696Z
中文译文更新时间：2026-11-09T04:48:56.586Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-facebook-analytics
原文对照：https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/?lang=original
项目主页：https://capgo.app/docs/plugins/facebook-analytics/
源码仓库：https://github.com/Cap-go/capacitor-facebook-analytics

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：116 kB，30 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-05-06T07:15:49.712Z
- 最新版本发布：2026-10-15T06:49:40.401Z
- 近 30 天下载量：12727（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

Meta/Facebook App Eventies 分析的电容插件.

## 安装

```sh
npm install @capgo/capacitor-facebook-analytics
```

也可以使用：`pnpm add @capgo/capacitor-facebook-analytics`、`yarn add @capgo/capacitor-facebook-analytics`、`bun add @capgo/capacitor-facebook-analytics`

## README

# @capgo/电容-面书-分析

从您的 Capacitor app 在 iOS 和 Android 上发送 Meta (Facebook) App Events, 以测量您的 Meta 广告活动的安装,购买和转换.

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-facebook-analytics)](https://capgo.app/?ref=plugin_facebook_analytics)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_facebook_analytics)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_facebook_analytics) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-facebook-analytics` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/capor-facebook-analysis到我的Capacitor应用上并把它接上_ [代理设置指南](https://capgo.app/agents/?ref=plugin_facebook_analytics) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_facebook_analytics)

![@capgo/capacitor-facebook-analytics for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-facebook-analytics/main/assets/github-social-preview.png)

## 主要特点

-   **应用事件**数字 : `initAppEvents()` 启动 Facebook SDK 并激活 App Events .
-   **自定义事件**数字 : `logEvent()` 记录任何带有参数的事件.
-   **采购**数字 : `logPurchase()` 用货币记录收入.
-   **广告跟踪**数字 : `enableAdvertiserTracking()`, (中文(简体) ), `disableAdvertiserTracking()` 财务报告和审定财务报表 `getAdvertiserTrackingStatus()`. 在iOS 17上以及后来的状态反映了App Track Introduction. 在iOS 16以及更早的时候,设置者会更改Facebook SDK旗.
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. 使用官方的Facebook SDKs. 事件日志无法上网 .

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

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

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
bun add @capgo/capacitor-facebook-analytics
bunx cap sync
```

## 使用量

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

## 原生设置

在您的本地应用程序中配置 Meta app id 和客户端符 。 此插件不会为您创建这些值 .

### iOS系统

将您的元值添加到应用程序 `Info.plist`数字 :

```xml
<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>
```

当广告商的追踪 被你同意的流,打电话 `enableAdvertiserTracking()` 在伐木活动之前.

如果自动 Meta App 事件记录被禁用(`FacebookAutoLogAppEventsEnabled` =: `false`因此,初始化可以等待同意,呼叫 `initAppEvents()` 只有在同意和ATT流出之后 在iOS上,这个在激活 App Events 之前初始化 FBSDK 。 关于Android, `FacebookInitProvider` 通常执行基本 `sdkInitialize()` 启动时 `AutoInitEnabled` 财务报告和审定财务报表 `AutoLogAppEventsEnabled` 控制全部初始化和自动事件记录; `initAppEvents()` 需要时完成基本输入(例如如果提供者被删除),然后调用 `activateApp()`不调用 `ApplicationDelegate.shared.initializeSDK()` 从 `AppDelegate` 在流出之前,它会启动Meta.

### 机器人

将您的元值添加到应用程序 `AndroidManifest.xml`数字 :

```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`数字 :

```xml
<string name="facebook_app_id">YOUR_FACEBOOK_APP_ID</string>
<string name="facebook_client_token">YOUR_FACEBOOK_CLIENT_TOKEN</string>
```

## 解决问题

### `"FacebookAnalytics" plugin is not implemented on android`

这通常意味着Capacitor没有注册本地的Android插件. 检查如下:

1.  运行 `bunx cap sync` 在安装或升级插件后.
2.  确认 `@capgo/capacitor-facebook-analytics` 在Android同步输出中列出.
3.  添加元数据 `ApplicationId` 财务报告和审定财务报表 `ClientToken` 从上面的Android设置部分录入.
4.  升级到 `@capgo/capacitor-facebook-analytics@8.1.7` 或更新 如果你在老建筑.

如果 Meta SDK 设置缺失,事件调用仍然可以以明显的错误拒绝,但一旦同步成功,插件本身应该在Android上注册.

## API 密码

-   [`initAppEvents()`](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-initappevents)
-   [`logEvent(...)`](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-logevent)
-   [`logPurchase(...)`](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-logpurchase)
-   [`enableAdvertiserTracking()`](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-enableadvertisertracking)
-   [`disableAdvertiserTracking()`](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-disableadvertisertracking)
-   [`getAdvertiserTrackingStatus()`](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-getadvertisertrackingstatus)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-type-aliases)

Facebook App Events 分析桥.

### initAppEvents () (英语)

```typescript
initAppEvents() => Promise<void>
```

初始化Facebook SDK并激活App Events.

当自动程序事件记录被禁用时调用, 您想要 在您同意后开始发送事件 .

在iOS上,这个初始化了主线程上的 FBSDK,然后激活 App 活动.

关于Android, `FacebookInitProvider` 通常运行基本的 SDK 设置通过 `FacebookSdk.sdkInitialize()` 在应用程序启动. `com.facebook.sdk.AutoInitEnabled` 控制路径是否也调用 `FacebookSdk.fullyInitialize()` (服务器通信). `com.facebook.sdk.AutoLogAppEventsEnabled` 自动控制 `activateApp()` 伐木业。 当提供者被移除时 (例如 `@capgo/capacitor-social-login`)或基本内涵从来 完成, 这种方法调用 `sdkInitialize()` 等待着它 `InitializeCallback`,然后通过 `setAutoInitEnabled(true)` 打电话前 `activateApp()`。 。 。 . `activateApp()` 光是SDK根本不够 初始化或仅基本初始化完成.

不初始化 Facebook 从 `AppDelegate` 同意的应用程序; 在用户获得广告计量同意后,拨打这种方法.

* * *

### 日志事件(...)

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

登录Facebook App事件.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[LogEventOptions](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-logeventoptions)` |

* * *

### 对数购买 (...)

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

登录Facebook购买活动 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[LogPurchaseOptions](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-logpurchaseoptions)` |

* * *

### 启用 Advertiser 跟踪 ()

```typescript
enableAdvertiserTracking() => Promise<void>
```

启用广告商跟踪 .

IOS 16 及以下各集 `Settings.shared.isAdvertiserTrackingEnabled`。 。 。 . 在iOS 17及以上 FBSDK v17+上直接读取App Track Track Transference. 在Android上,这个可以使广告商ID收藏.

* * *

### 禁用Advertiser跟踪()

```typescript
disableAdvertiserTracking() => Promise<void>
```

禁用广告商跟踪.

IOS 16 及以下各集 `Settings.shared.isAdvertiserTrackingEnabled`。 。 。 . 在iOS 17及以上 FBSDK v17+上直接读取App Track Track Transference. 在Android上,这禁用广告商的ID收藏.

* * *

### 获取 Advertiser 跟踪状态 ()

```typescript
getAdvertiserTrackingStatus() => Promise<AdvertiserTrackingStatusResult>
```

获取当前广告商跟踪状态.

在iOS 17及以上,这反映了App Track Introduction的授权.

**回返情况:** `Promise<[AdvertiserTrackingStatusResult](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-advertisertrackingstatusresult)>`

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<PluginVersionResult>
```

返回平台执行版本标记 .

**回返情况:** `Promise<[PluginVersionResult](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-pluginversionresult)>`

* * *

### 接口

#### 日志结果选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`event`** | `string` | Facebook标准事件名称或自定义应用事件名称. |
| **`valueToSum`** | `number` | 此事件的可选数值总和 . |
| **`currency`** | `string` | 具有价值的标准事件的可选ISO 4217货币代码. 这是作为Facebook传送的 `fb_currency` 事件参数. |
| **`params`** | `[FacebookEventParams](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-facebookeventparams)` | 可选事件参数. |

#### 日志购买选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`amount`** | `number` | 采购金额. |
| **`currency`** | `string` | ISO 4217货币编码. |
| **`params`** | `[FacebookEventParams](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-facebookeventparams)` | 可选购买参数. |

#### 广告跟踪状态

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`status`** | `boolean` | 目前广告商追踪状态. |

#### 插件变压器

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`version`** | `string` | 版本标识符由平台执行返回. |

### 类型异名

#### Facebook 活动Name

Facebook标准事件名称.

`(typeof [FacebookEventName](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-facebookeventname))[keyof typeof FacebookEventName]`

#### Facebook 活动

事件参数由Facebook标准参数名或自定义名称所键入.

`[Record](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-record)<[FacebookEventParameterName](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-facebookeventparametername) | string, [FacebookEventParamValue](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-facebookeventparamvalue)>`

#### 记录

构造 T 类型 K 的一组属性类型

`{ [P in K]: T; }`

#### 脸书EventParamValue

被本地的Facebook App Evolutions SDKs所接受的价值.

布尔值被转换为 Facebook 切换字符串 : `true` 变成 `"1"` 财务报告和审定财务报表 `false` 变成 `"0"`。 。 。 .

`string | number | boolean | null`

#### 脸书事件Comment

Facebook标准事件参数名.

`(typeof [FacebookEventParameterName](https://npmcn.com/package/%40capgo/capacitor-facebook-analytics/#readme-facebookeventparametername))[keyof typeof FacebookEventParameterName]`

## 常见问题

### @capgo/capacitor-facebook-analytics 是什么？

Meta/Facebook App Eventies 分析的电容插件\.

### 如何安装 @capgo/capacitor-facebook-analytics？

在项目目录运行 npm install @capgo/capacitor-facebook-analytics，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capgo/capacitor-facebook-analytics 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/capacitor-facebook-analytics 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capgo/capacitor-facebook-analytics 可以商用吗？

@capgo/capacitor-facebook-analytics 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-facebook-analytics 的下载量有多少？

根据 npm 官方下载统计，@capgo/capacitor-facebook-analytics 在 2026/10/09 – 2026/11/07 这 30 天内被下载 12,727 次，日均约 424 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/capacitor-facebook-analytics 还在维护吗？

最新版本 8\.1\.19 发布于 2026/10/15（25 天前）；至今共发布 20 个版本，其中过去 12 个月发布了 20 个；首次发布于 2026/05/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。