# @capawesome/capacitor-posthog 中文文档

规范地址：https://npmcn.com/package/%40capawesome/capacitor-posthog/

版本：8\.6\.2
npm 元数据更新时间：2026-09-10T19:09:53.693Z
中文译文更新时间：2026-11-09T03:12:52.968Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/capacitor-posthog
原文对照：https://npmcn.com/package/%40capawesome/capacitor-posthog/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/posthog/
源码仓库：https://github.com/capawesome-team/capacitor-plugins

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

- 包体积（解压后）：260 kB，74 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：posthog-js ^1\.306\.2，@capacitor/core \>=8\.0\.0
- 首次发布：2024-09-06T09:48:23.096Z
- 最新版本发布：2026-09-10T19:09:53.362Z
- 近 30 天下载量：57296（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 16 个）

## 中文简介

Android,iOS,和Web上的PostHog SDK的非官方Capacitor插件.

## 安装

```sh
npm install @capawesome/capacitor-posthog
```

也可以使用：`pnpm add @capawesome/capacitor-posthog`、`yarn add @capawesome/capacitor-posthog`、`bun add @capawesome/capacitor-posthog`

## README

# 电容 PostHog 插件

非官方电容插件 [邮箱](https://posthog.com/)\[^1\]

[![Deliver Live Updates to your Capacitor app with Capawesome Cloud](https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1)](https://cloud.capawesome.io/)

## 使用大小写

PostHog插件一般用来理解用户如何与应用程序互动,例如:

-   **产品分析**: 抓取自定义事件并屏幕视图以分析用户如何通过您的应用程序移动.
-   **用户识别**: 识别有明显身份的用户,指定别名,并将其活动与团体联系起来.
-   **地物标志**:通过在运行时检查特征标志及其有效载荷,逐步推出特征.
-   **会话重放**: 记录用户会话,以了解使用模式并调试问题.
-   **跟踪错误**: 手动或自动抓取例外以监视应用程序的稳定性.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 8.x.x (英语) | \>=8.x.x | 积极支持 |
| 7.x.x (中文(简体) ) | 7.x.x (中文(简体) ) | 折旧 |

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-posthog` plugin in my project.
```

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

```bash
npm install @capawesome/capacitor-posthog posthog-js
npx cap sync
```

### 机器人

#### 变量

如果需要, 您可以在您的应用程序中定义以下工程变量 `variables.gradle` 要更改依赖的默认版本的文件 :

-   `$androidxCoreKtxVersion` 版本 `androidx.core:core-ktx` (默认 : `1.13.1`(中文(简体) )
-   `$posthogVersion` 版本 `com.posthog:posthog-android` (默认 : `3.27.2`(中文(简体) )

如果您在工程中遇到其它插件的依赖性冲突, 这会有所帮助 .

## 配置

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`apiKey`** | `string` | 您 PostHog 项目的 API 密钥 . |  | 7.1.0 (中文(简体) ) |
| **`apiHost`** | `string` | 您 PostHog 实例或反向代理的 API 主机 . | `'https://us.i.posthog.com'` | 8.3.0 (单位:千美元) |
| **`host`** | `string` | 您 PostHog 实例的 API 主持人 。 折旧的别名 `apiHost`。 。 。 . | `'https://us.i.posthog.com'` | 7.1.0 (中文(简体) ) |
| **`uiHost`** | `string` | PostHog UI 主机使用时 `apiHost` 指向反向代理。 仅在Web上提供. |  | 8.3.0 (单位:千美元) |
| **`enableSessionReplay`** | `boolean` | 是否自动启用会话记录 . | `false` | 7.3.0 (单位:千美元) |
| **`sessionReplayConfig`** | `[SessionReplayOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-sessionreplayoptions)` | 会话记录配置选项 . |  | 7.3.0 (单位:千美元) |
| **`captureApplicationLifecycleEvents`** | `boolean` | 是否抓取应用程序生命周期事件 . | `true` | 8.3.0 (单位:千美元) |
| **`autoCaptureExceptions`** | `boolean` | 是否自动抓取未处理的例外 . | `false` | 8.5.0 (中文(简体) ) |

### 实例

单位 `capacitor.config.json`数字 :

```json
{
  "plugins": {
    "Posthog": {
      "apiKey": 'phc_g8wMenebiIQ1pYd5v9Vy7oakn6MczVKIsNG5ZHCspdy',
      "apiHost": 'https://eu.i.posthog.com',
      "host": 'https://eu.i.posthog.com',
      "uiHost": 'https://eu.posthog.com',
      "enableSessionReplay": undefined,
      "sessionReplayConfig": undefined,
      "captureApplicationLifecycleEvents": undefined,
      "autoCaptureExceptions": undefined
    }
  }
}
```

单位 `capacitor.config.ts`数字 :

```ts
/// <reference types="@capawesome/capacitor-posthog" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Posthog: {
      apiKey: 'phc_g8wMenebiIQ1pYd5v9Vy7oakn6MczVKIsNG5ZHCspdy',
      apiHost: 'https://eu.i.posthog.com',
      host: 'https://eu.i.posthog.com',
      uiHost: 'https://eu.posthog.com',
      enableSessionReplay: undefined,
      sessionReplayConfig: undefined,
      captureApplicationLifecycleEvents: undefined,
      autoCaptureExceptions: undefined,
    },
  },
};

export default config;
```

## 演示

这里有一个实例: [robingenz/电容器-插管-demo](https://github.com/robingenz/capacitor-plugin-demo)

## 使用量

以下例子显示如何设置SDK,抓取事件,跟踪屏幕视图,识别用户,与一组联系用户,管理超级属性,重置用户,并冲出队列事件.

### 设置 SDK

打电话 `setup(...)` 在任何其他方法之前。 或者,在Android和iOS上,您可以在 Capacitor 配置文件中配置插件(参见 [配置](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-configuration))),在这种情况下,你决不能称这种方法:

```typescript
import { Posthog } from '@capawesome/capacitor-posthog';

const setup = async () => {
  await Posthog.setup({
    apiKey: 'YOUR_API_KEY',
    apiHost: 'https://eu.i.posthog.com',
  });
};
```

### 捕获事件

抓取带有可选属性的自定义事件 :

```typescript
import { Posthog } from '@capawesome/capacitor-posthog';

const capture = async () => {
  await Posthog.capture({
    event: 'event',
    properties: {
      key: 'value',
    },
  });
};
```

### 音轨屏幕视图

发送带有屏幕标题的屏幕事件 。 仅在Android和iOS上提供:

```typescript
import { Posthog } from '@capawesome/capacitor-posthog';

const screen = async () => {
  await Posthog.screen({
    screenTitle: 'screen',
    properties: {
      key: 'value',
    },
  });
};
```

### 识别用户

识别当前拥有不同ID和设定人物属性的用户。 您也可以使用 : `alias(...)`数字 :

```typescript
import { Posthog } from '@capawesome/capacitor-posthog';

const identify = async () => {
  await Posthog.identify({
    distinctId: 'distinct-id',
    userProperties: {
      key: 'value',
    },
  });
};

const alias = async () => {
  await Posthog.alias({
    alias: 'new-distinct-id',
  });
};
```

### 与一组联系的用户

将当前用户的事件与一个团体,例如公司或团队联系起来:

```typescript
import { Posthog } from '@capawesome/capacitor-posthog';

const group = async () => {
  await Posthog.group({
    type: 'group',
    key: 'key',
    groupProperties: {
      key: 'value',
    },
  });
};
```

### 管理超级属性

登记每个事件发送的超级财产,并在不再需要时取消登记:

```typescript
import { Posthog } from '@capawesome/capacitor-posthog';

const register = async () => {
  await Posthog.register({
    key: 'super-property',
    value: 'super-value',
  });
};

const unregister = async () => {
  await Posthog.unregister({
    key: 'super-property',
  });
};
```

### 重置用户

重置当前用户的ID和匿名ID, 例如在登录后 :

```typescript
import { Posthog } from '@capawesome/capacitor-posthog';

const reset = async () => {
  await Posthog.reset();
};
```

### Flush 队列事件

手动冲洗队列中的所有事件 。 仅在Android和iOS上提供:

```typescript
import { Posthog } from '@capawesome/capacitor-posthog';

const flush = async () => {
  await Posthog.flush();
};
```

## API 密码

-   [`alias(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-alias)
-   [`capture(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-capture)
-   [`captureException(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-captureexception)
-   [`flush()`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-flush)
-   [`getDistinctId()`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-getdistinctid)
-   [`getFeatureFlag(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-getfeatureflag)
-   [`getFeatureFlagPayload(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-getfeatureflagpayload)
-   [`getSessionId()`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-getsessionid)
-   [`group(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-group)
-   [`identify(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-identify)
-   [`isFeatureEnabled(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-isfeatureenabled)
-   [`isOptOut()`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-isoptout)
-   [`optIn()`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-optin)
-   [`optOut()`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-optout)
-   [`register(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-register)
-   [`reloadFeatureFlags()`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-reloadfeatureflags)
-   [`reset()`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-reset)
-   [`screen(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-screen)
-   [`setPersonProperties(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-setpersonproperties)
-   [`setup(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-setup)
-   [`startSessionRecording()`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-startsessionrecording)
-   [`stopSessionRecording()`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-stopsessionrecording)
-   [`unregister(...)`](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-unregister)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-type-aliases)

### 别名(...)

```typescript
alias(options: AliasOptions) => Promise<void>
```

向当前用户指定另一个不同的ID .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[AliasOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-aliasoptions)` |

**自:** 6.0.0 (单位:千美元)

* * *

### 抓取(...)

```typescript
capture(options: CaptureOptions) => Promise<void>
```

抓住一个事件.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[CaptureOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-captureoptions)` |

**自:** 6.0.0 (单位:千美元)

* * *

### 抓取例外(...)

```typescript
captureException(options: CaptureExceptionOptions) => Promise<void>
```

抓住一个例外.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[CaptureExceptionOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-captureexceptionoptions)` |

**自:** 8.5.0 (中文(简体) )

* * *

### 冲号( )

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

将队列中的所有事件浮出水面 .

仅在Android和iOS上提供.

**自:** 6.0.0 (单位:千美元)

* * *

### 获取 DistinctId ()

```typescript
getDistinctId() => Promise<GetDistinctIdResult>
```

获取当前识别身份.

**回返情况:** `Promise<[GetDistinctIdResult](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-getdistinctidresult)>`

**自:** 8.2.0 (中文(简体) )

* * *

### 获取 FeatureFlag (...)

```typescript
getFeatureFlag(options: GetFeatureFlagOptions) => Promise<GetFeatureFlagResult>
```

获取特征旗的值 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetFeatureFlagOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-getfeatureflagoptions)` |

**回返情况:** `Promise<[GetFeatureFlagResult](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-getfeatureflagresult)>`

**自:** 7.0.0 (单位:千美元)

* * *

### 获取 FeatureFlagPayload (...)

```typescript
getFeatureFlagPayload(options: GetFeatureFlagPayloadOptions) => Promise<GetFeatureFlagPayloadResult>
```

获取特性旗的有效载荷.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetFeatureFlagPayloadOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-getfeatureflagpayloadoptions)` |

**回返情况:** `Promise<[GetFeatureFlagPayloadResult](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-getfeatureflagpayloadresult)>`

**自:** 7.1.0 (中文(简体) )

* * *

### 获取会议( )

```typescript
getSessionId() => Promise<GetSessionIdResult>
```

获取当前会话编号 .

**回返情况:** `Promise<[GetSessionIdResult](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-getsessionidresult)>`

**自:** 8.6.0 (简体中文)

* * *

### 组(...)

```typescript
group(options: GroupOptions) => Promise<void>
```

把那个用户的事件和一群人联系起来.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GroupOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-groupoptions)` |

**自:** 6.0.0 (单位:千美元)

* * *

### 标识(...)

```typescript
identify(options: IdentifyOptions) => Promise<void>
```

识别当前用户 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[IdentifyOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-identifyoptions)` |

**自:** 6.0.0 (单位:千美元)

* * *

### feature 启用(...)

```typescript
isFeatureEnabled(options: IsFeatureEnabledOptions) => Promise<IsFeatureEnabledResult>
```

检查是否启用了特性旗 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[IsFeatureEnabledOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-isfeatureenabledoptions)` |

**回返情况:** `Promise<[IsFeatureEnabledResult](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-isfeatureenabledresult)>`

**自:** 7.0.0 (单位:千美元)

* * *

### optout () (中文(简体) )

```typescript
isOptOut() => Promise<IsOptOutResult>
```

检查用户是否选择了不抓取 .

**回返情况:** `Promise<[IsOptOutResult](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-isoptoutresult)>`

**自:** 8.1.0 联合国

* * *

### 选择IN( )

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

选择到事件捕获.

**自:** 8.1.0 联合国

* * *

### 选择退出( C)

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

选择退出事件捕获.

在网络上与 `cookielessMode: 'on_reject'`切换到无饼干匿名追踪. 在iOS/Android上:完全停止所有事件捕获.

**自:** 8.1.0 联合国

* * *

### 注册(...)

```typescript
register(options: RegisterOptions) => Promise<void>
```

登记一个新的超级财产。 每次活动都会送出这个地产.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[RegisterOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-registeroptions)` |

**自:** 6.0.0 (单位:千美元)

* * *

### 重新装入FeatureFlags ()

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

重新装入特性旗 .

**自:** 7.0.0 (单位:千美元)

* * *

### 重设( c)

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

重置当前用户的ID和匿名ID.

**自:** 6.0.0 (单位:千美元)

* * *

### 屏幕(...)

```typescript
screen(options: ScreenOptions) => Promise<void>
```

发送屏幕事件 .

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ScreenOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-screenoptions)` |

**自:** 6.0.0 (单位:千美元)

* * *

### 设置个人财产(...)

```typescript
setPersonProperties(options: SetPersonPropertiesOptions) => Promise<void>
```

设置当前用户关联人的属性 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetPersonPropertiesOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-setpersonpropertiesoptions)` |

**自:** 8.6.0 (简体中文)

* * *

### 设置(...)

```typescript
setup(options: SetupOptions) => Promise<void>
```

以提供的选项设置 PostHog SDK .

**请注意**:在任何其他方法之前,应先使用这种方法. 或者,在Android和iOS上,您可以在 您的电容配置文件 。 在这种情况下,你决不能叫这个方法.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetupOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-setupoptions)` |

**自:** 6.0.0 (单位:千美元)

* * *

### 开始记录( C)

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

开始录音.

**自:** 7.3.0 (单位:千美元)

* * *

### 停止记录( )

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

停止录音.

**自:** 7.3.0 (单位:千美元)

* * *

### 未注册(...)

```typescript
unregister(options: UnregisterOptions) => Promise<void>
```

删除一个超级属性 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[UnregisterOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-unregisteroptions)` |

**自:** 6.0.0 (单位:千美元)

* * *

### 接口

#### 非选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`alias`** | `string` | 指定给当前用户的新的单独ID . | 6.0.0 (单位:千美元) |

#### 抓取选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`event`** | `string` | 取取之事名. | 6.0.0 (单位:千美元) |
| **`properties`** | `Record<string, any>` | 随事件一起发送的属性 . | 6.0.0 (单位:千美元) |

#### 捕获例外选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`message`** | `string` | 特例之谕. |  | 8.5.0 (中文(简体) ) |
| **`name`** | `string` | 名之为例外. 用作分组的例外类型. | `'Error'` | 8.5.0 (中文(简体) ) |
| **`stacktrace`** | `StackFrame[]` | 例外的堆积痕迹 可以从 `Error` 使用 [`stacktrace.js`](https://www.stacktracejs.com/)。 。 。 . |  | 8.5.0 (中文(简体) ) |
| **`properties`** | `Record<string, any>` | 除外发送的属性 . |  | 8.5.0 (中文(简体) ) |

#### 堆叠外观

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`functionName`** | `string` | 函数的名称 . | 8.5.0 (中文(简体) ) |
| **`fileName`** | `string` | 文件名称. | 8.5.0 (中文(简体) ) |
| **`lineNumber`** | `number` | 文件内的行号 . | 8.5.0 (中文(简体) ) |
| **`columnNumber`** | `number` | 文件内的列号 . | 8.5.0 (中文(简体) ) |

#### 获取 DistinctId 结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`distinctId`** | `string` | 当前的识别码 . | 8.2.0 (中文(简体) ) |

#### 获取FeatureFlagResult 标签

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`value`** | `string | boolean | null` | 地物旗的价值. 如果特性旗不存在,则值将是 `null`。 。 。 . | 7.0.0 (单位:千美元) |

#### 获取 FeatureFlag 选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`key`** | `string` | 地物旗的钥匙. | 7.0.0 (单位:千美元) |

#### 获取FeatureFlagPayload 最终结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`value`** | `[JsonType](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-jsontype)` | 地物旗载荷的价值. | 7.1.0 (中文(简体) ) |

#### 获取 FeatureFlagPayload 选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`key`** | `string` | 地物旗的钥匙. | 7.1.0 (中文(简体) ) |

#### 获取会议结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`sessionId`** | `string | null` | 当前会话编号 。 如果没有会话活动,则值为 `null`。 。 。 . | 8.6.0 (简体中文) |

#### 组合选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `string` | 组型. | 6.0.0 (单位:千美元) |
| **`key`** | `string` | 组合键. | 6.0.0 (单位:千美元) |
| **`groupProperties`** | `Record<string, any>` | 组事件发送的属性 . | 6.0.0 (单位:千美元) |

#### 识别选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`distinctId`** | `string` | 用户的明显身份. | 6.0.0 (单位:千美元) |
| **`userProperties`** | `Record<string, any>` | 要设定的人属性 . | 6.0.0 (单位:千美元) |

#### 能够实现的结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`enabled`** | `boolean` | 是否启用特性旗 。 如果特性旗不存在,则值将是 `false`。 。 。 . | 7.0.0 (单位:千美元) |

#### 是否允许选择

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`key`** | `string` | 地物旗的钥匙. | 7.0.0 (单位:千美元) |

#### 异地输出结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`optedOut`** | `boolean` | 用户是否选择退出抓取 . | 8.1.0 联合国 |

#### 注册选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`key`** | `string` | 超级地产名称. | 6.0.0 (单位:千美元) |
| **`value`** | `any` | 超级财产的价值. | 6.0.0 (单位:千美元) |

#### 屏幕选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`screenTitle`** | `string` | 取出屏名来. | 6.0.0 (单位:千美元) |
| **`properties`** | `Record<string, any>` | 与屏幕事件一起发送的属性 . | 6.0.0 (单位:千美元) |

#### 设置个人财产选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`properties`** | `Record<string, any>` | 要设定的人属性 . | 8.6.0 (简体中文) |
| **`setOnceProperties`** | `Record<string, any>` | 个人属性只设置一次 。 现有值将不会被覆盖 . | 8.6.0 (简体中文) |

#### 设置选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`apiKey`** | `string` | 您 PostHog 项目的 API 密钥 . |  | 6.0.0 (单位:千美元) |
| **`apiHost`** | `string` | 您 PostHog 实例或反向代理的 API 主机 。 如果两者兼有 `apiHost` 财务报告和审定财务报表 `host` 提供, `apiHost` 以优先为准. | `'https://us.i.posthog.com'` | 8.3.0 (单位:千美元) |
| **`host`** | `string` | 您 PostHog 实例的 API 主持人 。 折旧的别名 `apiHost`。 。 。 . | `'https://us.i.posthog.com'` | 6.0.0 (单位:千美元) |
| **`uiHost`** | `string` | PostHog UI 主机使用时 `apiHost` 指向反向代理。 仅在Web上提供. |  | 8.3.0 (单位:千美元) |
| **`cookielessMode`** | `'always' | 'on_reject'` | 无饼干追踪模式 `'always'`: 总是用无饼干跟踪服务器侧匿名散列。 - `'on_reject'`: 正常跟踪直到 `optOut()` 叫做,然后切换到无饼干。 仅在Web上提供. 在 PostHog 项目设置中需要启用无饼干模式 . |  | 8.1.0 联合国 |
| **`enableSessionReplay`** | `boolean` | 是否自动启用会话记录 . | `false` | 7.3.0 (单位:千美元) |
| **`optOut`** | `boolean` | 是否默认选择退出抓取 。 用户必须呼叫 `optIn()` 能够捕捉. | `false` | 8.1.0 联合国 |
| **`sessionReplayConfig`** | `[SessionReplayOptions](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-sessionreplayoptions)` | 会话重放配置选项 . |  | 7.3.0 (单位:千美元) |
| **`captureApplicationLifecycleEvents`** | `boolean` | 是否抓取应用程序生命周期事件 。 只有iOS和Android可以使用. | `true` | 8.3.0 (单位:千美元) |
| **`autoCaptureExceptions`** | `boolean` | 是否自动抓取未处理的例外 . | `false` | 8.5.0 (中文(简体) ) |
| **`preloadFeatureFlags`** | `boolean` | 启动时是否要预装特征标记 。 仅在Android和iOS上提供. | `true` | 8.6.0 (简体中文) |
| **`surveys`** | `boolean` | 是否允许调查 。 仅在iOS和Web上提供. | `true` | 8.6.0 (简体中文) |
| **`webConfig`** | `Record<string, any>` | 额外 [后hog-js 配置选项](https://posthog.com/docs/libraries/js/config) 合并到向 `posthog.init`。在此设定的选项优先于其他设置选项。 仅在Web上提供. |  | 8.6.0 (简体中文) |

#### 会话重放选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`screenshotMode`** | `boolean` | 启用会话录音的截图模式 。 警告:这可能捕捉到敏感信息. | `false` | 7.3.0 (单位:千美元) |
| **`maskAllTextInputs`** | `boolean` | 在会话录音中覆盖全部文本输入字段 . | `true` | 7.3.0 (单位:千美元) |
| **`maskAllImages`** | `boolean` | 在会话录音中覆盖所有图像 . | `true` | 7.3.0 (单位:千美元) |
| **`maskAllSandboxedViews`** | `boolean` | 遮盖所有沙盒系统视图(iOS特有). | `true` | 7.3.0 (单位:千美元) |
| **`captureNetworkTelemetry`** | `boolean` | 在会话录音中采集网络遥测. | `false` | 7.3.0 (单位:千美元) |
| **`debouncerDelay`** | `number` | 取消会话记录快照的延迟( 以秒计) . | `1.0` | 7.3.0 (单位:千美元) |

#### 未注册选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`key`** | `string` | 要删除的超级属性名称 . | 6.0.0 (单位:千美元) |

### 类型异名

#### JsonType (英语)

`string | number | boolean | null | { [key: string]: [JsonType](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-jsontype); } | JsonType[]`

## 高级

### 反向代理服务器

对于 PostHog 管理倒置代理, 设置 `apiHost` 转到您的代理 URL并 `uiHost` 到您的 PostHog 应用程序主机( S)`https://us.posthog.com` 或者说 `https://eu.posthog.com`) (中文(简体) ). `host` 仍作为折旧的别名支持 `apiHost`。 。 。 . `uiHost` 仅在网上提供.

## 财务问题

### 我一定要打电话给 `setup` 使用插件前的方法 ?

是的,那个 `setup(...)` 方法应在任何其他方法之前调用。 或者,在Android和iOS上,您可以在 Capacitor 配置文件中配置插件(参见 [配置](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-configuration)) (中文(简体) ). 那样的话,你就不能叫 `setup(...)` 方法.

### 二者有何区别 `apiHost` 财务报告和审定财务报表 `host` 选项?

这个 `host` 选项是用于 `apiHost`。两者都指向您 PostHog 实例的 API 主机或反向代理机。 如果提供了两种选择, `apiHost` 优先,所以新项目只应使用 `apiHost`。 。 。 .

### 我如何使用带有反向代理的插件?

设定 `apiHost` 选项 `uiHost` 选项到您的 PostHog 应用程序主机, 例如 `https://us.posthog.com` 或者说 `https://eu.posthog.com`。注意: `uiHost` 仅在网上提供。 见 [反向代理服务器](https://npmcn.com/package/%40capawesome/capacitor-posthog/#readme-reverse-proxy) 详细情况.

### 我该如何重新播放会话?

设定 `enableSessionReplay` 选项到 `true` 输入 `setup(...)` 方法或控制器配置文件中,并用 `sessionReplayConfig` 选项。 您也可以开始并停止手动录制 `startSessionRecording()` 财务报告和审定财务报表 `stopSessionRecording()` 方法。 。 .

### 用户如何选择不跟踪?

打电话 `optOut()` 停止事件捕获的方法和 `optIn()` 重新启用的方法。 您可以检查当前状态 `isOptOut()` 或默认选择用户退出 `optOut` 设置选项。 在网络上与 `cookielessMode: 'on_reject'`,选择退出开关进行无饼干匿名跟踪,而不是完全停止捕获.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [分析](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Firebase Analytics 的非官方电容插件.
-   [冰冻](https://capawesome.io/docs/sdks/capacitor/crisp/): Crisp直播和客户支持平台的非官方Capacitor插件.
-   [窗体砖](https://capawesome.io/docs/sdks/capacitor/formbricks/):非官方的Capacitor插件,用于Formbricks运行应用中调查.
-   [格拉法纳·法罗](https://capawesome.io/docs/sdks/capacitor/grafana-faro/): Grafana 的非官方电容插件 法罗监视你的应用.
-   [TikTok 应用事件](https://capawesome.io/docs/sdks/capacitor/tiktok-app-events/): TikTok App Events SDK 的非官方 Capacitor 插件.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/posthog/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/posthog/LICENSE)。 。 。 .

\[^1\]: 本项目不附属于PostHog公司或其任何子公司或子公司,不由它们认可、赞助或批准.

## 常见问题

### @capawesome/capacitor-posthog 是什么？

Android,iOS,和Web上的PostHog SDK的非官方Capacitor插件\.

### 如何安装 @capawesome/capacitor-posthog？

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

### @capawesome/capacitor-posthog 支持 TypeScript 吗？

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

### @capawesome/capacitor-posthog 支持 ESM 还是 CommonJS？

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

### @capawesome/capacitor-posthog 可以商用吗？

@capawesome/capacitor-posthog 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capawesome/capacitor-posthog 的下载量有多少？

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

### @capawesome/capacitor-posthog 还在维护吗？

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