@cg-devcenter/rtc-fpnn-webjs-sdk 1.0.0-cg.10
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.
- package/README.md +113 -0
- package/dist/rtm.d.cts +3 -0
- package/dist/rtm.d.mts +59 -0
- package/dist/rtm.d.ts +639 -0
- package/dist/rtm.min.js +27 -0
- package/dist/rtm.mjs +18 -0
- package/dist/rtm.shared-worker.js +27 -0
- package/dist/rtm.vite-plugin.d.mts +8 -0
- package/dist/rtm.vite-plugin.mjs +23 -0
- package/dist/rtm.vite.d.ts +59 -0
- package/dist/rtm.vite.mjs +33 -0
- package/dist/rtm.webpack4-adapter.cjs +29 -0
- package/dist/rtm.webpack4-plugin.cjs +50 -0
- package/dist/rtm.webpack4-plugin.d.cts +5 -0
- package/docs/CAPABILITIES.md +129 -0
- package/docs/Chat.md +278 -0
- package/docs/Data.md +33 -0
- package/docs/EventProcess.md +126 -0
- package/docs/Files.md +52 -0
- package/docs/Friends.md +50 -0
- package/docs/Groups.md +64 -0
- package/docs/LEGACY_RTM_TLV_COMPATIBILITY.md +188 -0
- package/docs/Messages.md +183 -0
- package/docs/PROTOCOL_MIGRATION.md +148 -0
- package/docs/RTM_MIGRATION.md +206 -0
- package/docs/Rooms.md +67 -0
- package/docs/System.md +49 -0
- package/docs/TLV.md +62 -0
- package/docs/TLV_CONTRACT.md +180 -0
- package/docs/USAGE.md +624 -0
- package/docs/Users.md +48 -0
- package/docs/ValueAdded.md +82 -0
- package/package.json +93 -0
package/docs/USAGE.md
ADDED
|
@@ -0,0 +1,624 @@
|
|
|
1
|
+
# RTC WebSocket SDK TLV v1 接入与 API 参考
|
|
2
|
+
|
|
3
|
+
## 1. 文档范围
|
|
4
|
+
|
|
5
|
+
本文面向 TLV v1 接入者,按“跑通连接 → 了解生命周期 → 查 API 参数”组织。参数与返回值详解覆盖下方支持矩阵标记为 TLV v1 支持的 API;矩阵同时列出未开放 API,供确认边界。它不是 FPNN 传统 API 的完整参考。
|
|
6
|
+
|
|
7
|
+
| 入口 | 运行环境 | 能力范围 |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `createClient()` | 浏览器 | 默认 FPNN;支持 SharedWorker 时共享同 UID 多窗口连接,不支持时自动使用独立连接。 |
|
|
10
|
+
| `createClient({protocol: 'tlv-v1'})` | 浏览器 | 显式选择 TLV v1;支持 SharedWorker 时共享连接,不支持时自动使用独立 TLV 连接;可调用本文支持矩阵列出的 API。 |
|
|
11
|
+
| `createClient({sharing: false, protocol: 'tlv-v1'})` / `RTMClient` + `protocol: 'tlv-v1'` | 浏览器;Node.js 需注入 `webSocketFactory` | 独立 TLV v1 连接;本文 TLV v1 支持矩阵列出的 API。 |
|
|
12
|
+
| `RTMClient` + `protocol: 'fpnn'` | 浏览器 | 旧版兼容入口;兼容 API 仍受 FPNN 服务端能力和部署配置限制。 |
|
|
13
|
+
| `RTMSharedWorkerClient` | 支持 SharedWorker 的浏览器、同源页面 | 显式创建 Worker 客户端;默认 FPNN,指定 TLV v1 时使用 TLV。多个同源页面共享一个 UID 的 RTC 会话,Worker 全量转发 SDK 事件。 |
|
|
14
|
+
|
|
15
|
+
本文给出 TLV v1 方法参数和常见返回约定,不重复 TLV wire 字段的完整 schema。TLV Gate Answer 字段、数据类型和状态码以[TLV v1 Client 契约](TLV_CONTRACT.md)为准;TypeScript 完整声明见 [`dist/rtm.d.ts`](../dist/rtm.d.ts)。`fpnn` 的具体兼容范围以旧服务端为准;旧接口参数说明见[用户](Users.md)、[群组](Groups.md)、[房间](Rooms.md)、[消息](Messages.md)、[聊天](Chat.md)、[数据](Data.md)、[系统](System.md)、[文件](Files.md)、[好友](Friends.md)、[增值服务](ValueAdded.md)和[事件处理](EventProcess.md)文档。
|
|
16
|
+
|
|
17
|
+
需要从 FPNN 迁移到 TLV v1 时,先看 [协议迁移对照](PROTOCOL_MIGRATION.md):它列出了相同 `RTMClient` 业务 API 对应的旧 FPNN method 与 TLV URI,并标明支持边界和兼容差异。
|
|
18
|
+
|
|
19
|
+
如果是从上游 [`highras/rtm-client-sdk-websocket`](https://github.com/highras/rtm-client-sdk-websocket) 迁移,请先看[RTM SDK 迁移指南](RTM_MIGRATION.md)。该指南固定对照 GitHub `master` 的指定 commit;npm 包、fork 或内部构建可能与该源码不同。飞书统计中的服务端调用不属于本浏览器 SDK。
|
|
20
|
+
|
|
21
|
+
需要保留旧 RTM 业务方法、主要结果结构和 Push 名称并将协议切到 TLV 时,查看 [`legacy-rtm` 兼容迁移指南](LEGACY_RTM_TLV_COMPATIBILITY.md)。兼容模式仅由 `createClient()` 显式开启,不会改变默认协议或原生 API 行为。
|
|
22
|
+
|
|
23
|
+
### 交给测试人员或 AI 接入前
|
|
24
|
+
|
|
25
|
+
请随文提供以下环境信息,避免接入者猜测项目配置或尝试从浏览器获取项目密钥:
|
|
26
|
+
|
|
27
|
+
- SDK:安装 npm `latest` 标签对应的版本:`npm install @cg-devcenter/rtc-fpnn-webjs-sdk@latest`。包根 ESM、Vite 与 Webpack 4 构建插件、配置回退和 `getConnectionInfo()` 均包含在本包中。
|
|
28
|
+
- RTC 环境:`pid`、协议(通常为 `tlv-v1`)、完整 WebSocket endpoint,以及应用页面的 origin。
|
|
29
|
+
- 测试身份:发送 UID、接收 UID、账号权限和预期验证场景;不要在文档或任务描述中粘贴长期凭证。
|
|
30
|
+
- credential 获取方式:由哪个业务服务端接口签发、请求需要的登录态/参数、响应 JSON 字段名和 credential 有效期。项目 `SecretKey` 只保留在受控服务端或本机签发工具中。
|
|
31
|
+
- 页面模式:普通单页连接,或同 UID 多页面共享连接;共享模式还要说明 Worker 文件的部署方式和需要验证的浏览器。
|
|
32
|
+
|
|
33
|
+
缺少以上信息时,接入者仍可完成 API 集成,但不能独立验证真实 Gate 登录和消息收发。
|
|
34
|
+
|
|
35
|
+
### 用于实际项目的实时信令
|
|
36
|
+
|
|
37
|
+
- 先确认协议、PID、Gate 地址与签发 credential 的服务端属于同一环境。线上 HTTPS 页面使用 WSS;共享 Worker 应部署在应用同源地址,并被站点 CSP 的 `worker-src` 允许。现代 ESM 项目使用包根入口;Vite 项目增加一次 `/vite-plugin` 插件配置。
|
|
38
|
+
- 全局信令接收器保持 `conversation: null`;设置会话过滤后,该页面只收到匹配的消息 Push。UI 不可见或失去焦点不会改变 SDK 路由,但浏览器挂起页面会延后 JS 执行,静默回收 Worker 的恢复边界见下文。
|
|
39
|
+
- SDK 传送实时消息和信令,不提供音视频采集、编解码或媒体连接。业务应定义消息类型、业务 ID、有效期与处理确认;Gate 接受发送不等于对方业务已处理。
|
|
40
|
+
- 请求中断时发送结果可能未知,SDK 不自动重放。业务根据业务 ID 做幂等处理,并自行决定重试与断线补偿;需要历史补偿时也要确认项目启用对应服务能力。
|
|
41
|
+
- 每个业务调用都处理 callback / Promise 错误,不能只依赖全局事件。TLV 发送错误的嵌套结构、超时、鉴权与支持矩阵见本文对应章节。
|
|
42
|
+
|
|
43
|
+
## 2. 快速开始:登录、收 Push、发消息、关闭
|
|
44
|
+
|
|
45
|
+
### 默认共享接入
|
|
46
|
+
|
|
47
|
+
`createClient(options)` 优先使用 SharedWorker;浏览器不支持 SharedWorker,或配置中含有无法保留到 Worker 的运行时值(例如函数型 `webSocketFactory`、`md5`、`platformImpl` 或 metadata)时,会自动使用当前页面内的 `RTMClient`。两种模式使用同一个 `createClient()` facade、业务 API、事件和 Promise 接口;页面内模式不共享连接或登录态。`client.getConnectionInfo()` 返回 `{ mode: 'shared' | 'direct', fallbackReason: string | null }`。`sharing: false` 会主动选择页面内模式,`fallbackReason` 为 `null`。Worker 脚本加载失败、初始化失败或超时仍会报告错误,不会静默改成页面内连接。省略 `protocol` 时默认使用 FPNN;直接构造 `RTMSharedWorkerClient` 表示明确要求 Worker,不能传输的配置会抛出具体原因。只有显式设置 `protocol: 'tlv-v1'` 才选择 TLV v1。配置值不可传递时会自动改用页面内连接,并通过 `getConnectionInfo()` 报告模式与回退原因;浏览器不支持 SharedWorker 时也会使用页面内连接。共享连接按 PID、协议、UID 和 Gate endpoint 区分环境;两个共享入口在连接参数一致时可复用同一会话。
|
|
48
|
+
|
|
49
|
+
```js
|
|
50
|
+
const client = rtm.createClient({ pid, endpoint, webSocketFactory });
|
|
51
|
+
if (typeof client.getConnectionInfo === 'function') {
|
|
52
|
+
console.log(client.getConnectionInfo());
|
|
53
|
+
// { mode: 'direct', fallbackReason: 'options.webSocketFactory is a function; SharedWorker cannot preserve page-side function behavior' }
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
现代 ESM 项目从包根导入。Worker URL 按构建工具解析:Vite 开发模式在 `vite.config.js` 注册一次 SDK 插件,避免依赖预构建将 SDK 的 `import.meta.url` 移入 `.vite/deps`;生产 Worker 资源由 Vite 构建输出。Webpack 4 注册 SDK 的 `/webpack4` 插件;Webpack 5 使用包根 ESM 入口和标准资源解析。普通 HTML 将 SDK 脚本和 Worker 文件放在同源同目录。上述常规方式都不需要业务传 `workerUrl`;只有自定义 Worker 部署位置时才需要覆盖它。旧 `/vite` 入口继续兼容。包根 ESM 与构建插件均包含在本包中。下面可作为 Vite 页面脚本使用,替换项目配置和 credential 接口:
|
|
58
|
+
|
|
59
|
+
```js
|
|
60
|
+
import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
|
|
61
|
+
|
|
62
|
+
const uid = '10001';
|
|
63
|
+
const peerUid = '10002';
|
|
64
|
+
const client = rtm.createClient({
|
|
65
|
+
protocol: 'tlv-v1',
|
|
66
|
+
pid: 12345,
|
|
67
|
+
tlvEndpoint: 'wss://<gate-host>/service/websocket',
|
|
68
|
+
autoReconnect: true,
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
client.processor.on(rtm.RTMConfig.TLV_SERVER_PUSH.recvMessage, (event) => {
|
|
72
|
+
console.log('Received', event);
|
|
73
|
+
});
|
|
74
|
+
client.on('SharedSessionState', (session) => console.log('Session', session));
|
|
75
|
+
client.on('SharedWorkerError', (error) => console.error('Shared connection', error));
|
|
76
|
+
|
|
77
|
+
async function start() {
|
|
78
|
+
// 按 UID 挂接共享会话,尚未登录时不会建立 Gate WebSocket。
|
|
79
|
+
await client.whenReady(uid);
|
|
80
|
+
const session = client.getSharedSession();
|
|
81
|
+
let credential;
|
|
82
|
+
if (session.status === 'idle') {
|
|
83
|
+
const response = await fetch('/api/rtc/credential?uid=' + encodeURIComponent(uid), {
|
|
84
|
+
credentials: 'same-origin',
|
|
85
|
+
});
|
|
86
|
+
if (!response.ok) throw new Error('Credential request failed: ' + response.status);
|
|
87
|
+
credential = (await response.json()).credential;
|
|
88
|
+
if (!credential) throw new Error('Credential is missing');
|
|
89
|
+
}
|
|
90
|
+
await client.promises.login(uid, credential);
|
|
91
|
+
await client.promises.sendChat(peerUid, 'hello', '{}');
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
start().catch(console.error);
|
|
95
|
+
// 页面离开由 SDK 自动 detach;组件卸载时也可 client.destroy()。
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
已持有 credential 时直接 `client.promises.login(uid, credential)` 即可,SDK 从登录参数取 UID,无需先调用 `whenReady()`。第一次登录需要服务端 credential;后续同 UID 页面可省略。`on()` / `processor.on()` 可在登录之前订阅,不需要业务缓存监听器。
|
|
99
|
+
|
|
100
|
+
UID 使用正整数或十进制字符串;超过 JavaScript 安全整数范围时必须用字符串,最大为 uint64。SDK 规范化前导零并转为协议整数,不会把 UID 字符串直接发给 FPNN。无效或超范围的 UID 返回 `RTM_SHARED_UID_INVALID`,缺少 UID 返回 `RTM_SHARED_UID_REQUIRED`。
|
|
101
|
+
|
|
102
|
+
| 配置 / API | 默认与边界 |
|
|
103
|
+
| --- | --- |
|
|
104
|
+
| `createClient(options)` | 使用扁平客户端配置,默认优先共享、协议默认 `fpnn`;无法使用 SharedWorker 或配置含不可传输的运行时值时,自动回退为当前页面连接,并可用 `getConnectionInfo()` 查询模式和原因。 |
|
|
105
|
+
| `sharing: false` | 显式选择页面内连接,但仍返回相同的 `createClient()` facade。Node.js 使用 TLV 时传 `protocol: 'tlv-v1'` 和 `webSocketFactory`;FPNN 仍仅支持浏览器。 |
|
|
106
|
+
| `uid` | 可选;提供时立即挂接共享 Worker,适合收件箱自动观察其他页面登录。省略时在 `login()` / `loginIfNeeded()` / `whenReady(uid)` 时挂接。一个实例固定一个 UID;切换账号需 detach 后创建新实例。 |
|
|
107
|
+
| `workerName` / `workerUrl` | 可选高级覆盖项;常规接入不需要配置 `workerUrl`。默认共享身份由 PID、协议、UID 和 Gate endpoint 生成,endpoint 不需要单独配置。普通 HTML 使用脚本同目录规则;Vite 使用 `/vite-plugin`;Webpack 4 使用 `/webpack4`;Webpack 5 使用标准 ESM 资源解析。只有自定义 Worker 部署位置时才传同源 `workerUrl`。`workerNamespace` 仍可隔离应用。 |
|
|
108
|
+
| `whenReady(uid?)` | 等待首次挂接并返回当时的快照;后续状态用 `getSharedSession()` 或 `SharedSessionState` 读取。尚未绑定 UID 且未传 UID 时立即 reject `RTM_SHARED_UID_REQUIRED`,不会无限等待。 |
|
|
109
|
+
| `promises.login(uid, credential?, timeout?)` | 成功 resolve `{accepted: true, errorCode}`,RTC 拒绝或本地/Worker 错误 reject;并发同 UID 登录只发一次鉴权。`loginIfNeeded()` 保留 `{accepted, errorCode, reused, uid}` 的结果约定。 |
|
|
110
|
+
| `login(uid, credential?, callback?, timeout?)` | RTC 拒绝回调 `callback(false, numericCode)`;共享模式的本地/Worker 失败会通过 `SharedWorkerError` 提供详情。仅 `accepted === true` 表示登录成功;`promises.login()` 会 reject 详细错误。 |
|
|
111
|
+
| `destroy()` | 共享模式只 detach 当前页面;最后一页离开后按 `idleShutdownTimeout` 回收共享连接。独立模式关闭本页的 RTMClient。`bye()` / `close()` 结束当前连接。 |
|
|
112
|
+
| 会话路由与业务 API | 沿用 `setConversation()`、`processor`、重连和原协议的业务返回;业务能力由底层 `RTMClient` 决定,FPNN 文件发送可用。`createClient()` 会为函数或自定义实例配置自动选择页面内模式;直接 `RTMSharedWorkerClient` 则要求配置可传给 Worker。绑定 UID 前的业务请求明确报 `RTM_SHARED_UID_REQUIRED`。 |
|
|
113
|
+
|
|
114
|
+
共享还要求同一浏览器配置文件、origin 和 Worker URL。同一浏览器配置文件、origin、Worker URL、PID、协议、UID 和 Gate endpoint 的页面会复用一条连接;Gate 地址不同会自动隔离。**同一共享身份下的 `clientOptions` 必须一致**;认证、重连或其他参数不同会初始化失败,不会覆盖已有连接。`createClient()` 和 `RTMSharedWorkerClient` 自动使用相同规则,同一应用混用入口也能加入同一会话。显式传入 `workerName` 或 `workerNamespace` 时,共享页面仍须保持一致。
|
|
115
|
+
|
|
116
|
+
Gate endpoint 已自动区分测试、预发和生产环境,通常不需要设置 `workerNamespace`。只有同一 endpoint 下确实需要两组独立登录态时,才为各组设置不同 namespace。
|
|
117
|
+
|
|
118
|
+
### 原有单连接接入
|
|
119
|
+
|
|
120
|
+
先通过业务服务端为当前 UID 签发 credential。浏览器不能持有项目 SecretKey。下面的 `/api/rtc/credential` 是业务服务端接口占位,请替换成你们自己的鉴权接口;它应返回 `{ "credential": "..." }`。
|
|
121
|
+
|
|
122
|
+
将 SDK 浏览器 bundle 放入页面后,这段 HTML 可直接作为最小接入模板。替换 `pid`、`tlvEndpoint` 和用户 ID,并让 credential 接口能签发发送 UID 的 credential,即可连到真实 Gate:
|
|
123
|
+
|
|
124
|
+
```html
|
|
125
|
+
<script src="/assets/rtm.min.js"></script>
|
|
126
|
+
<script>
|
|
127
|
+
const rtm = window.rtm;
|
|
128
|
+
const config = {
|
|
129
|
+
pid: 12345,
|
|
130
|
+
tlvEndpoint: 'wss://<gate-host>/service/websocket',
|
|
131
|
+
uid: '10001',
|
|
132
|
+
peerUid: '10002',
|
|
133
|
+
};
|
|
134
|
+
const timeoutMs = 12000;
|
|
135
|
+
|
|
136
|
+
async function getCredential(uid) {
|
|
137
|
+
const response = await fetch(
|
|
138
|
+
'/api/rtc/credential?uid=' + encodeURIComponent(uid),
|
|
139
|
+
{ credentials: 'same-origin' },
|
|
140
|
+
);
|
|
141
|
+
if (!response.ok) throw new Error('Credential request failed: ' + response.status);
|
|
142
|
+
const result = await response.json();
|
|
143
|
+
if (!result.credential) throw new Error('Credential is missing');
|
|
144
|
+
return result.credential;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
async function startChat() {
|
|
148
|
+
const credential = await getCredential(config.uid);
|
|
149
|
+
const client = new rtm.RTMClient({
|
|
150
|
+
protocol: 'tlv-v1',
|
|
151
|
+
pid: config.pid,
|
|
152
|
+
tlvEndpoint: config.tlvEndpoint,
|
|
153
|
+
autoReconnect: true,
|
|
154
|
+
requestTimeout: timeoutMs,
|
|
155
|
+
});
|
|
156
|
+
let loggedIn = false;
|
|
157
|
+
|
|
158
|
+
client.on('ErrorRecorder', (error) => console.error('RTC connection error', error));
|
|
159
|
+
client.processor.on(rtm.RTMConfig.TLV_SERVER_PUSH.recvMessage, (event) => {
|
|
160
|
+
console.log('Received direct message', event);
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
try {
|
|
164
|
+
const uid = new rtm.RTMConfig.Int64(config.uid);
|
|
165
|
+
const peerUid = new rtm.RTMConfig.Int64(config.peerUid);
|
|
166
|
+
await client.promises.login(uid, credential, timeoutMs);
|
|
167
|
+
loggedIn = true;
|
|
168
|
+
|
|
169
|
+
const sent = await client.promises.sendChat(
|
|
170
|
+
peerUid, 'Hello from RTM SDK', '{}', undefined, timeoutMs,
|
|
171
|
+
);
|
|
172
|
+
console.log('Message accepted by Gate', sent);
|
|
173
|
+
} finally {
|
|
174
|
+
if (loggedIn) {
|
|
175
|
+
try {
|
|
176
|
+
await client.promises.bye(timeoutMs);
|
|
177
|
+
} catch (error) {
|
|
178
|
+
// TLV bye timeout/error closes the socket locally; keep cleanup bounded.
|
|
179
|
+
console.warn('Graceful close failed', error);
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
client.destroy();
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
startChat().catch((error) => console.error('RTM startup failed', error));
|
|
187
|
+
</script>
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
`sendChat` 的 `attrs` 是额外信息字符串;没有额外字段时传 `'{}'`。消息 ID `mid` 可省略,SDK 会生成。`promises.login()` 在鉴权拒绝时会 reject,业务请求的 Promise 则在 Gate 返回错误或请求超时时 reject。
|
|
191
|
+
|
|
192
|
+
### 引用与运行环境
|
|
193
|
+
|
|
194
|
+
```js
|
|
195
|
+
// CommonJS
|
|
196
|
+
const rtm = require('@cg-devcenter/rtc-fpnn-webjs-sdk');
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
现代 ESM 项目可从包根入口导入。Vite 项目在 `vite.config.js` 注册一次 SDK 插件,处理开发依赖预构建;SDK 的 ESM Worker 资源由 Vite 输出并自动传给 `RTMSharedWorkerClient`。应用代码不需要填写 Worker 路径:
|
|
200
|
+
|
|
201
|
+
```js
|
|
202
|
+
import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
```js
|
|
206
|
+
// vite.config.js
|
|
207
|
+
import { rtmSdkVitePlugin } from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite-plugin';
|
|
208
|
+
|
|
209
|
+
export default {
|
|
210
|
+
plugins: [rtmSdkVitePlugin()],
|
|
211
|
+
};
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Vue 2 / Webpack 4 项目在 Webpack 配置中注册 SDK 插件一次。它会随构建输出 Worker 资源并处理 `publicPath`,业务代码仍从包根导入 SDK,也不需要传 `workerUrl`:
|
|
215
|
+
|
|
216
|
+
```js
|
|
217
|
+
// webpack.config.js
|
|
218
|
+
const RTMSDKWebpack4Plugin = require('@cg-devcenter/rtc-fpnn-webjs-sdk/webpack4');
|
|
219
|
+
|
|
220
|
+
module.exports = {
|
|
221
|
+
plugins: [new RTMSDKWebpack4Plugin()],
|
|
222
|
+
};
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Webpack 5 项目从包根 ESM 入口导入即可使用标准资源解析,不需要 SDK 插件。无论使用 Vue、React 还是普通 JS,页面里的客户端创建方式相同。
|
|
226
|
+
|
|
227
|
+
浏览器可加载 `dist/rtm.min.js` 并从 `window.rtm` 取 SDK。Node.js 仅支持 TLV v1;通过 `RTMClient` 或 `createClient()` 传入 `webSocketFactory(url)`,返回对象须支持 `send(data)`、`close(code?, reason?)` 及 `onopen`、`onmessage`、`onerror`、`onclose`。`createClient()` 在 Node.js 会报告 direct 模式。SDK 不附带 Node WebSocket 实现。`fpnn` 和 SharedWorker 仅面向浏览器。
|
|
228
|
+
|
|
229
|
+
若用 unpkg 或 jsDelivr 加载 `rtm.min.js`,不要让 SDK 自动推导共享 Worker 地址:推导出的 Worker 会落在 CDN 域名,与业务页面不同源。可把同版本的 `rtm.shared-worker.js` 部署到应用自己的同源静态目录,并显式传入 `workerUrl`;如果不需要多页面共享,可设置 `sharing: false`。例如:
|
|
230
|
+
|
|
231
|
+
```js
|
|
232
|
+
const client = window.rtm.createClient({
|
|
233
|
+
pid,
|
|
234
|
+
endpoint,
|
|
235
|
+
uid,
|
|
236
|
+
workerUrl: '/sdk/rtm.shared-worker.js',
|
|
237
|
+
});
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
SharedWorker 仍要求 Worker 与页面同源;仅配置跨域 CORS 不会满足此限制。常规 npm bundler 接入和应用同源 HTML 部署不受此 CDN 注意事项影响。
|
|
241
|
+
|
|
242
|
+
## 3. 生命周期与错误处理
|
|
243
|
+
|
|
244
|
+
### 初始化和生命周期 API
|
|
245
|
+
|
|
246
|
+
| API | 参数和结果 |
|
|
247
|
+
| --- | --- |
|
|
248
|
+
| `new RTMClient(options)` | 创建客户端;`pid` 必填,必须显式设 `protocol: 'tlv-v1'` 才使用 TLV。构造参数见下表。 |
|
|
249
|
+
| `login(uid, credential, callback, timeout?)` | `callback(accepted, errorCode)`。仅 `accepted === true` 表示进入登录态。`timeout` 限制 auth 请求;WebSocket 握手由 `connectionTimeout` 限制。 |
|
|
250
|
+
| `promises.login(uid, credential, timeout?)` | 登录成功 resolve `{accepted: true, errorCode}`;登录拒绝或失败 reject,错误对象带 `code`。 |
|
|
251
|
+
| `bye(timeout?, callback?)` | 发协议级关闭请求;Gate 应答后 callback 为 `(err, data)`。TLV 失败或超时会关闭底层连接。Promise 版本等待应答并在失败时 reject。 |
|
|
252
|
+
| `close()` | 立即关闭当前连接,不等待协议级关闭应答。 |
|
|
253
|
+
| `startAutoReconnect()` | 关闭当前连接并允许 SDK 按配置重连。`createClient()` 的 `legacy-rtm` 模式下也会作为本地生命周期方法直接转发,不经过 TLV 业务 API 映射。 |
|
|
254
|
+
| `destroy()` | 立即关闭连接并释放客户端资源;正在等待的请求会以错误结束。 |
|
|
255
|
+
| `getServerTime(timeout, callback)` | 查询服务端时间;TLV 返回 `server_ms`。 |
|
|
256
|
+
| `addAttrs(attrs, timeout, callback)` / `getAttrs(timeout, callback)` | 设置或读取连接属性。 |
|
|
257
|
+
| `addDebugLog(msg, attrs, timeout, callback)` | 向 Gate 发送调试日志。 |
|
|
258
|
+
|
|
259
|
+
### RTMClient 构造参数
|
|
260
|
+
|
|
261
|
+
省略可选项时使用默认值;除非另有说明,时间单位为毫秒。
|
|
262
|
+
|
|
263
|
+
| 参数 | 类型 | 必填 / 默认值 | 说明 |
|
|
264
|
+
| --- | --- | --- | --- |
|
|
265
|
+
| `pid` | `number` | 必填 | RTC 项目 ID。 |
|
|
266
|
+
| `protocol` | `'tlv-v1' \| 'fpnn'` | 默认 `'fpnn'` | 新接入请显式设为 `'tlv-v1'`。 |
|
|
267
|
+
| `endpoint` | `string` | FPNN 必填 | FPNN Gate 主机及可选端口(`host[:port]`),使用 `ws://`。 |
|
|
268
|
+
| `ssl_endpoint` | `string` | FPNN 可选 | FPNN Gate 主机及可选端口(`host[:port]`),使用 `wss://`;提供时优先于 `endpoint`。 |
|
|
269
|
+
| `tlvEndpoint` | `string` | TLV 必填 | Gate 提供的完整 `ws://` 或 `wss://` URL,含部署要求的路径,通常以 `/service/websocket` 结尾。 |
|
|
270
|
+
| `autoReconnect` | `boolean` | `true` | 自动重连开关。终止性鉴权错误不会无限重试。 |
|
|
271
|
+
| `connectionTimeout` | `number` | `30000` | 建立 WebSocket 连接的超时。 |
|
|
272
|
+
| `requestTimeout` | `number` | `20000` | 请求默认超时;方法级 `timeout > 0` 时覆盖此值。 |
|
|
273
|
+
| `requestMetadata` | `object \| (() => object)` | 可选 | TLV v1 只发送 `trace`、`sent_ms`。禁止放 credential、SecretKey 等敏感字段。SharedWorker 仅接受静态可传输对象;函数形式会使 `createClient()` 回退到页面内连接。 |
|
|
274
|
+
| `requestMetadataProvider` | `() => object` | 可选 | `requestMetadata` 函数形式的兼容选项;通过 `createClient()` 使用时会自动选择页面内连接。 |
|
|
275
|
+
| `webSocketFactory` | `(url) => RTMWebSocket` | Node 必填 | 自定义 WebSocket 工厂。浏览器通常使用全局 `WebSocket`;`createClient()` 会在配置该函数时选择页面内连接。 |
|
|
276
|
+
| `authSec` / `authVer` | `number` / `2` | 可选 | 自签鉴权字段;须同时提供,且 `authVer` 必须为 `2`。 |
|
|
277
|
+
| `locale` / `clientVersion` | `string` | 可选 | 登录语言和客户端版本。未提供版本时 SDK 使用内置版本字符串。 |
|
|
278
|
+
| `attrs` | `Record<string, string>` | 可选 | 登录连接属性。 |
|
|
279
|
+
| `tlvHeartbeatIdleMs` | `number` | `30000` | TLV 空闲多久发送心跳。 |
|
|
280
|
+
| `tlvHeartbeatTimeoutMs` | `number` | `10000` | TLV 心跳应答等待上限。 |
|
|
281
|
+
| `pushDedupTtlMs` | `number` | `30000` | 可靠 Push 的本地去重窗口,实际下限 20 秒。 |
|
|
282
|
+
| `regressiveStrategy` | `{startConnectFailedCount, maxIntervalSeconds, linearRegressiveCount}` | `{3, 8, 4}` | 控制自动重连退避;分别表示开始线性退避的失败次数、最大间隔秒数和线性递增步数。 |
|
|
283
|
+
|
|
284
|
+
`requestMetadata` 与 `requestMetadataProvider` 任选一种即可。实现按 `requestMetadata || requestMetadataProvider` 取值:当 `requestMetadata` 为 truthy 时优先使用它,`requestMetadataProvider` 只作后备;两者同时提供时,前者生效。建议新接入统一使用 `requestMetadata`。
|
|
285
|
+
|
|
286
|
+
### Callback、Promise 与错误
|
|
287
|
+
|
|
288
|
+
| 调用类型 | 成功 | 失败 |
|
|
289
|
+
| --- | --- | --- |
|
|
290
|
+
| `login` callback | `callback(true, 0)` | `callback(false, errorCode)`;TLV Gate 仅返回 `accepted: false` 而无错误码时 SDK 使用 `200027`。 |
|
|
291
|
+
| `promises.login` | resolve `{accepted: true, errorCode}` | reject 带 `code` 的 Error。 |
|
|
292
|
+
| 普通业务 callback | `callback(null, data)` | `callback(error, null)`;错误通常包含 `code`,TLV `control.error` 还含 `status`、`reason`。TLV 消息发送 API 的错误结构是例外,见下文。 |
|
|
293
|
+
| `client.promises.method(...原参数)` | resolve 对应 callback 的 `data` | reject 对应 callback 的错误。参数顺序相同,去掉 callback;不要向 Promise 方法传 callback。 |
|
|
294
|
+
| `loginIfNeeded` | resolve `{accepted, errorCode, reused, uid}` | RTC 鉴权结果仍 resolve;Worker 启动、调用参数或缺少 credential 等 SDK 错误 reject。 |
|
|
295
|
+
|
|
296
|
+
`ErrorRecorder(error)` 用于连接、协议、自动重连和登录错误,不会代替普通业务请求的 callback 或 Promise rejection。业务失败应检查各自调用结果。请求超时与连接中断会结束挂起调用;连接中断时写入结果可能未知,SDK 不自动重放,业务应按幂等规则决定是否重试。
|
|
297
|
+
|
|
298
|
+
`bye()` 与普通业务调用不同,是异步的协议关闭握手。结束整个会话时,使用有超时的 Promise,并在 `finally` 中 `close()` 后 `destroy()`;不必等待 `SessionClosed` 才能清理:
|
|
299
|
+
|
|
300
|
+
```js
|
|
301
|
+
try {
|
|
302
|
+
await client.promises.bye(5000);
|
|
303
|
+
} catch (error) {
|
|
304
|
+
console.warn('Gate did not confirm close', error);
|
|
305
|
+
} finally {
|
|
306
|
+
try { client.close(); } finally { client.destroy(); }
|
|
307
|
+
}
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
Promise 成功表示 Gate 已应答关闭请求。直接结束整个会话可调用 `close()`,这可能中止尚未完成的 `bye()`。共享模式下只关闭当前页面或卸载组件时仅调用 `destroy()`,不要调用 `bye()` / `close()`,其他页面会继续使用共享会话。独立 `RTMClient.destroy()` 则会关闭其自身连接。
|
|
311
|
+
|
|
312
|
+
常用事件:`ErrorRecorder(error)`、`ReloginCompleted(successful, retryAgain, errorCode, retriedCount)`、`SessionClosed(errorCode)`。TLV 可靠 Push 由 SDK 自动 ACK,并按 `message_ref` 去重;这不等于离线补拉或业务存储。
|
|
313
|
+
|
|
314
|
+
## 4. 同 UID 多窗口:SharedWorker
|
|
315
|
+
|
|
316
|
+
SharedWorker 是 SDK 实例和登录状态的共享底座:负责端口、同 UID 登录合并、调用转发和生命周期。协议实现、业务 API、文件上传、重连、ACK 和去重均由底层 `RTMClient` 执行,公开业务方法从 SDK 自动代理。Worker 不检查消息类型、不筛选业务事件,也不增加业务能力限制。`conversation` / `setConversation()` 是页面端的可选筛选工具。
|
|
317
|
+
|
|
318
|
+
`RTMSharedWorkerClient` 是 SDK 提供的同源多页面连接复用能力。每个页面创建一个客户端端口,SDK 在 SharedWorker 内维护一个 `RTMClient` 和一条 WebSocket。常规接入无需手写 `workerUrl`,Worker URL 按构建方式自动解析:普通 HTML 从主 SDK 脚本地址推导同目录下的 `rtm.shared-worker.js`;Vite 项目在配置中注册 `/vite-plugin`;Webpack 4 项目注册 `/webpack4` 插件;Webpack 5 项目从包根 ESM 入口使用标准资源解析。旧 `/vite` 入口继续兼容。只有自定义 Worker 部署位置时才显式传入同源 `workerUrl`。Vue、React 和普通 JS 使用相同的 SDK API,具体 Worker 配置由构建工具决定。共享身份需要相同浏览器配置文件、origin、解析后的 Worker URL、`workerName` 和结构一致的 `clientOptions`。一个 Worker 只登录一个 UID、使用一种协议;传入 `uid` 后,SDK 根据协议、PID、UID 和实际 Gate endpoint 自动生成稳定身份,因此不同 Gate 环境自动使用不同连接;同一名称下其他 `clientOptions` 不一致会明确报错。`createSharedWorkerName()` 可显式传 `endpoint` 构造隔离名称。SDK 升级后请关闭同一共享身份的所有旧页面,等待 `idleShutdownTimeout`(默认 5 秒)后重新打开,确保旧 Worker 结束并加载新脚本;新旧页面/Worker 版本混用不受支持。
|
|
319
|
+
|
|
320
|
+
| API / 选项 | 参数与结果 |
|
|
321
|
+
| --- | --- |
|
|
322
|
+
| `new RTMSharedWorkerClient(options)` | `clientOptions` 必填;`clientOptions.protocol` 省略时默认 FPNN,提供 `pid` 及 `endpoint` 或 `ssl_endpoint`(`host[:port]`,不含 URL scheme 和路径)。选择 TLV v1 时显式设置 `protocol: 'tlv-v1'`,并提供完整 `tlvEndpoint`。`workerUrl` 可选,同源 Worker 脚本 URL;普通浏览器脚本省略时 SDK 推导加载 SDK 的脚本同目录下的 `rtm.shared-worker.js`,现代 ESM 入口自动解析包内 Worker 资源。提供 `uid` 且省略 `workerName` 时,SDK 根据协议、`clientOptions.pid`、`uid`、实际 Gate endpoint 和 `workerNamespace` 生成稳定名称;若需要自行构造名称,可调用 `createSharedWorkerName({protocol, pid, uid, endpoint, namespace})`。若 `uid` 和 `workerName` 都省略,会使用通用默认名称;多账号应用应传其中一个,避免不同 UID 页面加入同一个 Worker。`readyTimeout` 默认 10000 毫秒;`idleShutdownTimeout` 默认 5000 毫秒,最后一个页面 detach 后等待这段时间再关闭共享连接,设为 `0` 表示立即关闭;同一 Worker 的所有页面必须使用相同值。`conversation` 可选,默认 `null` 接收全部会话 Push。 |
|
|
323
|
+
| `whenReady()` | 等 Worker 首次初始化并返回 `{status, uid}` 初始快照;再次调用不会刷新快照,当前状态用 `getSharedSession()`。初始化失败时 Promise reject,SDK 会自动 detach 并关闭当前页面的端口。 |
|
|
324
|
+
| `getSharedSession()` | 同步返回本页面最近观察到的 `{status, uid}`。 |
|
|
325
|
+
| `loginIfNeeded(uid, credential?, timeout?)` | 同 UID 会话已登录则复用;登录中则加入该登录;会话空闲时须提供服务端签发的 credential。resolve `{accepted, errorCode, reused, uid}`。 |
|
|
326
|
+
| `setConversation(conversation, callback?)` | 修改当前页面监听器的本地 Push 筛选;Worker 始终全量分发事件,传 `null` 接收全部会话。出错时通过可选 callback 返回。 |
|
|
327
|
+
| `destroy()` | detach 当前页面端口;Worker 仍有其他页面时不关闭 RTC 连接。它会完成端口与监听器清理后再传播待处理业务回调抛出的异常。 |
|
|
328
|
+
| `shared.promises.*` / `shared.*` | 可调用所选协议的 `RTMClient` 业务 API,参数、callback、返回对象和 Push 事件均沿用该协议;业务方法自动代理,能力与协议错误由底层 SDK 决定;FPNN 支持 `sendFile` / `sendGroupFile` / `sendRoomFile`,TLV 由协议契约拒绝。`bye()` / `close()` 影响所有共享页面。 |
|
|
329
|
+
|
|
330
|
+
普通浏览器脚本部署时,把 `dist/rtm.min.js` 与 `dist/rtm.shared-worker.js` 放在同源静态目录的同一目录,SDK 会自动定位 Worker 文件。现代 ESM 项目从包根导入;Vite 使用 `/vite-plugin`,Webpack 4 使用 `/webpack4` 插件,Webpack 5 使用标准 ESM 资源解析。以上常规方式均无需手动设置 `workerUrl`;自定义 Worker 部署位置时才传同源覆盖地址。以下示例展示页面接入、首次登录、后续页面复用、Push 监听和当前页 detach。与快速开始相同,替换项目参数和 credential 接口:
|
|
331
|
+
|
|
332
|
+
```js
|
|
333
|
+
const rtm = window.rtm;
|
|
334
|
+
const uid = '10001';
|
|
335
|
+
const credentialUrl = '/api/rtc/credential?uid=' + encodeURIComponent(uid);
|
|
336
|
+
|
|
337
|
+
async function getCredential() {
|
|
338
|
+
const response = await fetch(credentialUrl, { credentials: 'same-origin' });
|
|
339
|
+
if (!response.ok) throw new Error('Credential request failed: ' + response.status);
|
|
340
|
+
const result = await response.json();
|
|
341
|
+
if (!result.credential) throw new Error('Credential is missing');
|
|
342
|
+
return result.credential;
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
function renderPush(event) { console.log('RTC Push', event); }
|
|
346
|
+
function renderSession(session) { console.log('Shared RTC session', session); }
|
|
347
|
+
|
|
348
|
+
let shared = null;
|
|
349
|
+
function createSharedClient() {
|
|
350
|
+
const client = new rtm.RTMSharedWorkerClient({
|
|
351
|
+
uid, // SDK 自动按 PID、协议、UID 和 Gate endpoint 复用同环境会话;此 UID 仅用于挂接,不会自动登录。
|
|
352
|
+
clientOptions: {
|
|
353
|
+
protocol: 'tlv-v1',
|
|
354
|
+
pid: 12345,
|
|
355
|
+
tlvEndpoint: 'wss://<gate-host>/service/websocket',
|
|
356
|
+
autoReconnect: true,
|
|
357
|
+
},
|
|
358
|
+
conversation: null, // 收件箱接收所有会话;聊天页可只订阅一个会话。
|
|
359
|
+
});
|
|
360
|
+
[
|
|
361
|
+
rtm.RTMConfig.TLV_SERVER_PUSH.recvMessage,
|
|
362
|
+
rtm.RTMConfig.TLV_SERVER_PUSH.recvGroupMessage,
|
|
363
|
+
rtm.RTMConfig.TLV_SERVER_PUSH.recvRoomMessage,
|
|
364
|
+
rtm.RTMConfig.TLV_SERVER_PUSH.recvBroadcastMessage,
|
|
365
|
+
].forEach((name) => client.processor.on(name, renderPush));
|
|
366
|
+
client.on('SharedSessionState', renderSession);
|
|
367
|
+
client.on('SharedWorkerError', (error) => {
|
|
368
|
+
console.error('SharedWorker client is no longer usable', error);
|
|
369
|
+
client.destroy();
|
|
370
|
+
if (shared === client) shared = null;
|
|
371
|
+
// 显示“重新连接”操作;用户触发后再次调用 connectInbox()。
|
|
372
|
+
});
|
|
373
|
+
return client;
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
async function connectInbox() {
|
|
377
|
+
if (!shared) shared = createSharedClient();
|
|
378
|
+
const client = shared;
|
|
379
|
+
await client.whenReady();
|
|
380
|
+
const snapshot = client.getSharedSession();
|
|
381
|
+
// 建议先让一个页面登录,再打开其余页面。已登录/正在登录时无需再取 credential。
|
|
382
|
+
const credential = snapshot.status === 'idle' ? await getCredential() : undefined;
|
|
383
|
+
const result = await client.loginIfNeeded(uid, credential);
|
|
384
|
+
if (!result.accepted) throw Object.assign(new Error('RTM login rejected'), { code: result.errorCode });
|
|
385
|
+
console.log('Shared session ready', result);
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
connectInbox().catch(console.error);
|
|
389
|
+
// 只有 SDK 报告 SharedWorkerError 后才重建 client;新 client 的登录快照可能是 idle,届时再取 credential。
|
|
390
|
+
// 当前页关闭时 SDK 会自动 detach(BFCache 页面例外);应用也可主动调用:
|
|
391
|
+
// shared?.destroy();
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
- 首个页面在 UID 尚未登录时传入服务端签发的 credential;其他同 UID 页面在已登录时不需要 credential。若它们赶在首次登录完成前打开,`loginIfNeeded()` 会加入同一次登录。
|
|
395
|
+
- `whenReady()` 返回首次挂接快照 `{status, uid}`,当前状态用 `getSharedSession()`;`loginIfNeeded(uid, credential?, timeout?)` 返回 `{accepted, errorCode, reused, uid}`。credential 不会广播到页面。
|
|
396
|
+
- `conversation: {type: 'direct'|'group'|'room', id}` 在当前页面适配器中筛选私聊发送者、群或房间 Push;`null` 接收全部会话。Worker 始终向所有端口分发完整 SDK 事件,运行中可调用 `setConversation(...)` 修改本地筛选。
|
|
397
|
+
- 所有 SDK 事件由 Worker 原样分发到全部页面端口。页面适配器的可选 `conversation` 筛选会将 `event.room_removed` 限定为当前房间;`event.broadcast` 和 `event.kicked` 始终通知当前页面监听器。
|
|
398
|
+
- `destroy()` 只 detach 当前页面;还有页面连接时共享连接继续运行。任一页面调用 `bye()` / `close()` 会结束所有页面共享的 RTC 会话。
|
|
399
|
+
- 最后一个页面 detach 后,SDK 默认等待 5 秒再销毁 RTMClient 和连接;宽限期内新页面接入会取消回收。浏览器也可能在页面挂起或资源回收时结束 Worker,但 SDK 当前没有就绪后的心跳检测,浏览器静默回收不保证触发事件。
|
|
400
|
+
- 收到 `SharedWorkerError` 时,表示 SDK 检测到当前页面到 Worker 的错误(例如初始化失败、Worker `error` 或消息端口错误),可丢弃旧 client 并用相同连接配置创建新 client。此事件不是 Worker 被浏览器回收的通用通知;如果浏览器静默结束 Worker,页面可能无法及时获知。新 client 的登录快照若为 `idle`,重新登录时必须取得服务端为该 UID 签发的 credential。SDK 不在页面、Worker 或存储中持久化 credential,也不会在 Worker 进程丢失后自动重登。
|
|
401
|
+
- SharedWorker 仅共享实时连接和 Push,不同步页面草稿、未读 UI 或消息列表,也不持久化登录态。它不跨 origin、浏览器配置文件或 InPrivate 窗口共享;浏览器没有 SharedWorker API 时,`createClient()` 会改用每页一条独立连接,因此这些页面不能共享登录态。Worker 脚本加载或初始化失败仍会报告错误。
|
|
402
|
+
- 直接构造 `RTMSharedWorkerClient` 时,`clientOptions` 必须可安全传递给 Worker;函数、循环引用、访问器和自定义原型实例会抛出带配置路径的错误。通过 `createClient()` 时,这些配置会改用页面内 `RTMClient`,原因可通过 `getConnectionInfo()` 查询。
|
|
403
|
+
|
|
404
|
+
### FPNN 多窗口接入
|
|
405
|
+
|
|
406
|
+
FPNN SharedWorker 已包含在 npm `latest` 中。Node.js 仍只支持 TLV。
|
|
407
|
+
|
|
408
|
+
首次登录、后续窗口 `loginIfNeeded()`、`SharedSessionState`、路由和 detach 的使用方式与上面的 TLV 示例相同。FPNN 只改变连接配置和 Push 订阅;以下片段假定已加载 `rtm` 并取得 `pid`、`uid`、`peerUid`、FPNN Gate 地址及首次登录所需的 credential:
|
|
409
|
+
|
|
410
|
+
```js
|
|
411
|
+
const shared = new rtm.RTMSharedWorkerClient({
|
|
412
|
+
uid,
|
|
413
|
+
conversation: { type: 'direct', id: peerUid },
|
|
414
|
+
clientOptions: {
|
|
415
|
+
protocol: 'fpnn', // 可省略;未指定协议时 RTMSharedWorkerClient 默认 FPNN。
|
|
416
|
+
pid,
|
|
417
|
+
ssl_endpoint: 'gate.example:13321', // wss;ws 使用 endpoint: 'gate.example:13321'
|
|
418
|
+
autoReconnect: true,
|
|
419
|
+
},
|
|
420
|
+
});
|
|
421
|
+
|
|
422
|
+
// FPNN 文本聊天使用 recvChat,通用消息使用 recvMessage。
|
|
423
|
+
shared.processor.on(rtm.RTMConfig.SERVER_PUSH.recvChat, (event) => {
|
|
424
|
+
console.log('FPNN chat', event.from.toString(), event.msg);
|
|
425
|
+
});
|
|
426
|
+
shared.on('SharedSessionState', (state) => console.log('Shared session', state));
|
|
427
|
+
await shared.whenReady();
|
|
428
|
+
const result = await shared.loginIfNeeded(uid, credential);
|
|
429
|
+
if (!result.accepted) throw new Error('RTC login failed: ' + result.errorCode);
|
|
430
|
+
await shared.promises.sendChat(peerUid, 'hello', '{}');
|
|
431
|
+
// 页面离开时 SDK 自动 detach;也可显式 shared.destroy()。
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
FPNN 的 `endpoint` / `ssl_endpoint` 接收 `host[:port]`,SDK 补上 `ws://` / `wss://` 和 `/service/websocket`;它与 TLV 的完整 URL 配置不同。自动 Worker identity 包含协议,因此同 UID 的 FPNN / TLV 页面不会共享一条连接。若显式指定相同 `workerName` 却传入不同协议或配置,后加入页面初始化失败,不会覆盖已有会话。
|
|
435
|
+
|
|
436
|
+
FPNN Push 保留 `SERVER_PUSH` 事件和 `from / gid / rid / mid / msg` 等字段;TLV 保留 `TLV_SERVER_PUSH` 事件及其字段。Worker 原样分发所有 SDK 事件;ACK、去重、协议校验和业务请求都由底层 `RTMClient` 处理。页面适配器只在应用显式设置 `conversation` 时进行本地筛选。FPNN 的 `fileToken`、`sendFile`、`sendGroupFile`、`sendRoomFile` 都可通过共享调用使用,File 对象经结构化克隆交给 Worker,上传继续由 SDK 的文件代理连接完成。TLV 文件调用由底层协议契约返回 `200020`,共享层不维护业务 API 禁用名单。传统参数与 Push 细节见 [协议迁移对照](PROTOCOL_MIGRATION.md) 和 [事件处理说明](EventProcess.md)。
|
|
437
|
+
|
|
438
|
+
## 5. 参数与返回值约定
|
|
439
|
+
|
|
440
|
+
下表解释多个 API 复用的参数;详细 wire 字段、返回字段和 TLV 类型请参照[契约表](TLV_CONTRACT.md)。
|
|
441
|
+
|
|
442
|
+
| 参数 | 含义、类型和默认行为 |
|
|
443
|
+
| --- | --- |
|
|
444
|
+
| `uid` / `ouid` / `from` / `to` / `uids` | 用户 ID 或用户 ID 数组。可传十进制字符串、number 或 `RTMConfig.Int64`。大于 `Number.MAX_SAFE_INTEGER` 时必须用字符串或 `Int64`。 |
|
|
445
|
+
| `gid` / `rid` / `gids` / `rids` | 群组、房间 ID 或数组;同样建议大 ID 使用字符串或 `Int64`。 |
|
|
446
|
+
| `mid` | 消息引用 ID,不是历史分页游标。发送 API 可省略以便 SDK 生成;按消息 ID 查询时表示锚点。 |
|
|
447
|
+
| `timeout` | 单次请求超时,正数毫秒;省略或不为正数时使用 `requestTimeout`(默认 20 秒)。连接握手另由 `connectionTimeout` 控制。 |
|
|
448
|
+
| `msg` / `payload` | 消息内容,TLV v1 接受字符串或二进制。 |
|
|
449
|
+
| `attrs` | 消息附加信息字符串,映射为 `extra`;TLV 要求此字段存在,无附加信息时传 `'{}'`。 |
|
|
450
|
+
| `mtype` / `mtypes` | 消息类型整数或类型数组。常用值见 `RTMConfig.CHAT_TYPE`;省略 `mtypes` 表示不按类型筛选。 |
|
|
451
|
+
| `begin` / `end` | 历史查询起止时间,Unix epoch 毫秒;省略时 SDK 发 `0`。上下界包含规则由 Gate 定义,本文不额外推断。 |
|
|
452
|
+
| `desc` | 布尔值,映射为历史查询方向 `reverse`;`true` 从 `end` 开始倒序查询,`false` 从 `begin` 开始顺序查询;默认 `false`。 |
|
|
453
|
+
| `num` | 单页消息数,映射为 `limit`;默认 `20`。 |
|
|
454
|
+
| `lastid` | 历史翻页 cursor,非消息 ID 或时间戳;默认 `0`。把上一页结果的 `next` 作为下一页的 `lastid`。 |
|
|
455
|
+
| `mtime` | 会话/未读筛选起点,Unix epoch 毫秒,映射为 `since_ms`;省略表示不提供该筛选条件。 |
|
|
456
|
+
| `category` / `type` | 会话或单条消息所在的通道编号。类型值及各 API 允许范围见 TLV 契约;不要把它当成消息类型。 |
|
|
457
|
+
| `xid` | 与 `category` 对应的目标 ID,例如私聊 UID 或群/房间 ID。 |
|
|
458
|
+
| `readSeq` | `setSessionRead` 要标为已读的消息序号上界,正整数 int64。 |
|
|
459
|
+
| `clear` / `localOnly` / `online` | 布尔开关;分别控制查询时标记已读、本地删除会话、是否查询在线成员。未读摘要的 `clear` 默认 `false`;`removeSession` 的 `localOnly` 默认 `false`。 |
|
|
460
|
+
|
|
461
|
+
### 构造、账号和存储
|
|
462
|
+
|
|
463
|
+
下表业务 callback 方法以 `callback(err, data)` 结尾;`login` 和 `bye` 的回调形式见上文。表中省略重复的 callback 参数。Promise 版本保留业务参数顺序,仅省略 callback。
|
|
464
|
+
|
|
465
|
+
| API | 参数 | TLV v1 成功返回 |
|
|
466
|
+
| --- | --- | --- |
|
|
467
|
+
| `getOnlineUsers(uids, timeout)` | `uids`: 用户 ID 数组 | `RTMConfig.Int64[]` 在线 UID。 |
|
|
468
|
+
| `setUserInfo(oinfo, pinfo, timeout)` | `oinfo` 公共资料字符串;`pinfo` 私有资料字符串,均可省略 | 空 data。 |
|
|
469
|
+
| `getUserInfo(timeout)` | 无 | `{public_data, private_data}`。 |
|
|
470
|
+
| `getUserOpenInfo(uids, timeout)` | 用户 ID 数组 | `profiles` 用户资料映射。 |
|
|
471
|
+
| `setTranslationLanguage(targetLanguage, timeout)` | 目标语言字符串 | `{updated}`。 |
|
|
472
|
+
| `dataSet(key, value, timeout)` / `dataGet(key, timeout)` / `dataDelete(key, timeout)` | `key` 存储键;`value` 字符串 | set/delete 空 data;get 返回 `{value}`。 |
|
|
473
|
+
| `addBlacks(blacks, timeout)` / `deleteBlacks(blacks, timeout)` | `blacks`: 用户 ID 数组,TLV 最多 100 项 | 空 data。 |
|
|
474
|
+
| `getBlacks(timeout)` | 无 | `RTMConfig.Int64[]` 黑名单 UID。 |
|
|
475
|
+
|
|
476
|
+
### 群组和房间
|
|
477
|
+
|
|
478
|
+
| API | 参数 | TLV v1 成功返回 |
|
|
479
|
+
| --- | --- | --- |
|
|
480
|
+
| `addGroupMembers(gid, uids, timeout)` / `deleteGroupMembers(gid, uids, timeout)` | 群 ID、成员 UID 数组 | 空 data。 |
|
|
481
|
+
| `getGroupMembers(gid, online, timeout)` | `online` 可选,是否附带在线成员 | `{members, active_members?}`。 |
|
|
482
|
+
| `getGroupCount(gid, online, timeout)` | `online` 可选,是否返回在线人数 | `{total, active_total?}`。 |
|
|
483
|
+
| `getUserGroups(timeout)` | 无 | 群 ID 数组 `RTMConfig.Int64[]`。 |
|
|
484
|
+
| `setGroupInfo(gid, oinfo, pinfo, timeout)` | 群 ID;公共/私有资料字符串,可省略 | 空 data。 |
|
|
485
|
+
| `getGroupInfo(gid, timeout)` / `getGroupOpenInfo(gid, timeout)` | 群 ID | 完整资料 `{public_data, private_data}` 或公开资料 `{public_data}`。 |
|
|
486
|
+
| `getGroupsOpenInfo(gids, timeout)` | 群 ID 数组 | `profiles` 映射。 |
|
|
487
|
+
| `enterRoom(rid, timeout)` / `leaveRoom(rid, timeout)` | 房间 ID | 空 data。 |
|
|
488
|
+
| `enterRooms(rids, timeout)` | 房间 ID 数组,TLV 最多 100 项 | 空 data。 |
|
|
489
|
+
| `getUserRooms(timeout)` | 无 | 房间 ID 数组 `RTMConfig.Int64[]`。 |
|
|
490
|
+
| `getRoomMembers(rid, timeout)` / `getRoomCount(rids, timeout)` | 房间 ID 或 ID 数组 | `{members}` / `{totals}`。 |
|
|
491
|
+
| `setRoomInfo(rid, oinfo, pinfo, timeout)` | 房间 ID;公共/私有资料字符串 | 空 data。 |
|
|
492
|
+
| `setRoomProfile(rid, publicData, privateData, label, avatar, timeout)` | 扩展写入方法;可同时设置公共/私有资料、房间名称和头像。 | 空 data。 |
|
|
493
|
+
| `getRoomInfo(rid, timeout)` / `getRoomOpenInfo(rid, timeout)` / `getRoomsOpenInfo(rids, timeout)` | 房间 ID 或数组 | 完整资料、单房间公开资料或 `profiles` 映射。 |
|
|
494
|
+
| `getUserRoomsAndLastMessage(mtypes, timeout)` | 可选消息类型数组 | `{last_by_room}`,value 为历史 `tuple8`。 |
|
|
495
|
+
|
|
496
|
+
### 消息发送和单条消息
|
|
497
|
+
|
|
498
|
+
`sendChat`、`sendAudio`、`sendCmd` 分别固定文本、语音、命令消息类型;`sendGroup*`、`sendRoom*` 对应群和房间。发送成功 resolve/callback data 为 `{message_ref, payload: {message_ref, time_ms}}`。
|
|
499
|
+
|
|
500
|
+
TLV v1 的 `sendMessage`、`sendMessages`、`sendGroupMessage`、`sendRoomMessage` 及其快捷方法,失败时 callback 收到 `callback({message_ref, error}, null)`;Promise reject 的也是这个外层对象。协议错误码在内层 `error.code`,因此调用方应读取 `sendError.error.code`,不是 `sendError.code`:
|
|
501
|
+
|
|
502
|
+
```js
|
|
503
|
+
try {
|
|
504
|
+
await client.promises.sendChat(peerUid, 'Hello', '{}');
|
|
505
|
+
} catch (sendError) {
|
|
506
|
+
console.error(sendError.message_ref, sendError.error.code);
|
|
507
|
+
}
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
| API | 参数 |
|
|
511
|
+
| --- | --- |
|
|
512
|
+
| `sendMessage(to, mtype, msg, attrs, mid, timeout)` | 单个接收 UID、消息类型、正文、附加信息、可选消息引用。 |
|
|
513
|
+
| `sendMessages(tos, mtype, msg, attrs, mid, timeout)` | 接收 UID 数组(TLV 最多 100 项),其余同上。 |
|
|
514
|
+
| `sendGroupMessage(gid, mtype, msg, attrs, mid, timeout)` / `sendRoomMessage(rid, mtype, msg, attrs, mid, timeout)` | 群/房间 ID,其余同上。 |
|
|
515
|
+
| `sendChat(to, msg, attrs, mid, timeout)`、`sendAudio(to, msg, attrs, mid, timeout)`、`sendCmd(to, msg, attrs, mid, timeout)` | 私聊快捷方法;省略通用 `mtype`。 |
|
|
516
|
+
| `sendGroupChat(gid, msg, attrs, mid, timeout)`、`sendGroupAudio(gid, msg, attrs, mid, timeout)`、`sendGroupCmd(gid, msg, attrs, mid, timeout)` | 群消息快捷方法。 |
|
|
517
|
+
| `sendRoomChat(rid, msg, attrs, mid, timeout)`、`sendRoomAudio(rid, msg, attrs, mid, timeout)`、`sendRoomCmd(rid, msg, attrs, mid, timeout)` | 房间消息快捷方法。 |
|
|
518
|
+
| `getMessage(from, mid, xid, type, timeout)` / `getChat(...)` | 发送者 UID、消息引用、目标 ID、通道编号;`getChat` 是兼容别名。返回消息对象或空结果。 |
|
|
519
|
+
| `deleteMessage(from, mid, xid, type, timeout)` / `deleteChat(...)` | 同上;`deleteChat` 是兼容别名。成功返回空 data。 |
|
|
520
|
+
|
|
521
|
+
### 历史、翻页与计数
|
|
522
|
+
|
|
523
|
+
`getP2PMessage`、`getGroupMessage`、`getRoomMessage`、`getBroadcastMessage` 参数顺序相同:`(target?, desc, num, begin, end, lastid, mtypes, timeout)`。target 分别为对方 UID、群 ID、房间 ID;广播查询没有 target。
|
|
524
|
+
|
|
525
|
+
| API | 参数变化 / 行为 |
|
|
526
|
+
| --- | --- |
|
|
527
|
+
| `getP2PMessage(ouid, desc, num, begin, end, lastid, mtypes, timeout)` | 私聊历史。 |
|
|
528
|
+
| `getGroupMessage(gid, desc, num, begin, end, lastid, mtypes, timeout)` | 群历史。 |
|
|
529
|
+
| `getRoomMessage(rid, desc, num, begin, end, lastid, mtypes, timeout)` | 房间历史。 |
|
|
530
|
+
| `getBroadcastMessage(desc, num, begin, end, lastid, mtypes, timeout)` | 广播历史。 |
|
|
531
|
+
| `getP2PMessageByMessageId(ouid, mid, desc, num, begin, end, mtypes, timeout)` | 私聊历史;以消息引用 `mid` 为锚点定位一页,无 `lastid` 参数。 |
|
|
532
|
+
| `getGroupMessageByMessageId(gid, mid, desc, num, begin, end, mtypes, timeout)` | 群历史锚点查询。 |
|
|
533
|
+
| `getRoomMessageByMessageId(rid, mid, desc, num, begin, end, mtypes, timeout)` | 房间历史锚点查询。 |
|
|
534
|
+
| `getBroadcastMessageByMessageId(mid, desc, num, begin, end, mtypes, timeout)` | 广播历史锚点查询。 |
|
|
535
|
+
| `getP2PChat(ouid, desc, num, begin, end, lastid, timeout)` | 私聊文本、语音、命令历史快捷方法。 |
|
|
536
|
+
| `getGroupChat(gid, desc, num, begin, end, lastid, timeout)` | 群文本、语音、命令历史快捷方法。 |
|
|
537
|
+
| `getRoomChat(rid, desc, num, begin, end, lastid, timeout)` | 房间文本、语音、命令历史快捷方法。 |
|
|
538
|
+
| `getBroadcastChat(desc, num, begin, end, lastid, timeout)` | 广播文本、语音、命令历史快捷方法。 |
|
|
539
|
+
| `getP2PMessageCount(ouid, begin, end, mtypes, timeout)` | 私聊消息数量。 |
|
|
540
|
+
| `getGroupMessageCount(gid, begin, end, mtypes, timeout)` | 群消息数量。 |
|
|
541
|
+
| `getRoomMessageCount(rid, begin, end, mtypes, timeout)` | 房间消息数量。 |
|
|
542
|
+
| `getBroadcastMessageCount(begin, end, mtypes, timeout)` | 广播消息数量。 |
|
|
543
|
+
|
|
544
|
+
TLV v1 历史页返回 `{size, items, next, first_ms, last_ms}`。`items` 每项为 `tuple8`:`[cursor_id, sender_or_direction, kind, message_ref, deleted, payload, extra, time_ms]`。`cursor_id` 是不透明翻页游标,不是 `message_ref`;将 `next` 原样传回 `lastid`。Anchor 查询的 `mid` 才是消息引用。时间字段用毫秒;不要用返回的 `cursor_id` 当时间戳或消息 ID。
|
|
545
|
+
|
|
546
|
+
私聊历史翻页示例:假设 `client` 已登录、`peerUid` 是要查询的对方 UID,并且第一页确有后续页。首次查询使用 `lastid = 0`;下一次调用把第一页的 `next` 原样传回:
|
|
547
|
+
|
|
548
|
+
```js
|
|
549
|
+
const rtm = window.rtm;
|
|
550
|
+
|
|
551
|
+
async function getDirectPage(client, peerUid, cursor) {
|
|
552
|
+
return client.promises.getP2PMessage(
|
|
553
|
+
peerUid, false, 20, 0, 0, cursor, [rtm.RTMConfig.CHAT_TYPE.text], 12000,
|
|
554
|
+
);
|
|
555
|
+
}
|
|
556
|
+
|
|
557
|
+
async function readTwoDirectPages(client, peerUid) {
|
|
558
|
+
const firstPage = await getDirectPage(client, peerUid, 0);
|
|
559
|
+
// 此示例假设第一页有后续页;实际 UI 仅在 Gate 给出可用 continuation 时调用。
|
|
560
|
+
const nextPage = await getDirectPage(client, peerUid, firstPage.next);
|
|
561
|
+
return [firstPage, nextPage];
|
|
562
|
+
}
|
|
563
|
+
```
|
|
564
|
+
|
|
565
|
+
### 未读、会话与 Push
|
|
566
|
+
|
|
567
|
+
| API | 参数 | TLV v1 成功返回 / 用途 |
|
|
568
|
+
| --- | --- | --- |
|
|
569
|
+
| `getUnreadMessage(clear, withLogout, timeout)` | 两个布尔参数可选;`clear` 默认 false,表示是否标记已读;`withLogout` 请求附带登出时间 | `{peers, group_refs, logout_sec?}`。 |
|
|
570
|
+
| `getP2PUnreadMessageNum(uids, mtime, mtypes, timeout)` / `getGroupUnreadMessageNum(gids, mtime, mtypes, timeout)` | ID 数组;可选起始毫秒和消息类型过滤 | `{counts, times}`。 |
|
|
571
|
+
| `cleanUnreadMessage(timeout)` | 无 | 清理未读状态,返回空 data。 |
|
|
572
|
+
| `setSessionRead(category, xid, readSeq, timeout)` | 会话通道编号、目标 ID、已读序号上界 | 设置会话已读位置,返回空 data。 |
|
|
573
|
+
| `getSession(timeout)` | 无 | `{peers, group_refs}` 会话 ID 集合。 |
|
|
574
|
+
| `removeSession(to, localOnly, timeout)` | 对方 UID;`localOnly` 默认 false | 删除会话,返回空 data。 |
|
|
575
|
+
| `getP2PConversationList(mtime, mtypes, timeout)` / `getP2PUnreadConversationList(mtime, mtypes, timeout)` | 可选毫秒筛选起点和消息类型 | `{peers, badges, last_items}`。 |
|
|
576
|
+
| `getGroupConversationList(mtime, mtypes, timeout)` / `getGroupUnreadConversationList(mtime, mtypes, timeout)` | 同上 | `{group_refs, badges, last_items}`。 |
|
|
577
|
+
| `getUnreadConversationList(clear, mtime, mtypes, timeout)` | `clear` 默认 false;可选筛选 | 合并私聊与群的 `peers/group_refs`、未读数和最后消息字段。 |
|
|
578
|
+
|
|
579
|
+
Push 用 `client.processor.on(name, callback)` 订阅:`RTMConfig.TLV_SERVER_PUSH.recvMessage`、`recvGroupMessage`、`recvRoomMessage`、`recvBroadcastMessage`、`kickOut`、`kickOutRoom`。各事件字段见[Push 契约](TLV_CONTRACT.md#控制-uri-与-push)。
|
|
580
|
+
|
|
581
|
+
### 文本服务
|
|
582
|
+
|
|
583
|
+
| API | 参数 | TLV v1 能力 |
|
|
584
|
+
| --- | --- | --- |
|
|
585
|
+
| `textCheck(text, strategyId, timeout)` | 待审核文本、可选策略 ID | 支持;返回审核 decision、filtered 文本、识别语言及命中信息。 |
|
|
586
|
+
| `translate(originalMessage, originalLanguage, targetLanguage, type, profanity, timeout)` | 原文、可选源语言、目标语言、格式类型、过滤方式 | 支持;具体值域和返回字段见 TLV 契约。 |
|
|
587
|
+
|
|
588
|
+
## 6. TLV v1 API 支持矩阵
|
|
589
|
+
|
|
590
|
+
以下“支持”表示 SDK 有 TLV v1 URI 和字段契约,不代表当前 Gate 项目一定开通对应服务权限。旧 API 名称仍存在于 JavaScript 类中,不表示 TLV Gate 支持它。
|
|
591
|
+
|
|
592
|
+
| 功能 | TLV v1 API | TLV v1 | SharedWorker | 边界 / 替代方式 |
|
|
593
|
+
| --- | --- | --- | --- | --- |
|
|
594
|
+
| 登录、连接与系统 | `login`、`bye`、`getServerTime`、`addAttrs`、`getAttrs`、`addDebugLog`、重连与 Push 事件 | 支持 | 支持 | SharedWorker 支持 TLV 与显式选择的 FPNN;本表 SharedWorker 列描述 TLV 模式。 |
|
|
595
|
+
| 用户、资料与在线状态 | `getOnlineUsers`、`setUserInfo`、`getUserInfo`、`getUserOpenInfo`、`setTranslationLanguage` | 支持 | 支持 | 用户可见资料的权限由 Gate 项目控制。 |
|
|
596
|
+
| 用户存储与黑名单 | `dataSet`、`dataGet`、`dataDelete`、`addBlacks`、`deleteBlacks`、`getBlacks` | 支持 | 支持 | TLV 黑名单批量每次最多 100 个 UID。 |
|
|
597
|
+
| 群组 | `addGroupMembers`、`deleteGroupMembers`、`getGroupMembers`、`getGroupCount`、`getUserGroups`、`setGroupInfo`、`getGroupInfo`、`getGroupOpenInfo`、`getGroupsOpenInfo` | 支持 | 支持 | 服务端权限和群组存在状态仍由 Gate 校验。 |
|
|
598
|
+
| 房间 | `enterRoom`、`enterRooms`、`leaveRoom`、`getUserRooms`、`getUserRoomsAndLastMessage`、`getRoomMembers`、`getRoomCount`、资料读写 API | 支持 | 支持 | `enterRooms` 批量最多 100 个房间 ID。 |
|
|
599
|
+
| 消息发送和 Push | 私聊、群、房间、批量私聊发送 API;direct/group/room/broadcast Push | 支持 | 支持 | `sendMessages` 每次最多 100 个 UID;可靠 Push 自动 ACK 和去重。 |
|
|
600
|
+
| 历史、单条消息和计数 | `get*Message`、`get*MessageByMessageId`、`get*MessageCount`、`getMessage`、`deleteMessage` 及 Chat 别名 | 支持 | 支持 | 翻页 cursor 和消息引用是不同 ID;详见参数与返回约定。 |
|
|
601
|
+
| 未读与会话 | 未读数、会话列表、标记已读、删除会话 API | 支持 | 支持 | 不包含 SDK 外业务系统的未读规则和持久化 UI 状态。 |
|
|
602
|
+
| 文本审核与翻译 | `textCheck`、`translate` | 支持 | 支持 | 依赖 Gate 项目服务配置与权限。 |
|
|
603
|
+
| 文件消息 | `fileToken`、`sendFile`、`sendGroupFile`、`sendRoomFile` | 不支持 | 不支持 | TLV v1 Client port 未开放;需使用 FPNN 兼容入口或业务侧上传/转发方案。 |
|
|
604
|
+
| 好友关系 | `addFriends`、`deleteFriends`、`getFriends` | 不支持 | 不支持 | TLV v1 未开放。 |
|
|
605
|
+
| 设备 Push 设置 | `addDevice`、`removeDevice`、`addDevicePushOption`、`removeDevicePushOption`、`getDevicePushOption` | 不支持 | 不支持 | TLV v1 未开放。 |
|
|
606
|
+
| 增值与多媒体审核 | `profanity`、`imageCheck`、`audioCheck`、`videoCheck`、`speech2Text` | 不支持 | 不支持 | TLV v1 未开放;`textCheck` 和 `translate` 不在此限制内。 |
|
|
607
|
+
|
|
608
|
+
TLV 不支持的调用按实现分为三类:
|
|
609
|
+
|
|
610
|
+
- TLV 合约中保留、但没有 Client API 路由的 wire(如 `filetoken`、`addfriends`、`acheck`)返回 `200020`(`RTM_EC_FORBIDDEN_METHOD`)。
|
|
611
|
+
- 未登记且非保留的 wire 返回 `20004`(`RTM_EC_UNKNOWN_METHOD`)。
|
|
612
|
+
- 共享客户端原样转发 SDK 请求及结果。TLV 文件发送由底层 `filetoken` 的契约校验拒绝;callback 收到 `{mid, error}`,其中 `error.code` 为 `200020`,Promise 版本 reject 同一对象。
|
|
613
|
+
|
|
614
|
+
这些错误都不会自动切换到 FPNN。SharedWorker 的 TLV 模式复用 TLV 支持范围;FPNN 模式可转发其兼容业务 API,包括文件发送。通过 `createClient()` 使用函数型配置会自动选择页面内 `RTMClient`;直接构造 `RTMSharedWorkerClient` 时,`clientOptions` 必须可安全传递给 Worker。FPNN 兼容能力列表见[能力总览](CAPABILITIES.md),服务端支持仍需单独确认。
|
|
615
|
+
|
|
616
|
+
## 7. 调试与参考
|
|
617
|
+
|
|
618
|
+
- `requestMetadata` 可为请求附加 `trace`、`sent_ms` 以关联服务端日志,不要放 credential、项目 SecretKey 或个人敏感数据。
|
|
619
|
+
- `ErrorRecorder` 观察连接、协议、重连和登录错误;普通 API 错误通过该 API 的 callback / Promise 返回。
|
|
620
|
+
- [能力总览与业务流程](CAPABILITIES.md)
|
|
621
|
+
- [FPNN 与 TLV v1 迁移对照](PROTOCOL_MIGRATION.md)
|
|
622
|
+
- [TLV v1 URI、参数类型与返回字段](TLV_CONTRACT.md)
|
|
623
|
+
- [TLV v1 frame 与传输规则](TLV.md)
|
|
624
|
+
- [TypeScript API 声明](../dist/rtm.d.ts)
|