# @capgo/capacitor-rudderstack 中文文档

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

版本：8\.1\.17
npm 元数据更新时间：2026-10-15T03:44:20.981Z
中文译文更新时间：2026-11-09T04:08:59.485Z
软件包许可：MIT

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

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

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

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

## 中文简介

RuderStack分析、身份和事件跟踪的电容插件.

## 安装

```sh
npm install @capgo/capacitor-rudderstack
```

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

## README

# @ capgo/ 电容- rudderstack

用本地的RanderStack SDKs从您的 Capacitor app 中向 RanderStack 发送分析事件和用户身份. 一个舵手-斯德克-科尔多瓦相接口.

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

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

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

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

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

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

## 主要特点

-   **设置**数字 : `initialize()` 使用您的写键和数据平面 URL.
-   **跟踪**数字 : `track()`, (中文(简体) ), `screen()`, (中文(简体) ), `identify()`, (中文(简体) ), `group()` 财务报告和审定财务报表 `alias()`。 。 。 .
-   **身份**数字 : `reset()`, (中文(简体) ), `putAnonymousId()`, (中文(简体) ), `putAdvertisingId()` 财务报告和审定财务报表 `putDeviceToken()`。 。 。 .
-   **隐私和分娩**数字 : `optOut()` 财务报告和审定财务报表 `flush()`。 。 。 .
-   **易行移徙**:遵循 Cordova 插件 API 形状.
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-22. 使用陆克星iOS和Android SDK. Web 有不发送事件的API相容根.

RuderStack分析与事件跟踪的电容插件.

此软件包是一个 Capacitor 端口,由 [舵-斯德克-科尔多瓦](https://github.com/rudderlabs/rudder-sdk-cordova/tree/develop) 与原生的Android和iOS桥为Capacitor 8.

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/rudderstack/ 页面存档备份,存于互联网档案馆](https://capgo.app/docs/plugins/rudderstack/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的电容安装的版本 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 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-rudderstack` plugin in my project.
```

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

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

## 使用量

```ts
import { RudderStack } from '@capgo/capacitor-rudderstack';

await RudderStack.initialize('YOUR_WRITE_KEY', {
  dataPlaneUrl: 'https://your-dataplane.rudderstack.com',
  trackLifecycleEvents: true,
  logLevel: RudderStack.LogLevel.INFO,
});

await RudderStack.identify('user_123', {
  email: 'user@example.com',
  plan: 'pro',
});

await RudderStack.track('Checkout Started', {
  value: 49,
  currency: 'EUR',
});
```

API有意跟随Cordova插件外形,使已存在的Ruder Cordova集成可以在最小的呼叫站点变化下迁移.

## 行为

-   Android使用RuderStack Android SDK并透过Capacitor桥将Cordova相容的分析器表面曝光.
-   iOS使用RanderStack iOS SDK并配有与同为公共API相匹配的斯威夫特桥.
-   Web是一个轻量级相容执行,旨在开发与API对等. 它不会将事件发送到RuderStack.
-   `config.factories` 来自 Cordova 插件目前被忽略 。 本土目的地工厂配套插件不属于这个第一个Capacitor端口.

## API 密码

-   [`initialize(...)`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-initialize)
-   [`identify(...)`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-identify)
-   [`group(...)`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-group)
-   [`track(...)`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-track)
-   [`screen(...)`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-screen)
-   [`alias(...)`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-alias)
-   [`reset()`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-reset)
-   [`flush()`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-flush)
-   [`putDeviceToken(...)`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-putdevicetoken)
-   [`setAdvertisingId(...)`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-setadvertisingid)
-   [`putAdvertisingId(...)`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-putadvertisingid)
-   [`setAnonymousId(...)`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-setanonymousid)
-   [`putAnonymousId(...)`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-putanonymousid)
-   [`optOut(...)`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-optout)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-type-aliases)

反映公共表面的 API `rudder-sdk-cordova`。 。 。 .

### 初始化(...)

```typescript
initialize(writeKey: string, config?: RudderConfiguration | RudderOptions | undefined, options?: RudderOptions | undefined) => Promise<void>
```

初始化RuderStack客户端.

方法保存 Cordova 签名,因此第二个参数可以是配置对象或 a 舵手选项对象.

| 参数 | 类型 |
| --- | --- |
| **`writeKey`** | `string` |
| **`config`** | `[RudderConfiguration](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderconfiguration) | [RudderOptions](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderoptions)` |
| **`options`** | `[RudderOptions](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderoptions)` |

* * *

### 标识(...)

```typescript
identify(userId: string, traits?: RudderOptions | RudderTraits | undefined, options?: RudderOptions | undefined) => Promise<void>
```

为所提供的用户 ID 发送一个识别呼叫 .

| 参数 | 类型 |
| --- | --- |
| **`userId`** | `string` |
| **`traits`** | `[RudderOptions](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderoptions) | [RudderTraits](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-ruddertraits)` |
| **`options`** | `[RudderOptions](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderoptions)` |

* * *

### 组(...)

```typescript
group(groupId: string, groupTraits?: RudderOptions | RudderTraits | undefined, options?: RudderOptions | undefined) => Promise<void>
```

发送组呼叫以获取提供的组 ID .

| 参数 | 类型 |
| --- | --- |
| **`groupId`** | `string` |
| **`groupTraits`** | `[RudderOptions](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderoptions) | [RudderTraits](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-ruddertraits)` |
| **`options`** | `[RudderOptions](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderoptions)` |

* * *

### 音轨(...)

```typescript
track(eventName: string, properties?: RudderOptions | RudderProperties | undefined, options?: RudderOptions | undefined) => Promise<void>
```

为提供的事件名称发送音轨呼叫 .

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `string` |
| **`properties`** | `[RudderOptions](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderoptions) | [RudderProperties](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderproperties)` |
| **`options`** | `[RudderOptions](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderoptions)` |

* * *

### 屏幕(...)

```typescript
screen(screenName: string, properties?: RudderOptions | RudderProperties | undefined, options?: RudderOptions | undefined) => Promise<void>
```

为提供的屏幕名称发送屏幕呼叫.

| 参数 | 类型 |
| --- | --- |
| **`screenName`** | `string` |
| **`properties`** | `[RudderOptions](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderoptions) | [RudderProperties](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderproperties)` |
| **`options`** | `[RudderOptions](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderoptions)` |

* * *

### 别名(...)

```typescript
alias(newId: string, options?: RudderOptions | undefined) => Promise<void>
```

区分当前用户为新标识符.

| 参数 | 类型 |
| --- | --- |
| **`newId`** | `string` |
| **`options`** | `[RudderOptions](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderoptions)` |

* * *

### 重设( c)

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

重置当前 RanderStack 身份状态 .

* * *

### 冲号( )

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

Flushes立即排队活动.

* * *

### 将DeviceToken(...)放入

```typescript
putDeviceToken(deviceToken: string) => Promise<void>
```

设置将 RudderStack 转发到支持的目的地的推动符 .

| 参数 | 类型 |
| --- | --- |
| **`deviceToken`** | `string` |

* * *

### 设置 :

```typescript
setAdvertisingId(advertisingId: string) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`advertisingId`** | `string` |

* * *

### 置入广告ID(...)

```typescript
putAdvertisingId(advertisingId: string) => Promise<void>
```

设置自定义广告 id 值.

| 参数 | 类型 |
| --- | --- |
| **`advertisingId`** | `string` |

* * *

### 设置匿名文件(...)

```typescript
setAnonymousId(anonymousId: string) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`anonymousId`** | `string` |

* * *

### 设置匿名标识(...)

```typescript
putAnonymousId(anonymousId: string) => Promise<void>
```

设置自定义匿名的 id 值.

| 参数 | 类型 |
| --- | --- |
| **`anonymousId`** | `string` |

* * *

### 选择退出(...)

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

切换 RuderStack 跟踪选择退出 .

| 参数 | 类型 |
| --- | --- |
| **`optOut`** | `boolean` |

* * *

### 获取 PluginVersion ()

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

从本地执行中返回插件版本标记 .

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

* * *

### 接口

#### 舵手配置

支持基本的 RanderStack 本地 SDKs 的配置密钥 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`dataPlaneUrl`** | `string` | 陆克文Stack数据平面 URL. |
| **`flushQueueSize`** | `number` | 冲洗前要批量的事件数 . |
| **`dbCountThreshold`** | `number` | 数据库行阈值会触发Android和iOS上出轨. |
| **`configRefreshInterval`** | `number` | 服务器配置按小时刷新间隔 . |
| **`logLevel`** | `[RudderLogLevelValue](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-rudderloglevelvalue)` | (原始内容存档于2018-10-21). RanderStack log verbosity. |
| **`sleepTimeOut`** | `number` | 睡眠超时 / 睡眠计数由本地SDK使用. |
| **`autoCollectAdvertId`** | `boolean` | 仅限Android. 让本地SDK自动收集广告标识符. |
| **`trackLifecycleEvents`** | `boolean` | 音轨 `Application Installed`, (中文(简体) ), `Application Updated`,以及 `Application Opened` 自动. |
| **`controlPlaneUrl`** | `string` | 舵手Stack控制平面 URL. |
| **`recordScreenViews`** | `boolean` | 启用本地 SDK 支持的自动屏幕跟踪 . |
| **`factories`** | `any[]` | 在此 Capacitor 端口被忽略 。 Cordova SDK利用这个领域从伴生插件中将本土目的地工厂拖出靴子. 这些扩展包没有在首次Capacitor发行中执行. |

#### 左轮选项

(原始内容存档于2018-10-21) (英语). RanderStack per-call options.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`externalIds`** | `[Record](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-record)<string, string>` | 与事件一起传送的外部标识符 . |
| **`integrations`** | `[Record](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-record)<string, boolean>` | 按集成名称键入目标启用标记 . |

#### 插件变压器

插件版本有效载荷 .

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

### 类型异名

#### 舵手Loglevel Value 软件

RanderStack 为迁移方便而暴露的日志值 .

`0 | 1 | 2 | 3 | 4 | 5`

#### 记录

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

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

#### 舵手拖车

被接受的特质有效载荷 `identify` 财务报告和审定财务报表 `group`。 。 。 .

`[Record](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-record)<string, any>`

#### 舵子产品

被接受的属性有效载荷 `track` 财务报告和审定财务报表 `screen`。 。 。 .

`[Record](https://npmcn.com/package/%40capgo/capacitor-rudderstack/#readme-record)<string, any>`

## 常见问题

### @capgo/capacitor-rudderstack 是什么？

RuderStack分析、身份和事件跟踪的电容插件\.

### 如何安装 @capgo/capacitor-rudderstack？

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

### @capgo/capacitor-rudderstack 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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