@cg-devcenter/rtc-fpnn-webjs-sdk 1.0.0-cg.5 → 1.0.0-cg.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,205 @@
1
+ # 从 GitHub 上游 RTM SDK 迁移到当前 SDK
2
+
3
+ ## 对照基线与范围
4
+
5
+ 本文对照的是上游 [`highras/rtm-client-sdk-websocket`](https://github.com/highras/rtm-client-sdk-websocket),`master` 分支在 2026-10-13 检查到的 commit [`afe69746fea1444687f8999e9de05cbbb4838400`](https://github.com/highras/rtm-client-sdk-websocket/tree/afe69746fea1444687f8999e9de05cbbb4838400),不是 npm 上的 `rtm-fpnn-webjs-sdk@1.0.4`。上游 `master` 会继续变化,因此本页以该 commit 固定对照;当前仓库以实际工作区实现为新版本基线。
6
+
7
+ 上游源码的包元数据版本为 `1.0.0`。npm 已发布包可能与该 commit 不同;本文不声称 GitHub `master` 与某个 npm tarball 完全一致。如果项目使用 fork、内部构建或 npm 锁定版本,请先核对项目实际运行的源码。
8
+
9
+ 本次重新拉取 GitHub `master` 后,HEAD 仍为上述 commit。逐方法对照结果:上游有 91 个 `RTMClient` 类方法,当前有 105 个公开类方法;没有删除或改名原有方法,新增 14 个,3 个原有方法扩展了签名。此计数不包含构造器、getter、私有辅助方法或动态挂载的事件方法。
10
+
11
+ 本页讨论浏览器端 RTM SDK。服务端 SDK 的 `RTMServerClient`、`get_token`、`get_online_users`、`send_messages`、`broadcast_message` 等接口不属于这里的 `RTMClient` 迁移范围。
12
+
13
+ ## 先看结论
14
+
15
+ - 只把上游的 `RTMClient` 换成当前 SDK 的 `RTMClient` 并继续使用 FPNN,核心构造参数、登录调用、重连默认值和 FPNN Push 事件基本保持一致,通常是低成本迁移。
16
+ - 当前 SDK 新增的 `createClient()` 在浏览器支持 SharedWorker 时共享同 UID 的连接;不支持时自动退回当前页面的独立连接。支持时它会改变连接所有权和多窗口生命周期;若始终要“一页一个客户端连接”,继续使用 `RTMClient`,或设置 `sharing: false`。
17
+ - 当前 SDK 还支持 TLV v1。TLV 是显式协议迁移:Push 名称、事件字段、错误结构和支持范围与 FPNN 不完全相同,不能只替换 endpoint。
18
+
19
+ ### 从本 SDK 旧版升级时的协议默认值变化
20
+
21
+ 这项差异不是上游 `RTMClient` 的迁移差异:此前本 SDK 的 `createClient()` 和 `RTMSharedWorkerClient` 在省略协议时默认使用 TLV v1;当前版本统一改为默认 FPNN,以匹配旧 `RTMClient` 的默认协议。若旧代码只提供 `tlvEndpoint` / `tlv_endpoint`、没有写 `protocol`,升级后会因缺少 FPNN `endpoint` 而在创建客户端时抛错。请显式补上 `protocol: 'tlv-v1'`;FPNN 调用则使用 `endpoint` 或 `ssl_endpoint` 并可省略 `protocol`。不要依赖 endpoint 字段自动推断协议。
22
+
23
+ ## FPNN 接入:原有调用基本沿用
24
+
25
+ ### 首先替换包引用
26
+
27
+ | 原项目接入方式 | 迁移改动 |
28
+ | --- | --- |
29
+ | 使用 `rtm-fpnn-webjs-sdk`,或直接引用上游源码 | 替换为 `@cg-devcenter/rtc-fpnn-webjs-sdk` 的实际发布包或当前构建。ESM 使用 `import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk'`,也支持具名导入。CommonJS 使用 `require('@cg-devcenter/rtc-fpnn-webjs-sdk')`。 |
30
+ | HTML 加载旧 `dist/rtm.min.js` | 替换 SDK 文件;UMD 仍提供 `window.rtm`,业务构造和调用可以沿用。 |
31
+ | 为 SDK 加载 `fpnn`、`msgpack`、`md5`、`Int64BE` 四个全局依赖 | 当前 SDK 已打包这些依赖,单纯供 SDK 使用时不再需要分别加载。若业务代码仍直接访问这些全局变量,需继续提供它们或调整业务引用;包根不额外导出 `fpnn` 全局。 |
32
+ | 深层引用旧包的 `src/*`、`libs/*` | 改用包根的公开导出;当前 npm `files` / `exports` 不提供这些旧内部路径。 |
33
+
34
+ 例如旧代码用 `fpnn.FPConfig.ERROR_CODE.FPNN_EC_OK` 判断登录错误码,移除独立 FPNN 脚本后该全局变量不会由新 SDK 自动创建。登录时应按已有 `callback(accepted, errorCode)` 检查 `accepted`;也可以保留业务确实依赖的外部 FPNN 运行时。当前 SDK 内部仍优先使用已注入的兼容全局依赖。
35
+
36
+ 只替换包引用并继续 `new RTMClient(...)`,不会自动启用共享连接,也不要求部署 Worker 或切换 TLV。
37
+
38
+ 上游 `master` 使用 `new RTMClient(options)` 提供 `pid` 和 `endpoint` 或 `ssl_endpoint`,再用 `login(uid, token, callback, timeout)` 登录。UID 和 token 不在构造参数中;上游也没有要求业务先调用 dispatch 发现流程。当前 SDK 的 `RTMClient` 保留这套 FPNN 接入方式。
39
+
40
+ | 上游 GitHub `master` | 当前 SDK 的 FPNN `RTMClient` | 迁移说明 |
41
+ | --- | --- | --- |
42
+ | `new RTMClient({ pid, endpoint })` | 相同 | `endpoint` 仍是 FPNN Gate 的 `host[:port]`。 |
43
+ | `ssl_endpoint` | 相同 | 使用部署方提供的 SSL Gate 地址;当前 FPNN 配置要求 `host[:port]`,不要把 TLV WebSocket URL 当作 FPNN endpoint。 |
44
+ | `login(uid, token, callback, timeout)` | 相同 | token/credential 仍应由业务服务端签发。 |
45
+ | `autoReconnect` 默认 `true` | 默认 `true` | 无需为了保持上游默认值而改配置。 |
46
+ | `connectionTimeout`、`maxPingIntervalSeconds`、`attrs`、`platformImpl`、`md5`、`regressiveStrategy` | 保留 | 逐项按当前[接入指南](USAGE.md)确认配置约束。 |
47
+ | `ErrorRecorder`、`ReloginCompleted`、`SessionClosed` | 保留 | 事件名和主要用途不变;单个业务请求错误仍检查该请求的 callback/Promise。 |
48
+ | `client.processor.on(RTMConfig.SERVER_PUSH...)` | 保留 | FPNN 事件名及按消息类型拆分 Push 的行为沿用上游处理方式。 |
49
+
50
+ ```js
51
+ import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
52
+
53
+ // 保留上游的一页一个客户端连接行为
54
+ const client = new rtm.RTMClient({
55
+ protocol: 'fpnn',
56
+ pid,
57
+ endpoint: 'rtm-gate.example.com:13321',
58
+ autoReconnect: true,
59
+ });
60
+
61
+ client.processor.on(rtm.RTMConfig.SERVER_PUSH.recvChat, (message) => {
62
+ console.log('chat', message);
63
+ });
64
+
65
+ client.login(uid, credential, (accepted, errorCode) => {
66
+ if (!accepted) console.error('RTM login failed', errorCode);
67
+ }, 30_000);
68
+ ```
69
+
70
+ ### 不使用 SharedWorker 时的兼容边界
71
+
72
+ 当使用 `new RTMClient({ protocol: 'fpnn', ... })`,或使用 `createClient({ sharing: false, protocol: 'fpnn', ... })` 时,当前 SDK 为每个客户端实例创建自己的 FPNN 连接。这与上游 `RTMClient` 的连接模型一致:多个页面各自创建客户端时,仍然是多个独立连接;不会自动跨页面共享登录态或转发 Push。当前 FPNN 请求仍由 `fpnn.FPClient` 承载,常用登录、发送 API 和 `RTMConfig.SERVER_PUSH` 事件名沿用上游。
73
+
74
+ 这表示**接入模型和常见 FPNN 业务行为基本兼容,不表示实现逐行相同或所有异常时序都完全相同**。当前 SDK 在连接生命周期中增加了过期连接隔离和登录/重连竞态保护,降低旧连接回调影响新连接的风险;这些属于实现层修复,边界时序下的事件先后可能与上游不同。
75
+
76
+ 还需注意以下差异:
77
+
78
+ - 当前 FPNN `endpoint` / `ssl_endpoint` 会校验为 `host[:port]`,不接受 URL scheme、路径、查询或片段;上游示例也使用 `host:port`,但当前版本会更早、明确地拒绝格式错误的地址。上游把普通 endpoint 的端口 `13325` 规范化为 `13321`,当前版本保留该兼容处理。
79
+ - 默认 `autoReconnect: true` 与上游一致。当前版没有为了 FPNN 迁移改变这一默认值。
80
+ - `login(uid, token, callback, timeout)`、FPNN Push 名称及普通 API 参数顺序沿用上游;当前版另外提供 Promise facade 和一批新增 API,见下表。
81
+ - `getUnreadMessage` 新增可选 `withLogout`,`removeSession` 新增可选 `localOnly`,`bye` 新增可选超时和 callback。旧 JavaScript 调用形式仍可用;当前类型声明也保留旧调用重载,只有需要新语义时才传新增参数。
82
+ - `createClient()` 即使默认协议为 FPNN,也会在 SharedWorker 可用时优先共享;浏览器没有 SharedWorker API 时自动使用独立连接。需要始终独立时,应使用 `RTMClient` 或显式设置 `sharing: false`;只设置 `protocol: 'fpnn'` 不会关闭可用时的共享。
83
+
84
+ 共享模式下,当前 `createClient()` 通过 SharedWorker 按 PID、协议、UID 和 Gate 地址复用连接;首次登录的页面提供 credential,同身份的其他页面复用会话。
85
+
86
+ ```js
87
+ // 选择共享连接;省略 protocol 时当前默认 FPNN
88
+ const client = rtm.createClient({ pid, endpoint: 'rtm-gate.example.com:13321' });
89
+ await client.promises.login(uid, credential);
90
+
91
+ // 如果使用 createClient 但要保留独立连接
92
+ const independentClient = rtm.createClient({
93
+ sharing: false,
94
+ pid,
95
+ protocol: 'fpnn',
96
+ endpoint: 'rtm-gate.example.com:13321',
97
+ });
98
+ ```
99
+
100
+ 浏览器应用无需自行维护 Worker 名称或 URL。共享连接要求页面同源,并使用一致的连接配置;完整身份规则、生命周期和构建工具配置见[默认共享接入](USAGE.md#默认共享接入当前源码)。
101
+
102
+ ### 启用 SharedWorker 后真正需要调整的地方
103
+
104
+ | 接入部分 | 迁移要求 |
105
+ | --- | --- |
106
+ | 创建客户端 | 将 `new RTMClient(options)` 改成 `createClient(options)`;默认 FPNN,SharedWorker 可用时共享、不可用时自动独立连接。UID 可继续从 `login()` 参数取得。 |
107
+ | 登录 | 首次提供 credential,同 UID 的其他页面复用或加入同一次登录。共享层协调登录,认证请求由底层 SDK 执行。 |
108
+ | 业务 API、结果和事件 | FPNN 方法名、callback / Promise 结果和 Push 名称沿用底层 SDK;包括 `fileToken` 和三种文件发送。Worker 不维护业务禁用名单。 |
109
+ | 组件卸载 / 页面关闭 | 使用 `destroy()` 解绑当前页面;`bye()` / `close()` 会结束所有页面共享的 RTC 会话。不要继续用 `close()` 做单页清理。 |
110
+ | 多页配置 | 同 UID 页面需使用相同 PID、协议、Gate 和连接配置;页面需同源并支持 SharedWorker。 |
111
+ | 函数或平台对象配置 | 普通 `File` 可跨线程克隆;`md5` 函数、`platformImpl` 类实例、`webSocketFactory`、函数型 metadata 等不能直接跨线程保留执行行为。依赖这些自定义运行时的项目可继续独立模式。 |
112
+ | 构建和部署 | 普通 HTML 将 Worker 与 SDK 部署在同源同目录;Vite 注册 `/vite-plugin`;Webpack 4 注册 `/webpack4` 插件;Webpack 5 使用包根 ESM 资源解析。 |
113
+ | 会话筛选 | 默认全部 SDK 事件广播到所有页面端口。已有 `conversation` / `setConversation()` 用法继续可用,筛选只在页面适配器中执行。 |
114
+
115
+ 共享层只负责 SDK 实例、登录合并、调用/事件转发和生命周期;消息协议、文件上传、重连、ACK、去重、服务端能力和业务错误由底层 SDK 决定。SDK/Worker 升级时关闭所有旧共享页面,等待默认 5 秒回收旧 Worker 后再打开,避免新旧版本混用。
116
+
117
+ ## 上游 API 与当前 API 的变化
118
+
119
+ 大多数原有 FPNN 方法保留。下面列出确实发生的签名变化,以及新增能力;不要把这些变化与 TLV wire 字段名混为一谈。
120
+
121
+ | 上游 GitHub `master` | 当前 SDK | 影响与迁移方式 |
122
+ | --- | --- | --- |
123
+ | `getUnreadMessage(clear, timeout, callback)` | `getUnreadMessage(clear, withLogout, timeout, callback)`,兼容旧重载 | `withLogout` 用于请求登出时间;旧二参数 timeout-only 和三参数 callback 调用在 JS 与 TypeScript 中均可沿用。 |
124
+ | `removeSession(to, timeout, callback)` | `removeSession(to, localOnly, timeout, callback)`,兼容旧重载 | `localOnly` 用于选择本地/单向删除语义;旧调用继续沿用,未显式提供新布尔参数时 FPNN 请求不增加 `oneway` 字段。 |
125
+ | `bye()` | `bye(timeout, callback)` | 可选设置关闭请求超时并接收结果;无参调用仍可用。关闭后仍应按生命周期说明清理客户端。 |
126
+ | 通过外部 Promise 转换工具封装 callback | `client.promises` | 新增 SDK 自带 Promise facade;旧 callback API 仍保留。 |
127
+ | 只有 `RTMClient` 独立连接 | 新增 `createClient()` / `RTMSharedWorkerClient` | 新增同源多页面共享连接和 Push 路由;只在需要该能力时切换。 |
128
+
129
+ `getUnreadMessage` 和 `removeSession` 的新增布尔参数不是基础接入的必填项。上游调用可继续按原顺序传参;只有需要登出时间或本地删除语义时才传新增参数。`textCheck(text, timeout, callback)` 也有运行时和类型声明兼容重载。继续使用原有 callback 或外部 Bluebird Promise 转换工具时,不必改用新增的 `client.promises`;若主动改用 SDK Promise facade,省略 callback,并按当前参数顺序传入可选位,例如 `client.promises.getUnreadMessage(false, undefined, 15000)`。
130
+
131
+ ### 新增 14 个公开方法
132
+
133
+ 以下为完整 callback 签名;使用 `client.promises` 时省略末尾 callback。这些方法也由 SharedWorker 客户端代理。参数含义见[API 参数说明](USAGE.md#5-参数与返回值约定),FPNN method 与 TLV URI 对照见[协议迁移对照](PROTOCOL_MIGRATION.md)。接入指南中标为 TLV 的返回结构仅适用于 TLV,不应套用到 FPNN。
134
+
135
+ | 完整方法签名 | 用途 / 文档入口 |
136
+ | --- | --- |
137
+ | `getServerTime(timeout, callback)` | 查询服务端时间,见[时间查询](USAGE.md#初始化和生命周期-api)。 |
138
+ | `sendMessages(tos, mtype, msg, attrs, mid, timeout, callback)` | 批量发送私聊消息,见[消息发送](USAGE.md#消息发送和单条消息)。 |
139
+ | `setSessionRead(category, xid, readSeq, timeout, callback)` | 设置会话已读序号上界,见[未读与会话](USAGE.md#未读会话与-push)。 |
140
+ | `getP2PMessageByMessageId(ouid, mid, desc, num, begin, end, mtypes, timeout, callback)` | 以消息 ID 为锚点查询私聊历史,见[历史查询](USAGE.md#历史翻页与计数)。 |
141
+ | `getGroupMessageByMessageId(gid, mid, desc, num, begin, end, mtypes, timeout, callback)` | 以消息 ID 为锚点查询群历史,见[历史查询](USAGE.md#历史翻页与计数)。 |
142
+ | `getRoomMessageByMessageId(rid, mid, desc, num, begin, end, mtypes, timeout, callback)` | 以消息 ID 为锚点查询房间历史,见[历史查询](USAGE.md#历史翻页与计数)。 |
143
+ | `getBroadcastMessageByMessageId(mid, desc, num, begin, end, mtypes, timeout, callback)` | 以消息 ID 为锚点查询广播历史,见[历史查询](USAGE.md#历史翻页与计数)。 |
144
+ | `getP2PMessageCount(ouid, begin, end, mtypes, timeout, callback)` | 查询私聊消息数量,见[消息计数](USAGE.md#历史翻页与计数)。 |
145
+ | `getGroupMessageCount(gid, begin, end, mtypes, timeout, callback)` | 查询群消息数量,见[消息计数](USAGE.md#历史翻页与计数)。 |
146
+ | `getRoomMessageCount(rid, begin, end, mtypes, timeout, callback)` | 查询房间消息数量,见[消息计数](USAGE.md#历史翻页与计数)。 |
147
+ | `getBroadcastMessageCount(begin, end, mtypes, timeout, callback)` | 查询广播消息数量,见[消息计数](USAGE.md#历史翻页与计数)。 |
148
+ | `enterRooms(rids, timeout, callback)` | 批量进入房间,见[群组和房间](USAGE.md#群组和房间)。 |
149
+ | `getUserRoomsAndLastMessage(mtypes, timeout, callback)` | 查询用户房间及最近消息,见[群组和房间](USAGE.md#群组和房间)。 |
150
+ | `setRoomProfile(rid, publicData, privateData, label, avatar, timeout, callback)` | 设置房间公共/私有资料、名称和头像,见[群组和房间](USAGE.md#群组和房间)。原 `setRoomInfo` 保留。 |
151
+
152
+ 这 14 项是 `RTMClient` 新增业务方法的统计;`client.promises`、`createClient()` 和 SharedWorker 客户端属于额外的接入能力,不包含在这 14 项中。
153
+
154
+ ### 上游类型声明与源码不一致的地方
155
+
156
+ 以下差异需要按项目实际调用核对;它们不是 JS 方法改名。上游源码与其 `dist/rtm.d.ts` 已有不一致,当前声明更贴近实际源码参数:
157
+
158
+ | API | 上游声明 / 文档 | 上游源码与当前推荐调用 |
159
+ | --- | --- | --- |
160
+ | `getMessage` / `deleteMessage` / `getChat` / `deleteChat` | 上游 `.d.ts` 缺少首个 `from` 参数 | `method(from, mid, xid, type, timeout, callback)`。若 TypeScript 项目按旧声明只传五个参数,需要补发送者 ID;上游 JS 源码本来就要求这个参数。 |
161
+ | `imageCheck` | 声明和文档省略 `strategyId` | `imageCheck(image, type, undefined, timeout, callback)`,有策略时替换 `undefined`。 |
162
+ | `audioCheck` | 声明和文档省略 `strategyId` | `audioCheck(audio, type, lang, codec, srate, undefined, timeout, callback)`。 |
163
+ | `videoCheck` | 声明和文档省略 `strategyId` | `videoCheck(video, type, videoName, undefined, timeout, callback)`。 |
164
+ | `removeSession` 与五种 `get*ConversationList` | 存在于上游 JS,缺失于上游 `.d.ts` | 当前补充了这些声明;这些会话查询不是本次新增的 JS 能力。 |
165
+
166
+ 当前构造配置也有实际类型约束,例如 `pid` 是 number、FPNN endpoint 是 string,使用 TypeScript 的项目应按照真实业务值修正此前被 `any` 隐藏的配置问题。
167
+
168
+ ### 已修复的旧实现行为
169
+
170
+ 上游 `getChat` 错误地递归调用自身,`deleteChat` 向 `deleteMessage` 多传了一个 `this`。当前实现分别正确委托 `getMessage` / `deleteMessage`;方法名和源码签名保留,依赖旧行为的自定义补丁应重新核对。这属于旧实现修复,不能视为逐行行为完全不变。
171
+
172
+ 连接生命周期另外修复了旧连接回调污染新连接、重复重连定时器和 processor 定时器回收问题。FPNN 基础库本体只修改了 UMD 全局对象选择以支持 Worker,MessagePack、MD5、Int64 库与上游文件相同。
173
+
174
+ 当前 SDK 仍保留上游的 `dataGet`、`dataSet`、`dataDelete`、`getGroupMembers(gid, online, timeout, callback)`、历史查询 `mtypes` 参数和 `translate(..., type, profanity, timeout, callback)` 等签名;这些不是迁移差异。也不要将 processor 的 `kickout` Push 事件误认为客户端主动踢人 API。
175
+
176
+ ## 选择 TLV v1 是另一项迁移
177
+
178
+ 继续使用 FPNN 时不需要更换消息事件名称。改用 TLV v1 时,创建客户端需显式设置 `protocol: 'tlv-v1'` 并提供部署方给出的完整 WebSocket URL。TLV Push 使用 `event.direct`、`event.group`、`event.room`、`event.broadcast` 等名称,字段结构也不同;应使用 `RTMConfig.TLV_SERVER_PUSH` 常量和对应契约处理。
179
+
180
+ TLV v1 仅支持[支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵)中标出的 API。未支持的 FPNN API 不会自动回退到 FPNN。FPNN 与 TLV 的业务 API、wire method、URI 和字段对照见[协议迁移对照](PROTOCOL_MIGRATION.md)及[TLV 契约](TLV_CONTRACT.md)。
181
+
182
+ ## 迁移成本判断
183
+
184
+ | 迁移目标 | 预计改动 | 主要检查项 |
185
+ | --- | --- | --- |
186
+ | 上游 `RTMClient` → 当前 `RTMClient`,继续 FPNN | 低 | 包导入、构建方式、credential、Gate 配置;原登录和常用消息代码大多可沿用。 |
187
+ | 改用 `createClient()` 以共享多窗口连接 | 低到中 | 同 UID 页面连接配置一致;处理共享会话生命周期;验证不同窗口收到各自需要的 Push。 |
188
+ | 从 FPNN 切换到 TLV v1 | 中到高 | Push 名称和字段、错误结构、服务端 URI 支持范围、历史和未读行为及文件等不支持 API。 |
189
+
190
+ ## 发布前检查
191
+
192
+ 本次静态审计覆盖公开方法名、签名、FPNN Push 常量和基础库差异;审计时还对 85 个原有方法按历史参数构造模拟请求,比较 FPNN method、payload、timeout 和模拟空应答的 callback 结果。该 85 项回放是一次性审计记录,不由当前回归套件逐项重放。保留的 `test/migration-compatibility.js` 针对新增布尔参数的旧 timeout/callback 调用、显式空参数位、Promise facade,以及 `textCheck` 策略参数进行回归;包类型用例检查旧调用重载。审计发现并修复 `getUnreadMessage(clear, timeout)`、`removeSession(to, timeout)` 省略 callback 时丢失 timeout,以及 `textCheck(text, numericStrategyId, undefined, callback)` 将策略误当 timeout 的问题。`textCheck` 短 timeout 重载和 SDK Promise 简写仍可用,显式四参策略调用按上游源码保留字段。这些检查不替代真实 Gate 验证;文件方法的上游对照回放只覆盖 token 阶段,完整共享上传链路由本地模拟套件覆盖。
193
+
194
+ - 确认正在对照的是上述 GitHub commit,还是业务项目实际锁定的 npm 包、fork 或内部构建。
195
+ - 继续 FPNN 时,先用当前 `RTMClient` 做最小登录、Push、发送和重连验证;不要把 TLV WebSocket URL 填入 FPNN `endpoint`。
196
+ - 若切换到 `createClient()`,明确接受默认共享连接行为;若不需要共享,使用 `RTMClient` 或 `sharing: false`。
197
+ - 搜索项目中 `getUnreadMessage`、`removeSession`、`bye` 的调用,确认新增参数只在业务需要时启用。
198
+ - 切换 TLV v1 时,按支持矩阵逐项检查 API、Push 结构、错误与服务端权限。
199
+
200
+ ## 相关文档
201
+
202
+ - [FPNN 与 TLV v1 协议迁移对照](PROTOCOL_MIGRATION.md)
203
+ - [当前 SDK 接入指南](USAGE.md)
204
+ - [Push 事件说明](EventProcess.md)
205
+ - [当前 SDK 能力总览](CAPABILITIES.md)
package/docs/Rooms.md ADDED
@@ -0,0 +1,67 @@
1
+ # RTM Client Websocket SDK Room API Docs
2
+
3
+ ## Index
4
+
5
+ [TOC]
6
+
7
+ ## Apis
8
+
9
+ **协议范围:** 本页记录 FPNN 兼容 API 的参数和事件名称;列出的方法不一定都能通过 TLV v1 调用。请先核对 [TLV v1 支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵);两协议的 method、URI 和 Push 对照见[协议迁移说明](PROTOCOL_MIGRATION.md)。
10
+
11
+ * `enterRoom(rid, timeout, callback)`: 进入房间
12
+ * `rid`: **(Required | Int64)** 房间 id
13
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
14
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
15
+ * `err`: **(Error)**
16
+ * `data`: **(object)**
17
+
18
+ * `leaveRoom(rid, timeout, callback)`: 离开房间
19
+ * `rid`: **(Required | Int64)** 房间 id
20
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
21
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
22
+ * `err`: **(Error)**
23
+ * `data`: **(object)**
24
+
25
+ * `getUserRooms(timeout, callback)`: 获取用户所在的Room
26
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
27
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
28
+ * `err`: **(Error)**
29
+ * `data`: **(array[Int64])**
30
+
31
+ * `setRoomInfo(rid, oinfo, pinfo, timeout, callback) `: 设置房间信息
32
+ * `rid`: **(Required | Int64)** 房间id
33
+ * `oinfo`: **(Optional | string)** 公开信息
34
+ * `pinfo`: **(Optional | string)** 私有信息
35
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
36
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
37
+ * `err`: **(object[mid:Int64, error:Error])**
38
+ * `data`: **(object)**
39
+
40
+ * `getRoomInfo(rid, timeout, callback) `: 获取房间的公开信息和私有信息,会检查用户是否在房间内
41
+ * `rid`: **(Required | Int64)** 房间id
42
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
43
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
44
+ * `err`: **(object[mid:Int64, error:Error])**
45
+ * `data`: **(object[oinfo:string, pinfo:string])**
46
+
47
+ * `getRoomOpenInfo(rid, timeout, callback) `: 获取房间的公开信息
48
+ * `rid`: **(Required | Int64)** 房间id
49
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
50
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
51
+ * `err`: **(object[mid:Int64, error:Error])**
52
+ * `data`: **(object[oinfo:string, pinfo:string])**
53
+
54
+
55
+ * `getRoomMembers(rid, timeout, callback)`: 获取房间成员
56
+ * `rid`: **(Required | int64)** RoomID
57
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
58
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
59
+ * `err`: **(Error)**
60
+ * `data`: **(uids: [int64])** 成员列表
61
+
62
+ * `getRoomCount(rids, timeout, callback)`: 获取房间成员数量
63
+ * `rids`: **(Required | [int64])** RoomID列表
64
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
65
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
66
+ * `err`: **(Error)**
67
+ * `data`: **(cn: [string => int])** 房间人数
package/docs/System.md ADDED
@@ -0,0 +1,49 @@
1
+ # RTM Client Websocket SDK System API Docs
2
+
3
+ ## Index
4
+
5
+ [TOC]
6
+
7
+ ## Apis
8
+
9
+ **协议范围:** 本页记录 FPNN 兼容 API 的参数和事件名称;列出的方法不一定都能通过 TLV v1 调用。请先核对 [TLV v1 支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵);两协议的 method、URI 和 Push 对照见[协议迁移说明](PROTOCOL_MIGRATION.md)。
10
+
11
+ * `addAttrs(attrs, timeout, callback)`: 设置客户端信息, 保存在当前链接中, 客户端可以获取到
12
+ * `attrs`: **(Required | object[string, string])** key-value形式的变量
13
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
14
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
15
+ * `err`: **(Error)**
16
+ * `data`: **(object)**
17
+
18
+ * `getAttrs(timeout, callback)`: 获取客户端信息
19
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
20
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
21
+ * `err`: **(Error)**
22
+ * `data`: **(object[attrs:array[Map])**
23
+ * `Map.login` **(string)** 登录时间, UTC时间戳
24
+ * `Map.my` **(string)** 当前链接的`attrs`
25
+
26
+ * `addDebugLog(msg, attrs, timeout, callback)`: 添加debug日志
27
+ * `msg`: **(Required | string)** 调试信息msg
28
+ * `attrs`: **(Required | string)** 调试信息attrs
29
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
30
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
31
+ * `err`: **(Error)**
32
+ * `data`: **(object)**
33
+
34
+ * `addDevice(apptype, devicetoken, timeout, callback)`: 添加设备, 应用信息
35
+ * `apptype`: **(Required | string)** 应用信息
36
+ * `devicetoken`: **(Required | string)** 设备信息
37
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
38
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
39
+ * `err`: **(Error)**
40
+ * `data`: **(object)**
41
+
42
+ * `removeDevice(devicetoken, timeout, callback)`: 删除设备, 应用信息
43
+ * `devicetoken`: **(Required | string)** 设备信息
44
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
45
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
46
+ * `err`: **(Error)**
47
+ * `data`: **(object)**
48
+
49
+