# @appsflyer-sdk/js-core-plugin 中文文档

规范地址：https://npmcn.com/package/%40appsflyer-sdk/js-core-plugin/

版本：7\.1\.0
npm 元数据更新时间：2026-09-08T10:28:29.325Z
中文译文更新时间：2026-11-06T12:28:02.323Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40appsflyer-sdk/js-core-plugin
原文对照：https://npmcn.com/package/%40appsflyer-sdk/js-core-plugin/?lang=original

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

- 包体积（解压后）：80.6 kB，16 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-08-10T09:38:01.992Z
- 最新版本发布：2026-09-08T10:28:29.124Z
- 近 30 天下载量：374218（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

AppsFlyer SDK 7插件(Capactor, React Industrial, Cordova)共享JS/TS RPC客户端核心

## 安装

```sh
npm install @appsflyer-sdk/js-core-plugin
```

也可以使用：`pnpm add @appsflyer-sdk/js-core-plugin`、`yarn add @appsflyer-sdk/js-core-plugin`、`bun add @appsflyer-sdk/js-core-plugin`

## README

# @ appsflyer/ plugin- core

AppsFlyer SDK 7插件(Capacitor, React Industrial, Cordova)共享JS/TS RPC客户端核心.

见 `AppsFlyerSDK` (以 `RpcTransport` 执行),面向公众的API, 财务报告和审定财务报表 `RpcTransport` 内 `src/types.ts` 用于连接每个框架的插件 repo 工具.

每个 `AppsFlyerSDK` 方法取自直接输入的单个参数对象 `src/generated/methods.ts` (例如:. `logEvent(params: LogEventParams)`),生成于 `schema/appsflyer-plugins-rpc-schema.json` ——该方法的线载荷始终是准确的 那个计划 `publicApi.parameters` 形状,之间没有手写重塑.

此软件包没有本地代码, 也没有框架依赖性 需要每个消耗插件( Capacitor, Cordova, React Introduct, 本地脚本, Cocos Creator) 到 拥有自己的iOS(斯维夫特)和Android(科特林)本土RPC执行. 这个包是 共享 JS 边合同层:它解决了公共API对每个平台正确电线的呼叫 方法/参数(`resolveRpc()`被计划驱动 `rpc.android`编号 :`rpc.ios`编号 :`mappings` 块, 但每个消耗的插件 仍然拥有,船, 并维持自己的本土代码 实际上 收到RPC的电话 和本地的AppsFlyer SDK。 在这个单簧管内部, `nativescript` 财务报告和审定财务报表 `cocos-creator` 已经直接依赖它( e)`"@appsflyer/plugin-core": "file:../core"`)和再出口其类型/装置. `capacitor`, (中文(简体) ), `cordova`,以及 `react-native` 宣布依赖 `@appsflyer/plugin-core` 也一样,但是在传承的道路上 (单位:千美元)`file:../../appsflyer-js-plugin-core`) 各自独立后留下的——即 路径不能解决这个软件包, 或存在在这个单列波的任何地方, 所以这三个不是 电线已经接通了 将它们移入此包是 2+ 阶段 共享图书馆迁移(见 `capacitor-appsflyer-plugin-rpc`是因为 `docs/hld/2026-08-01-shared-js-rpc-plugin-library-hld.md`) (中文(简体) ).

## 已准备好会话顺序

`init() → registerSessionReadyListener() → start()` 是有文件记载的公约,不是什么 `AppsFlyerSDK` 机械执行。 通话 `start()` 在会话准备回话之前 发射不会扔,也不会排队 稍后的呼叫,它发送 `start` RPC呼吁 与其它方法一样 呼叫者的责任是等待 `onReady` 转回呼叫 `registerSessionReadyListener()` 打电话前 `start()`,每个SDK 7's 手动启动模型.

## 正确执行新运输

遵循这些步骤, 将新框架( 或固定现有框架) 线接到此套件上 :

1.  **执行 `RpcTransport`** (单位:千美元)`src/types.ts`)——这个包件的唯一接合要求:
    -   `call<T>(method, params)`: 前进 `method` 财务报告和审定财务报表 `params` 回到原生桥,没有重塑,没有包装,也没有钥匙重命名。 以本地回应解决,或以正常方式拒绝 `new AppsFlyerError(code, message)`。 。 。 .
    -   `subscribe(listener)`: 连接您的本土桥的持续事件频道并引用 `listener({ event, data, ... })` 每一个本地活动推。 还原 a `ListenerHandle` 谁 `remove()` 撕掉订阅.
2.  **构造一个 `AppsFlyerSDK` 实例**数字 : `new AppsFlyerSDK(new YourTransport(), { plugin: '<your-framework>', pluginVersion: '<your-package-version>' })`。这个身份通过 AppsFlyer 的属性后端报告 `setPluginInfo` ——必须是您框架本身的名称/版本,从不插件-core's.
3.  **只使用生成参数类型的调用方法 .** 每种方法都使用精确的参数对象 `<Method>Params` 内 `src/generated/methods.ts` (从包根再出). 导入生成的类型并将其作为-is使用——永远不要手写你自己的选项接口,也永远不要从更古老的API版本,内存,或另一个框架的插件来猜测形状. 如果这个计划改变一个方法的形状,生成的类型随它而变化;这就是形状的唯一活地.
4.  **在联合来文/技术服务中不要增加每个平台的特殊分类.** Android/iOS之间的密钥重命名编码于 `schema/appsflyer-plugins-rpc-schema.json`按方法计 `rpc.android`编号 :`rpc.ios`编号 :`mappings` 由原生桥本身处理。 如果你要写 JS shim 在打电话前将一个形状翻译成另一个形状 `transport.call()`,站住——逻辑属于原生代码,或者计划需要更新.
5.  **尊重启动命令**: 调用 `init(...)`,则 `registerSessionReadyListener(onReady)`,然后调用 `start()` 只有从内部 `onReady`这是公约,不是什么 `AppsFlyerSDK` 强制执行 -- `start()` 叫做"早起" 而不是扔地或排队.
6.  **按下正确的事件名称** 结束 `subscribe()`'收听器,匹配每种方法' `publicApi.events` 在计划: `onSessionReady`, (中文(简体) ), `onConversionDataSuccess`, (中文(简体) ), `onConversionDataFail`, (中文(简体) ), `onDeepLinkReceived`并推进遗产 `onDeepLinking` 如果原生的一方发出它,则以防御方式命名——不是每个原生的桥梁都变成一个名称.
7.  **调用前先核实**:如果你碰了这个计划,就跑 `npm run generate:types`; 那样 `npm run typecheck` 财务报告和审定财务报表 `npm test` 内 `packages/core`。如果你是一个消耗性软件包,则重建插件核心 `dist/` (单位:千美元)`npm run build`),并重打自已的套件对照它——一个被打乱的 `dist/` 将隐藏断裂 看起来像一个通行证.

## 对于人工智能特工

执行新运输或修改新运输的任何编码代理人的规则 `AppsFlyerSDK` 方案改变后:

**合同**

-   `RpcTransport.call<T>(method, params)` 逐字向原生桥推进; `RpcTransport.subscribe(listener)` 连接持续事件通道并返回 a `ListenerHandle`。 。 。 .
-   `AppsFlyerSDK` 以运输方式建造,并且 `PluginIdentity` (单位:千美元)`{ plugin, pluginVersion }`)——这必须是消耗性框架本身的特性,绝不是 `js-plugin-core`/plugin-core自己的包名或版本.

**帕拉姆斯——阅读,不要猜测**

-   每个方法的参数类型是生成的 `<Method>Params` 接口 `src/generated/methods.ts`从软件包根导出。 直接导入并使用.
-   从不手写参数/选项接口。 永远不要从这个SDK的更古老版本中推断出一个方法的形状,另一个 AppsFlyer 插件的命名惯例,或者前一个会话的内存——读 `src/generated/methods.ts` 或者说 `schema/appsflyer-plugins-rpc-schema.json` 直接,每次.
-   如果计划改变,生成的类型随它而改变. 重新生成( E)`npm run generate:types`在写出与之相反的代码之前.

**联合来文中没有重塑**

-   平面相差(双键、嵌入式对平面形状、更名的字段)生活在图案中 `rpc.android`编号 :`rpc.ios`编号 :`mappings` 每一个方法的块,是本土桥梁的责任,而不是这个包或消耗性框架的JS层.
-   撰写JS/TS shim,在呼叫前将一个参数形状翻译为另一个参数形状 `transport.call()` 是您解错层的信号——停止并修补原生桥或图案需要更新的旗帜.

**启动和活动**

-   顺序 : `init()` → `registerSessionReadyListener(onReady)` → `start()` 仅在内部调用 `onReady`。这是一个公约 `AppsFlyerSDK` 不执行; 调用 `start()` 早点起火.
-   所需的事件名称被推过 `subscribe()`数字 : `onSessionReady`, (中文(简体) ), `onConversionDataSuccess`, (中文(简体) ), `onConversionDataFail`, (中文(简体) ), `onDeepLinkReceived` - 加上遗产 `onDeepLinking` 名字是防御性的,因为并不是每个本土的桥梁都统一为一个名字.
-   规范每个本地侧出错 `new AppsFlyerError(code, message)` 拒绝之前 `call()` 答应.

**在宣布事情发生之前**

-   司马变了 `npm run generate:types`。 。 。 .
-   总是 `npm run typecheck` 财务报告和审定财务报表 `npm test` 内 `packages/core`。 。 。 .
-   修改了消费包(例如:. `nativescript`, (中文(简体) ), `cocos-creator`) — 重建插件核心 `dist/` (单位:千美元)`npm run build`)首先,然后对照其输入消耗包。 烂透了 `dist/` 将隐藏真正的破碎.

## 用法实例

```ts
import { AppsFlyerSDK, RpcTransport, RpcEvent, ListenerHandle } from '@appsflyer/plugin-core';

class ExampleTransport implements RpcTransport {
  async call<T = void>(method: string, params?: Record<string, unknown>): Promise<T> {
    // Forward to your framework's native bridge (Capacitor/RN/Cordova) here.
    return undefined as T;
  }
  subscribe(listener: (event: RpcEvent) => void): ListenerHandle {
    // Wire up your framework's native event channel here.
    return { remove: () => {} };
  }
}

// Each consuming framework supplies its own identity here — this is what
// gets reported to AppsFlyer's attribution backend via setPluginInfo, so it
// must NOT be plugin-core's own name/version.
const sdk = new AppsFlyerSDK(new ExampleTransport(), {
  plugin: 'capacitor',
  pluginVersion: '1.0.0',
});

await sdk.init({ devKey: 'DEV_KEY', appId: 'APP_ID' });
await sdk.registerSessionReadyListener(async () => {
  await sdk.start();
});
```

## 发展

-   `npm run generate:types` ——再生 `src/generated/methods.ts` 从 `schema/appsflyer-plugins-rpc-schema.json`
-   `npm run generate:rpc-map` ——再生 `src/generated/rpc-map.ts` (每个平台的方法/段落) 绘图表 `resolveRpc()` (读取)来自同一计划
-   `node scripts/generate-sdk-boilerplate.js` ——修改了方案后,打印出通关 每种方法的根 `src/appsflyer-sdk.ts` 还没有包装; 用手贴上每个根 (方法与非`void` 结果或自定义的倾听者/init逻辑仍然需要手动打字). 未运行 `build` - 它只是指纹,从来没有写.
-   `npm test` - 运行杰斯特套房(所有测试都针对内幕) `FakeTransport`(没有本地代码)
-   `npm run typecheck` —— 说 `tsc --noEmit`
-   `npm run build` ——生成类型,生成 RPC 映射,然后编译到 `dist/`

见 `docs/KNOWLEDGE_BASE.md` 用于完整文件分解和流程图.

## 常见问题

### @appsflyer-sdk/js-core-plugin 是什么？

AppsFlyer SDK 7插件\(Capactor, React Industrial, Cordova\)共享JS/TS RPC客户端核心

### 如何安装 @appsflyer-sdk/js-core-plugin？

在项目目录运行 npm install @appsflyer-sdk/js-core-plugin，或使用 pnpm add / yarn add / bun add。

### @appsflyer-sdk/js-core-plugin 支持 TypeScript 吗？

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

### @appsflyer-sdk/js-core-plugin 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @appsflyer-sdk/js-core-plugin 可以商用吗？

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

### @appsflyer-sdk/js-core-plugin 的下载量有多少？

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

### @appsflyer-sdk/js-core-plugin 还在维护吗？

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