@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/Messages.md
ADDED
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
# RTM Client Websocket SDK Message 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
|
+
* `sendMessage(to, mtype, msg, attrs, mid, timeout, callback)`: 发送消息
|
|
12
|
+
* `to`: **(Required | Int64)** 接收方uid
|
|
13
|
+
* `mtype`: **(Required | number)** 消息类型
|
|
14
|
+
* `msg`: **(Required | string)** 消息内容
|
|
15
|
+
* `attrs`: **(Required | string)** 消息附加信息, 没有可传`''`
|
|
16
|
+
* `mid`: **(Optional | Int64)** 消息 id, 用于过滤重复消息, 非重发时为`Int64(0)`
|
|
17
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
18
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
19
|
+
* `err`: **(object[mid:Int64, error:Error])**
|
|
20
|
+
* `data`: **(object[mid:Int64, payload:object[mtime:Int64]])**
|
|
21
|
+
|
|
22
|
+
* `sendGroupMessage(gid, mtype, msg, attrs, mid, timeout, callback)`: 发送group消息
|
|
23
|
+
* `gid`: **(Required | Int64)** group id
|
|
24
|
+
* `mtype`: **(Required | number)** 消息类型
|
|
25
|
+
* `msg`: **(Required | string)** 消息内容
|
|
26
|
+
* `attrs`: **(Required | string)** 消息附加信息, 可传`''`
|
|
27
|
+
* `mid`: **(Optional | Int64)** 消息 id, 用于过滤重复消息, 非重发时为`Int64(0)`
|
|
28
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
29
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
30
|
+
* `err`: **(object[mid:Int64, error:Error])**
|
|
31
|
+
* `data`: **(object[mid:Int64, payload:object[mtime:Int64]])**
|
|
32
|
+
|
|
33
|
+
* `sendRoomMessage(rid, mtype, msg, attrs, mid, timeout, callback)`: 发送room消息
|
|
34
|
+
* `rid`: **(Required | Int64)** room id
|
|
35
|
+
* `mtype`: **(Required | number)** 消息类型
|
|
36
|
+
* `msg`: **(Required | string)** 消息内容
|
|
37
|
+
* `attrs`: **(Required | string)** 消息附加信息, 可传`''`
|
|
38
|
+
* `mid`: **(Optional | Int64)** 消息 id, 用于过滤重复消息, 非重发时为`Int64(0)`
|
|
39
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
40
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
41
|
+
* `err`: **(object[mid:Int64, error:Error])**
|
|
42
|
+
* `data`: **(object[mid:Int64, payload:object[mtime:Int64]])**
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
* `getUnreadMessage(clear, withLogout, timeout, callback)`: 检测未读消息数目;旧调用 `getUnreadMessage(clear, timeout, callback)` 仍兼容。
|
|
47
|
+
* `clear`: **(Optional | bool)** 是否除离线提醒
|
|
48
|
+
* `withLogout`: **(Optional | bool)** 是否返回登出时间
|
|
49
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
50
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
51
|
+
* `err`: **(Error)**
|
|
52
|
+
* `data`: **(object[p2p:array(Int64), group:array(Int64)])** 对应值为未读消息数目
|
|
53
|
+
|
|
54
|
+
* `cleanUnreadMessage(timeout, callback)`: 清除未读消息
|
|
55
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
56
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
57
|
+
* `err`: **(Error)**
|
|
58
|
+
* `data`: **(object)**
|
|
59
|
+
|
|
60
|
+
* `getP2PUnreadMessageNum(uids, mtime, mtypes, timeout, callback)`: 获取未读P2P消息数目
|
|
61
|
+
* `uids`: **(Required | [int64])** uid列表
|
|
62
|
+
* `mtime`: **(Required | int64)** 毫秒级时间戳,获取这个时间戳之后的未读消息,如果mtime 为空,则获取上一次logout后的未读消息
|
|
63
|
+
* `mtypes`: **(Required | [number])** 获取指定mtype的未读消息,为空或undefined,则获取聊天相关未读消息
|
|
64
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
65
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
66
|
+
* `err`: **(Error)**
|
|
67
|
+
* `data`:
|
|
68
|
+
* `p2p` : **({ uid => num})**
|
|
69
|
+
* `ltime` : **({ session_id => time})** 每个session的的最新一条消息时间
|
|
70
|
+
|
|
71
|
+
* `getGroupUnreadMessageNum(gids, mtime, mtypes, timeout, callback)`: 获取未读Group消息数目
|
|
72
|
+
* `gids`: **(Required | [int64])** gid列表
|
|
73
|
+
* `mtime`: **(Required | int64)** 毫秒级时间戳,获取这个时间戳之后的未读消息,如果mtime 为空,则获取上一次logout后的未读消息
|
|
74
|
+
* `mtypes`: **(Required | [number])** 获取指定mtype的未读消息,为空或undefined,则获取聊天相关未读消息
|
|
75
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
76
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
77
|
+
* `err`: **(Error)**
|
|
78
|
+
* `data`:
|
|
79
|
+
* `group` : **({ gid => num})**
|
|
80
|
+
* `ltime` : **({ session_id => time})** 每个session的的最新一条消息时间
|
|
81
|
+
|
|
82
|
+
* `getGroupMessage(gid, desc, num, begin, end, lastid, mtypes, timeout, callback)`: 获取Group历史消息
|
|
83
|
+
* `gid`: **(Required | Int64)** Group id
|
|
84
|
+
* `desc`: **(Required | bool)** `true`: 则从`end`的时间戳开始倒序翻页, `false`: 则从`begin`的时间戳顺序翻页
|
|
85
|
+
* `num`: **(Required | number)** 获取数量, **一次最多获取20条, 建议10条**
|
|
86
|
+
* `begin`: **(Optional | Int64)** 开始时间戳, 毫秒, 默认`0`, 条件:`>=`
|
|
87
|
+
* `end`: **(Optional | Int64)** 结束时间戳, 毫秒, 默认`0`, 条件:`<=`
|
|
88
|
+
* `lastid`: **(Optional | Int64)** 最后一条消息的id, 第一次默认传`0`, 条件:`> or <`
|
|
89
|
+
* `mtypes`: **(Optional | array(number))** 获取哪些mtype的历史
|
|
90
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
91
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
92
|
+
* `err`: **(Error)**
|
|
93
|
+
* `data`: **(object[num:number, lastid:Int64, begin:Int64, end:Int64, msgs:array[GroupMsg]])**
|
|
94
|
+
* `GroupMsg.id` **(Int64)**
|
|
95
|
+
* `GroupMsg.from` **(Int64)**
|
|
96
|
+
* `GroupMsg.mtype` **(number)**
|
|
97
|
+
* `GroupMsg.mid` **(Int64)**
|
|
98
|
+
* `GroupMsg.deleted` **(bool)**
|
|
99
|
+
* `GroupMsg.msg` **(string)**
|
|
100
|
+
* `GroupMsg.attrs` **(string)**
|
|
101
|
+
* `GroupMsg.mtime` **(Int64)**
|
|
102
|
+
|
|
103
|
+
* `getRoomMessage(rid, desc, num, begin, end, lastid, mtypes, timeout, callback)`: 获取Room历史消息
|
|
104
|
+
* `rid`: **(Required | Int64)** Room id
|
|
105
|
+
* `desc`: **(Required | bool)** `true`: 则从`end`的时间戳开始倒序翻页, `false`: 则从`begin`的时间戳顺序翻页
|
|
106
|
+
* `num`: **(Required | number)** 获取数量, **一次最多获取20条, 建议10条**
|
|
107
|
+
* `begin`: **(Optional | Int64)** 开始时间戳, 毫秒, 默认`0`, 条件:`>=`
|
|
108
|
+
* `end`: **(Optional | Int64)** 结束时间戳, 毫秒, 默认`0`, 条件:`<=`
|
|
109
|
+
* `lastid`: **(Optional | Int64)** 最后一条消息的id, 第一次默认传`0`, 条件:`> or <`
|
|
110
|
+
* `mtypes`: **(Optional | array(number))** 获取哪些mtype的历史
|
|
111
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
112
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
113
|
+
* `err`: **(Error)**
|
|
114
|
+
* `data`: **(object[num:number, lastid:Int64, begin:Int64, end:Int64, msgs:array[RoomMsg]])**
|
|
115
|
+
* `RoomMsg.id` **(Int64)**
|
|
116
|
+
* `RoomMsg.from` **(Int64)**
|
|
117
|
+
* `RoomMsg.mtype` **(number)**
|
|
118
|
+
* `RoomMsg.mid` **(Int64)**
|
|
119
|
+
* `RoomMsg.deleted` **(bool)**
|
|
120
|
+
* `RoomMsg.msg` **(string)**
|
|
121
|
+
* `RoomMsg.attrs` **(string)**
|
|
122
|
+
* `RoomMsg.mtime` **(Int64)**
|
|
123
|
+
|
|
124
|
+
* `getBroadcastMessage(desc, num, begin, end, lastid, mtypes, timeout, callback)`: 获取广播历史消息
|
|
125
|
+
* `desc`: **(Required | bool)** `true`: 则从`end`的时间戳开始倒序翻页, `false`: 则从`begin`的时间戳顺序翻页
|
|
126
|
+
* `num`: **(Required | number)** 获取数量, **一次最多获取20条, 建议10条**
|
|
127
|
+
* `begin`: **(Optional | Int64)** 开始时间戳, 毫秒, 默认`0`, 条件:`>=`
|
|
128
|
+
* `end`: **(Optional | Int64)** 结束时间戳, 毫秒, 默认`0`, 条件:`<=`
|
|
129
|
+
* `lastid`: **(Optional | Int64)** 最后一条消息的id, 第一次默认传`0`, 条件:`> or <`
|
|
130
|
+
* `mtypes`: **(Optional | array(number))** 获取哪些mtype的历史
|
|
131
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
132
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
133
|
+
* `err`: **(Error)**
|
|
134
|
+
* `data`: **(object[num:number, lastid:Int64, begin:Int64, end:Int64, msgs:array[BroadcastMsg]])**
|
|
135
|
+
* `BroadcastMsg.id` **(Int64)**
|
|
136
|
+
* `BroadcastMsg.from` **(Int64)**
|
|
137
|
+
* `BroadcastMsg.mtype` **(number)**
|
|
138
|
+
* `BroadcastMsg.mid` **(Int64)**
|
|
139
|
+
* `BroadcastMsg.deleted` **(bool)**
|
|
140
|
+
* `BroadcastMsg.msg` **(string)**
|
|
141
|
+
* `BroadcastMsg.attrs` **(string)**
|
|
142
|
+
* `BroadcastMsg.mtime` **(Int64)**
|
|
143
|
+
|
|
144
|
+
* `getP2PMessage(ouid, desc, num, begin, end, lastid, mtypes, timeout, callback)`: 获取P2P历史消息
|
|
145
|
+
* `ouid`: **(Required | Int64)** 获取和哪个用户id的历史消息
|
|
146
|
+
* `desc`: **(Required | bool)** `true`: 则从`end`的时间戳开始倒序翻页, `false`: 则从`begin`的时间戳顺序翻页
|
|
147
|
+
* `num`: **(Required | number)** 获取数量, **一次最多获取20条, 建议10条**
|
|
148
|
+
* `begin`: **(Optional | Int64)** 开始时间戳, 毫秒, 默认`0`, 条件:`>=`
|
|
149
|
+
* `end`: **(Optional | Int64)** 结束时间戳, 毫秒, 默认`0`, 条件:`<=`
|
|
150
|
+
* `lastid`: **(Optional | Int64)** 最后一条消息的id, 第一次默认传`0`, 条件:`> or <`
|
|
151
|
+
* `mtypes`: **(Optional | array(number))** 获取哪些mtype的历史
|
|
152
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
153
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
154
|
+
* `err`: **(Error)**
|
|
155
|
+
* `data`: **(object[num:number, lastid:Int64, begin:Int64, end:Int64, msgs:array[P2PMsg]])**
|
|
156
|
+
* `P2PMsg.id` **(Int64)**
|
|
157
|
+
* `P2PMsg.direction` **(number)**
|
|
158
|
+
* `P2PMsg.mtype` **(number)**
|
|
159
|
+
* `P2PMsg.mid` **(Int64)**
|
|
160
|
+
* `P2PMsg.deleted` **(bool)**
|
|
161
|
+
* `P2PMsg.msg` **(string)**
|
|
162
|
+
* `P2PMsg.attrs` **(string)**
|
|
163
|
+
* `P2PMsg.mtime` **(Int64)**
|
|
164
|
+
|
|
165
|
+
* `getMessage(frrom, mid, xid, type, timeout, callback)`: 获取消息
|
|
166
|
+
* `from`: **(Required | Int64)** 发送者用户 id
|
|
167
|
+
* `mid`: **(Required | Int64)** 消息 id
|
|
168
|
+
* `xid`: **(Required | Int64)** 消息接收方 id (userId/RoomId/GroupId)
|
|
169
|
+
* `type`: **(Required | number)** 接收方类型 (1:p2p, 2:group, 3:room)
|
|
170
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
171
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
172
|
+
* `err`: **(Error)**
|
|
173
|
+
* `data`: **(object[id: Int64, mtype: number, msg: string, attrs: string, mtime: Int64])**
|
|
174
|
+
|
|
175
|
+
* `deleteMessage(from, mid, xid, type, timeout, callback)`: 删除消息
|
|
176
|
+
* `from`: **(Required | Int64)** 发送者用户 id
|
|
177
|
+
* `mid`: **(Required | Int64)** 消息 id
|
|
178
|
+
* `xid`: **(Required | Int64)** 消息接收方 id (userId/RoomId/GroupId)
|
|
179
|
+
* `type`: **(Required | number)** 接收方类型 (1:p2p, 2:group, 3:room)
|
|
180
|
+
* `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
|
|
181
|
+
* `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
|
|
182
|
+
* `err`: **(Error)**
|
|
183
|
+
* `data`: **(object)**
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
# FPNN 与 TLV v1 协议迁移对照
|
|
2
|
+
|
|
3
|
+
本文说明如何在现有 `RTMClient` 接入中选择 FPNN 或 TLV v1,并对照 SDK 业务 API、旧 FPNN wire method 与 TLV URI。
|
|
4
|
+
|
|
5
|
+
## 先看结论
|
|
6
|
+
|
|
7
|
+
- `RTMClient` 是两种协议共用的业务 API 门面。TLV v1 已实现的接口由 SDK 在内部把旧 method 和字段转换成 TLV URI 与字段;业务代码不需要自己发送 TLV frame,也不应直接调用这些 wire 名称。
|
|
8
|
+
- 协议在创建客户端时选择:`protocol: 'fpnn'` 或 `protocol: 'tlv-v1'`。一个客户端实例不会按请求混用两种协议。
|
|
9
|
+
- 业务 API 名称和调用方式在支持范围内保持一致,但这不保证每个返回对象、错误对象、服务端权限或业务语义都完全相同。切换前请对照本页的差异说明和 [TLV v1 Client API 契约](TLV_CONTRACT.md)。
|
|
10
|
+
- TLV v1 未支持的 FPNN API 不会自动回退到 FPNN。完整支持边界见 [接入指南的支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵)。
|
|
11
|
+
|
|
12
|
+
## 选择协议
|
|
13
|
+
|
|
14
|
+
现有 FPNN 客户端通常使用 `endpoint`(FPNN Gate 地址)创建。继续使用旧 `RTMClient` 构造器时,省略协议仍默认 FPNN。迁移到新工厂 `createClient()` 时,省略协议同样默认 FPNN;浏览器支持 SharedWorker 时工厂自动共享,不支持时自动使用独立连接:
|
|
15
|
+
|
|
16
|
+
```js
|
|
17
|
+
const client = rtm.createClient({
|
|
18
|
+
pid,
|
|
19
|
+
endpoint: fpnnEndpoint,
|
|
20
|
+
});
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
若业务必须保持每个页面独立连接,可改用 `rtm.createClient({ sharing: false, pid, endpoint: fpnnEndpoint })`;浏览器缺少 SharedWorker 时,`createClient()` 也会自动使用独立连接。若希望新项目显式使用 TLV v1,则设置 `protocol: 'tlv-v1'` 并提供完整 `tlvEndpoint`。
|
|
24
|
+
|
|
25
|
+
迁移到 TLV v1 时,将连接地址换成部署方提供的完整 WebSocket URL,并在创建时选择 TLV:
|
|
26
|
+
|
|
27
|
+
```js
|
|
28
|
+
const client = new rtm.RTMClient({
|
|
29
|
+
protocol: 'tlv-v1',
|
|
30
|
+
pid,
|
|
31
|
+
tlvEndpoint: 'wss://<gate-host>/service/websocket',
|
|
32
|
+
autoReconnect: true,
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
await client.promises.login(uid, credential);
|
|
36
|
+
await client.promises.sendChat(peerUid, 'hello', '{}');
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`credential` 仍须由业务服务端或受控签发工具为当前 UID 签发。不要把项目 `SecretKey` 放入浏览器。其余连接、登录、发送、监听 Push 的业务调用可以继续使用同一套 `RTMClient` API;`RTMSharedWorkerClient` 和 `createClient()` 省略协议时均默认 FPNN,显式设置 `protocol: 'tlv-v1'` 才使用 TLV。SharedWorker 配置和能力边界见 [FPNN 多窗口接入](USAGE.md#fpnn-多窗口接入)。
|
|
40
|
+
|
|
41
|
+
## API 与 wire 名称对照
|
|
42
|
+
|
|
43
|
+
“FPNN method”列是 SDK 内部兼容接口使用的旧请求 method 名称,用于帮助查旧 FPNN 文档和服务端日志。它不是 TLV 请求名,也不是建议业务直接调用的 API。TLV 连接实际发送右侧的 URI。
|
|
44
|
+
|
|
45
|
+
### 连接、用户与存储
|
|
46
|
+
|
|
47
|
+
| RTMClient 业务 API | FPNN method | TLV v1 URI |
|
|
48
|
+
| --- | --- | --- |
|
|
49
|
+
| `login` | `auth` | `auth.login` |
|
|
50
|
+
| `bye` | `bye` | `connection.close` |
|
|
51
|
+
| `getServerTime` | `getservertime` | `system.time` |
|
|
52
|
+
| `addAttrs` / `getAttrs` | `addattrs` / `getattrs` | `connection.set_props` / `connection.get_props` |
|
|
53
|
+
| `addDebugLog` | `adddebuglog` | `system.debug` |
|
|
54
|
+
| `getOnlineUsers` | `getonlineusers` | `presence.online` |
|
|
55
|
+
| `setUserInfo` / `getUserInfo` | `setuserinfo` / `getuserinfo` | `user.set_profile` / `user.get_profile` |
|
|
56
|
+
| `getUserOpenInfo` | `getuseropeninfo` | `user.get_public` |
|
|
57
|
+
| `setTranslationLanguage` | `setlang` | `user.set_locale` |
|
|
58
|
+
| `dataGet` / `dataSet` / `dataDelete` | `dataget` / `dataset` / `datadel` | `storage.get` / `storage.set` / `storage.delete` |
|
|
59
|
+
| `addBlacks` / `deleteBlacks` / `getBlacks` | `addblacks` / `delblacks` / `getblacks` | `blacklist.add` / `blacklist.remove` / `blacklist.list` |
|
|
60
|
+
|
|
61
|
+
### 群组与房间
|
|
62
|
+
|
|
63
|
+
| RTMClient 业务 API | FPNN method | TLV v1 URI |
|
|
64
|
+
| --- | --- | --- |
|
|
65
|
+
| `addGroupMembers` / `deleteGroupMembers` | `addgroupmembers` / `delgroupmembers` | `group.add` / `group.remove` |
|
|
66
|
+
| `getGroupMembers` / `getGroupCount` | `getgroupmembers` / `getgroupcount` | `group.members` / `group.count` |
|
|
67
|
+
| `getUserGroups` | `getusergroups` | `group.joined` |
|
|
68
|
+
| `setGroupInfo` / `getGroupInfo` | `setgroupinfo` / `getgroupinfo` | `group.set_profile` / `group.get_profile` |
|
|
69
|
+
| `getGroupOpenInfo` / `getGroupsOpenInfo` | `getgroupopeninfo` / `getgroupsopeninfo` | `group.get_public` / `group.get_public_batch` |
|
|
70
|
+
| `enterRoom` / `leaveRoom` / `enterRooms` | `enterroom` / `leaveroom` / `enterrooms` | `room.join` / `room.leave` / `room.join_batch` |
|
|
71
|
+
| `getUserRooms` / `getRoomMembers` / `getRoomCount` | `getuserrooms` / `getroommembers` / `getroomcount` | `room.joined` / `room.members` / `room.counts` |
|
|
72
|
+
| `setRoomInfo` / `setRoomProfile` | `setroominfo` | `room.set_profile` |
|
|
73
|
+
| `getRoomInfo` / `getRoomOpenInfo` / `getRoomsOpenInfo` | `getroominfo` / `getroomopeninfo` / `getroomsopeninfo` | `room.get_profile` / `room.get_public` / `room.get_public_batch` |
|
|
74
|
+
| `getUserRoomsAndLastMessage` | `getuserroomsandlastmsg` | `room.last_messages` |
|
|
75
|
+
|
|
76
|
+
### 消息、审核、翻译与历史
|
|
77
|
+
|
|
78
|
+
| RTMClient 业务 API | FPNN method | TLV v1 URI |
|
|
79
|
+
| --- | --- | --- |
|
|
80
|
+
| `sendMessage`、`sendChat`、`sendAudio`、`sendCmd` | `sendmsg` | `message.send` |
|
|
81
|
+
| `sendMessages` | `sendmsgs` | `message.send_batch` |
|
|
82
|
+
| `sendGroupMessage`、`sendGroupChat`、`sendGroupAudio`、`sendGroupCmd` | `sendgroupmsg` | `message.send_group` |
|
|
83
|
+
| `sendRoomMessage`、`sendRoomChat`、`sendRoomAudio`、`sendRoomCmd` | `sendroommsg` | `message.send_room` |
|
|
84
|
+
| `textCheck` | `tcheck` | `moderation.check` |
|
|
85
|
+
| `translate` | `translate` | `translation.run` |
|
|
86
|
+
| `getP2PMessage` / `getP2PChat` | `getp2pmsg` | `history.direct` |
|
|
87
|
+
| `getGroupMessage` / `getGroupChat` | `getgroupmsg` | `history.group` |
|
|
88
|
+
| `getRoomMessage` / `getRoomChat` | `getroommsg` | `history.room` |
|
|
89
|
+
| `getBroadcastMessage` / `getBroadcastChat` | `getbroadcastmsg` | `history.broadcast` |
|
|
90
|
+
| `getP2PMessageByMessageId` / `getGroupMessageByMessageId` | `getp2pmsgbymessageid` / `getgroupmsgbymessageid` | `history.direct_anchor` / `history.group_anchor` |
|
|
91
|
+
| `getRoomMessageByMessageId` / `getBroadcastMessageByMessageId` | `getroommsgbymessageid` / `getbroadcastmsgbymessageid` | `history.room_anchor` / `history.broadcast_anchor` |
|
|
92
|
+
| `getP2PMessageCount` / `getGroupMessageCount` | `getp2pmsgcount` / `getgroupmsgcount` | `history.direct_count` / `history.group_count` |
|
|
93
|
+
| `getRoomMessageCount` / `getBroadcastMessageCount` | `getroommsgcount` / `getbroadcastmsgcount` | `history.room_count` / `history.broadcast_count` |
|
|
94
|
+
| `getMessage` / `getChat` | `getmsg` | `message.get` |
|
|
95
|
+
| `deleteMessage` / `deleteChat` | `delmsg` | `message.revoke` |
|
|
96
|
+
|
|
97
|
+
### 未读、会话与会话列表
|
|
98
|
+
|
|
99
|
+
| RTMClient 业务 API | FPNN method | TLV v1 URI |
|
|
100
|
+
| --- | --- | --- |
|
|
101
|
+
| `getUnreadMessage` | `getunread` | `unread.summary` |
|
|
102
|
+
| `getSession` | `getsession` | `session.list` |
|
|
103
|
+
| `cleanUnreadMessage` | `cleanunread` | `unread.clear` |
|
|
104
|
+
| `setSessionRead` | `setsessionread` | `session.read` |
|
|
105
|
+
| `getP2PUnreadMessageNum` / `getGroupUnreadMessageNum` | `getp2punread` / `getgroupunread` | `unread.direct` / `unread.group` |
|
|
106
|
+
| `removeSession` | `removesession` | `session.remove` |
|
|
107
|
+
| `getP2PConversationList` / `getP2PUnreadConversationList` | `getp2pconversationlist` / `getp2punreadconversationlist` | `conversation.direct` / `conversation.direct_unread` |
|
|
108
|
+
| `getGroupConversationList` / `getGroupUnreadConversationList` | `getgroupconversationlist` / `getgroupunreadconversationlist` | `conversation.group` / `conversation.group_unread` |
|
|
109
|
+
| `getUnreadConversationList` | `getunreadconversationlist` | `conversation.unread` |
|
|
110
|
+
|
|
111
|
+
### 服务端 Push 事件
|
|
112
|
+
|
|
113
|
+
两种协议的 Push 名称和字段也不同。按所选协议使用对应的 `RTMConfig` 常量订阅;不要把常量的字符串值写死在业务代码里。
|
|
114
|
+
|
|
115
|
+
| Push 场景 | FPNN 事件名 | TLV v1 事件名 | TLV 常量 |
|
|
116
|
+
| --- | --- | --- | --- |
|
|
117
|
+
| 一对一消息 | `pushmsg` | `event.direct` | `RTMConfig.TLV_SERVER_PUSH.recvMessage` |
|
|
118
|
+
| 群组消息 | `pushgroupmsg` | `event.group` | `RTMConfig.TLV_SERVER_PUSH.recvGroupMessage` |
|
|
119
|
+
| 房间消息 | `pushroommsg` | `event.room` | `RTMConfig.TLV_SERVER_PUSH.recvRoomMessage` |
|
|
120
|
+
| 广播消息 | `pushbroadcastmsg` | `event.broadcast` | `RTMConfig.TLV_SERVER_PUSH.recvBroadcastMessage` |
|
|
121
|
+
| 当前账号被踢下线 | `kickout` | `event.kicked` | `RTMConfig.TLV_SERVER_PUSH.kickOut` |
|
|
122
|
+
| 从房间移除 | `kickoutroom` | `event.room_removed` | `RTMConfig.TLV_SERVER_PUSH.kickOutRoom` |
|
|
123
|
+
|
|
124
|
+
## 切换时要核对的差异
|
|
125
|
+
|
|
126
|
+
### 参数与返回字段
|
|
127
|
+
|
|
128
|
+
TLV URI 使用自己的字段名和 schema。例如 FPNN `sendmsg` 的 `to / mid / mtype / msg / attrs` 在 TLV `message.send` 中映射为 `recipient / message_ref / kind / payload / extra`;历史查询的 `begin / end / lastid / num / desc` 映射为 `start_ms / end_ms / cursor / limit / reverse`。SDK 执行映射,业务代码仍传 `RTMClient` 方法参数。消息载荷不是完全等价:FPNN MessagePack 可携带对象,而 TLV `payload` 仅接受字符串或二进制;迁移时需要在业务层将对象序列化为 JSON 字符串,或明确编码为二进制。各 URI 的字段、类型、默认值和 Gate Answer 见 [TLV v1 Client API 契约](TLV_CONTRACT.md)。
|
|
129
|
+
|
|
130
|
+
Push 事件也有协议差异:名称见上表,事件字段与 FPNN wire payload 不完全相同。业务侧应依照当前协议订阅并按契约处理事件;不要将 FPNN Push 字段表直接套用到 TLV。FPNN 订阅名见 [事件处理说明](EventProcess.md),TLV Push 字段见 [TLV v1 Client API 契约](TLV_CONTRACT.md#控制-uri-与-push)。
|
|
131
|
+
|
|
132
|
+
### API 支持范围
|
|
133
|
+
|
|
134
|
+
`protocol: 'tlv-v1'` 只覆盖 [TLV v1 支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵)中标为支持的 API。常见未开放项包括文件(`filetoken`、`sendfile` 等)、好友(`addfriends`、`getfriends`)、设备 Push 设置、多媒体审核,以及传统 RTM 房间控制类接口。调用未开放 wire 不会切换到 FPNN:保留但未开放的 wire 会返回 `200020`,未知 wire 会返回 `20004`。共享层转发相同的 SDK 调用:FPNN 文件发送可用,TLV 由底层 SDK 拒绝。错误细节见 [能力总览](CAPABILITIES.md#协议与能力入口) 和支持矩阵。
|
|
135
|
+
|
|
136
|
+
### 登录与错误处理
|
|
137
|
+
|
|
138
|
+
`login` callback 仍按 `(accepted, errorCode)` 判断是否成功;Promise 登录失败会 reject。TLV 的具体鉴权错误码和仅收到拒绝应答时的默认错误码见 [接入指南错误约定](USAGE.md#callbackpromise-与错误)。TLV 消息发送失败的错误对象结构也有专门约定,不要假设所有协议的业务错误都有同一种形状。
|
|
139
|
+
|
|
140
|
+
**发布前应按业务实际使用的 API 做回归验证**:登录/重连、消息收发与 Push、历史分页、未读/会话查询、业务错误处理及服务端权限。成功建立连接不代表 Gate 已开放所有 URI。
|
|
141
|
+
|
|
142
|
+
## 相关文档
|
|
143
|
+
|
|
144
|
+
- [TLV v1 接入指南与 API 参数](USAGE.md)
|
|
145
|
+
- [TLV v1 API、字段与返回值契约](TLV_CONTRACT.md)
|
|
146
|
+
- [SDK 能力与协议边界](CAPABILITIES.md)
|
|
147
|
+
- [FPNN 兼容 API 旧说明](Users.md)、[消息](Messages.md)、[聊天](Chat.md)、[群组](Groups.md)、[房间](Rooms.md)
|
|
148
|
+
- [旧 RTM FPNN 项目迁移到 TLV 的页面契约适配](LEGACY_RTM_TLV_COMPATIBILITY.md)
|
|
@@ -0,0 +1,206 @@
|
|
|
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 固定对照;本 SDK 的对照范围以本包提供的 API 为准。
|
|
6
|
+
|
|
7
|
+
上游源码的包元数据版本为 `1.0.0`。npm 已发布包可能与该 commit 不同;本文不声称 GitHub `master` 与某个 npm tarball 完全一致。如果项目使用 fork、内部构建或 npm 锁定版本,请先核对项目实际运行的源码。
|
|
8
|
+
|
|
9
|
+
逐方法对照结果:该上游基线有 91 个 `RTMClient` 类方法,当前 SDK 有 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
|
+
- 如果要尽量保留上游 RTM FPNN 的方法名、Callback 和 Push 契约,同时把网络协议切到 TLV,请使用 [`legacy-rtm` 兼容迁移指南](LEGACY_RTM_TLV_COMPATIBILITY.md)。该适配由 `createClient()` 的 `compatibility: 'legacy-rtm'` 显式启用;普通 `RTMClient` 不自动转换。
|
|
19
|
+
|
|
20
|
+
### 从本 SDK 旧版升级时的协议默认值变化
|
|
21
|
+
|
|
22
|
+
这项差异不是上游 `RTMClient` 的迁移差异:此前本 SDK 的 `createClient()` 和 `RTMSharedWorkerClient` 在省略协议时默认使用 TLV v1;当前版本统一改为默认 FPNN,以匹配旧 `RTMClient` 的默认协议。若旧代码只提供 `tlvEndpoint` / `tlv_endpoint`、没有写 `protocol`,升级后会因缺少 FPNN `endpoint` 而在创建客户端时抛错。请显式补上 `protocol: 'tlv-v1'`;FPNN 调用则使用 `endpoint` 或 `ssl_endpoint` 并可省略 `protocol`。不要依赖 endpoint 字段自动推断协议。
|
|
23
|
+
|
|
24
|
+
## FPNN 接入:原有调用基本沿用
|
|
25
|
+
|
|
26
|
+
### 首先替换包引用
|
|
27
|
+
|
|
28
|
+
| 原项目接入方式 | 迁移改动 |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| 使用 `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')`。 |
|
|
31
|
+
| HTML 加载旧 `dist/rtm.min.js` | 替换 SDK 文件;UMD 仍提供 `window.rtm`,业务构造和调用可以沿用。 |
|
|
32
|
+
| 为 SDK 加载 `fpnn`、`msgpack`、`md5`、`Int64BE` 四个全局依赖 | 当前 SDK 已打包这些依赖,单纯供 SDK 使用时不再需要分别加载。若业务代码仍直接访问这些全局变量,需继续提供它们或调整业务引用;包根不额外导出 `fpnn` 全局。 |
|
|
33
|
+
| 深层引用旧包的 `src/*`、`libs/*` | 改用包根的公开导出;当前 npm `files` / `exports` 不提供这些旧内部路径。 |
|
|
34
|
+
|
|
35
|
+
例如旧代码用 `fpnn.FPConfig.ERROR_CODE.FPNN_EC_OK` 判断登录错误码,移除独立 FPNN 脚本后该全局变量不会由新 SDK 自动创建。登录时应按已有 `callback(accepted, errorCode)` 检查 `accepted`;也可以保留业务确实依赖的外部 FPNN 运行时。当前 SDK 内部仍优先使用已注入的兼容全局依赖。
|
|
36
|
+
|
|
37
|
+
只替换包引用并继续 `new RTMClient(...)`,不会自动启用共享连接,也不要求部署 Worker 或切换 TLV。
|
|
38
|
+
|
|
39
|
+
上游 `master` 使用 `new RTMClient(options)` 提供 `pid` 和 `endpoint` 或 `ssl_endpoint`,再用 `login(uid, token, callback, timeout)` 登录。UID 和 token 不在构造参数中;上游也没有要求业务先调用 dispatch 发现流程。当前 SDK 的 `RTMClient` 保留这套 FPNN 接入方式。
|
|
40
|
+
|
|
41
|
+
| 上游 GitHub `master` | 当前 SDK 的 FPNN `RTMClient` | 迁移说明 |
|
|
42
|
+
| --- | --- | --- |
|
|
43
|
+
| `new RTMClient({ pid, endpoint })` | 相同 | `endpoint` 仍是 FPNN Gate 的 `host[:port]`。 |
|
|
44
|
+
| `ssl_endpoint` | 相同 | 使用部署方提供的 SSL Gate 地址;当前 FPNN 配置要求 `host[:port]`,不要把 TLV WebSocket URL 当作 FPNN endpoint。 |
|
|
45
|
+
| `login(uid, token, callback, timeout)` | 相同 | token/credential 仍应由业务服务端签发。 |
|
|
46
|
+
| `autoReconnect` 默认 `true` | 默认 `true` | 无需为了保持上游默认值而改配置。 |
|
|
47
|
+
| `connectionTimeout`、`maxPingIntervalSeconds`、`attrs`、`platformImpl`、`md5`、`regressiveStrategy` | 保留 | 逐项按当前[接入指南](USAGE.md)确认配置约束。 |
|
|
48
|
+
| `ErrorRecorder`、`ReloginCompleted`、`SessionClosed` | 保留 | 事件名和主要用途不变;单个业务请求错误仍检查该请求的 callback/Promise。 |
|
|
49
|
+
| `client.processor.on(RTMConfig.SERVER_PUSH...)` | 保留 | FPNN 事件名及按消息类型拆分 Push 的行为沿用上游处理方式。 |
|
|
50
|
+
|
|
51
|
+
```js
|
|
52
|
+
import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
|
|
53
|
+
|
|
54
|
+
// 保留上游的一页一个客户端连接行为
|
|
55
|
+
const client = new rtm.RTMClient({
|
|
56
|
+
protocol: 'fpnn',
|
|
57
|
+
pid,
|
|
58
|
+
endpoint: 'rtm-gate.example.com:13321',
|
|
59
|
+
autoReconnect: true,
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
client.processor.on(rtm.RTMConfig.SERVER_PUSH.recvChat, (message) => {
|
|
63
|
+
console.log('chat', message);
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
client.login(uid, credential, (accepted, errorCode) => {
|
|
67
|
+
if (!accepted) console.error('RTM login failed', errorCode);
|
|
68
|
+
}, 30_000);
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### 不使用 SharedWorker 时的兼容边界
|
|
72
|
+
|
|
73
|
+
当使用 `new RTMClient({ protocol: 'fpnn', ... })`,或使用 `createClient({ sharing: false, protocol: 'fpnn', ... })` 时,当前 SDK 为每个客户端实例创建自己的 FPNN 连接。这与上游 `RTMClient` 的连接模型一致:多个页面各自创建客户端时,仍然是多个独立连接;不会自动跨页面共享登录态或转发 Push。当前 FPNN 请求仍由 `fpnn.FPClient` 承载,常用登录、发送 API 和 `RTMConfig.SERVER_PUSH` 事件名沿用上游。
|
|
74
|
+
|
|
75
|
+
这表示**接入模型和常见 FPNN 业务行为基本兼容,不表示实现逐行相同或所有异常时序都完全相同**。当前 SDK 在连接生命周期中增加了过期连接隔离和登录/重连竞态保护,降低旧连接回调影响新连接的风险;这些属于实现层修复,边界时序下的事件先后可能与上游不同。
|
|
76
|
+
|
|
77
|
+
还需注意以下差异:
|
|
78
|
+
|
|
79
|
+
- 当前 FPNN `endpoint` / `ssl_endpoint` 会校验为 `host[:port]`,不接受 URL scheme、路径、查询或片段;上游示例也使用 `host:port`,但当前版本会更早、明确地拒绝格式错误的地址。上游把普通 endpoint 的端口 `13325` 规范化为 `13321`,当前版本保留该兼容处理。
|
|
80
|
+
- 默认 `autoReconnect: true` 与上游一致。当前版没有为了 FPNN 迁移改变这一默认值。
|
|
81
|
+
- `login(uid, token, callback, timeout)`、FPNN Push 名称及普通 API 参数顺序沿用上游;当前版另外提供 Promise facade 和一批新增 API,见下表。
|
|
82
|
+
- `getUnreadMessage` 新增可选 `withLogout`,`removeSession` 新增可选 `localOnly`,`bye` 新增可选超时和 callback。旧 JavaScript 调用形式仍可用;当前类型声明也保留旧调用重载,只有需要新语义时才传新增参数。
|
|
83
|
+
- `createClient()` 即使默认协议为 FPNN,也会在 SharedWorker 可用时优先共享;浏览器没有 SharedWorker API 时自动使用独立连接。需要始终独立时,应使用 `RTMClient` 或显式设置 `sharing: false`;只设置 `protocol: 'fpnn'` 不会关闭可用时的共享。
|
|
84
|
+
|
|
85
|
+
共享模式下,当前 `createClient()` 通过 SharedWorker 按 PID、协议、UID 和 Gate 地址复用连接;首次登录的页面提供 credential,同身份的其他页面复用会话。
|
|
86
|
+
|
|
87
|
+
```js
|
|
88
|
+
// 选择共享连接;省略 protocol 时当前默认 FPNN
|
|
89
|
+
const client = rtm.createClient({ pid, endpoint: 'rtm-gate.example.com:13321' });
|
|
90
|
+
await client.promises.login(uid, credential);
|
|
91
|
+
|
|
92
|
+
// 如果使用 createClient 但要保留独立连接
|
|
93
|
+
const independentClient = rtm.createClient({
|
|
94
|
+
sharing: false,
|
|
95
|
+
pid,
|
|
96
|
+
protocol: 'fpnn',
|
|
97
|
+
endpoint: 'rtm-gate.example.com:13321',
|
|
98
|
+
});
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
浏览器应用无需自行维护 Worker 名称或 URL。共享连接要求页面同源,并使用一致的连接配置;完整身份规则、生命周期和构建工具配置见[默认共享接入](USAGE.md#默认共享接入)。
|
|
102
|
+
|
|
103
|
+
### 启用 SharedWorker 后真正需要调整的地方
|
|
104
|
+
|
|
105
|
+
`createClient()` 会在配置不能安全传递给 Worker 时使用页面内 `RTMClient`,并通过 `getConnectionInfo()` 报告原因。浏览器不支持 SharedWorker 时也会使用页面内连接。
|
|
106
|
+
|
|
107
|
+
| 接入部分 | 迁移要求 |
|
|
108
|
+
| --- | --- |
|
|
109
|
+
| 创建客户端 | 将 `new RTMClient(options)` 改成 `createClient(options)`;默认 FPNN,SharedWorker 可用时共享、不可用时自动独立连接。UID 可继续从 `login()` 参数取得。 |
|
|
110
|
+
| 登录 | 首次提供 credential,同 UID 的其他页面复用或加入同一次登录。共享层协调登录,认证请求由底层 SDK 执行。 |
|
|
111
|
+
| 业务 API、结果和事件 | FPNN 方法名、callback / Promise 结果和 Push 名称沿用底层 SDK;包括 `fileToken` 和三种文件发送。Worker 不维护业务禁用名单。 |
|
|
112
|
+
| 组件卸载 / 页面关闭 | 使用 `destroy()` 解绑当前页面;`bye()` / `close()` 会结束所有页面共享的 RTC 会话。不要继续用 `close()` 做单页清理。 |
|
|
113
|
+
| 多页配置 | 同 UID 页面需使用相同 PID、协议、Gate 和连接配置;页面需同源并支持 SharedWorker。 |
|
|
114
|
+
| 函数或平台对象配置 | `createClient()` 检测到 `md5`、`platformImpl`、`webSocketFactory`、函数型 metadata 等无法保留到 Worker 的运行时值时,会自动使用当前页面内的 `RTMClient`,完整保留配置行为;用 `getConnectionInfo()` 查看 `mode` 和 `fallbackReason`。直接构造 `RTMSharedWorkerClient` 仍要求配置可传递,并会对不支持的值报出路径和原因。 |
|
|
115
|
+
| 构建和部署 | 普通 HTML 将 Worker 与 SDK 部署在同源同目录;Vite 注册 `/vite-plugin`;Webpack 4 注册 `/webpack4` 插件;Webpack 5 使用包根 ESM 资源解析。 |
|
|
116
|
+
| 会话筛选 | 默认全部 SDK 事件广播到所有页面端口。已有 `conversation` / `setConversation()` 用法继续可用,筛选只在页面适配器中执行。 |
|
|
117
|
+
|
|
118
|
+
共享层只负责 SDK 实例、登录合并、调用/事件转发和生命周期;消息协议、文件上传、重连、ACK、去重、服务端能力和业务错误由底层 SDK 决定。SDK/Worker 升级时关闭所有旧共享页面,等待默认 5 秒回收旧 Worker 后再打开,避免新旧版本混用。
|
|
119
|
+
|
|
120
|
+
## 上游 API 与当前 API 的变化
|
|
121
|
+
|
|
122
|
+
大多数原有 FPNN 方法保留。下面列出确实发生的签名变化,以及新增能力;不要把这些变化与 TLV wire 字段名混为一谈。
|
|
123
|
+
|
|
124
|
+
| 上游 GitHub `master` | 当前 SDK | 影响与迁移方式 |
|
|
125
|
+
| --- | --- | --- |
|
|
126
|
+
| `getUnreadMessage(clear, timeout, callback)` | `getUnreadMessage(clear, withLogout, timeout, callback)`,兼容旧重载 | `withLogout` 用于请求登出时间;旧二参数 timeout-only 和三参数 callback 调用在 JS 与 TypeScript 中均可沿用。 |
|
|
127
|
+
| `removeSession(to, timeout, callback)` | `removeSession(to, localOnly, timeout, callback)`,兼容旧重载 | `localOnly` 用于选择本地/单向删除语义;旧调用继续沿用,未显式提供新布尔参数时 FPNN 请求不增加 `oneway` 字段。 |
|
|
128
|
+
| `bye()` | `bye(timeout, callback)` | 可选设置关闭请求超时并接收结果;无参调用仍可用。关闭后仍应按生命周期说明清理客户端。 |
|
|
129
|
+
| 通过外部 Promise 转换工具封装 callback | `client.promises` | 新增 SDK 自带 Promise facade;旧 callback API 仍保留。 |
|
|
130
|
+
| 只有 `RTMClient` 独立连接 | 新增 `createClient()` / `RTMSharedWorkerClient` | 新增同源多页面共享连接和 Push 路由;只在需要该能力时切换。 |
|
|
131
|
+
|
|
132
|
+
`getUnreadMessage` 和 `removeSession` 的新增布尔参数不是基础接入的必填项。上游调用可继续按原顺序传参;只有需要登出时间或本地删除语义时才传新增参数。`textCheck(text, timeout, callback)` 也有运行时和类型声明兼容重载。继续使用原有 callback 或外部 Bluebird Promise 转换工具时,不必改用新增的 `client.promises`;若主动改用 SDK Promise facade,省略 callback,并按当前参数顺序传入可选位,例如 `client.promises.getUnreadMessage(false, undefined, 15000)`。
|
|
133
|
+
|
|
134
|
+
### 新增 14 个公开方法
|
|
135
|
+
|
|
136
|
+
以下为完整 callback 签名;使用 `client.promises` 时省略末尾 callback。这些方法也由 SharedWorker 客户端代理。参数含义见[API 参数说明](USAGE.md#5-参数与返回值约定),FPNN method 与 TLV URI 对照见[协议迁移对照](PROTOCOL_MIGRATION.md)。接入指南中标为 TLV 的返回结构仅适用于 TLV,不应套用到 FPNN。
|
|
137
|
+
|
|
138
|
+
| 完整方法签名 | 用途 / 文档入口 |
|
|
139
|
+
| --- | --- |
|
|
140
|
+
| `getServerTime(timeout, callback)` | 查询服务端时间,见[时间查询](USAGE.md#初始化和生命周期-api)。 |
|
|
141
|
+
| `sendMessages(tos, mtype, msg, attrs, mid, timeout, callback)` | 批量发送私聊消息,见[消息发送](USAGE.md#消息发送和单条消息)。 |
|
|
142
|
+
| `setSessionRead(category, xid, readSeq, timeout, callback)` | 设置会话已读序号上界,见[未读与会话](USAGE.md#未读会话与-push)。 |
|
|
143
|
+
| `getP2PMessageByMessageId(ouid, mid, desc, num, begin, end, mtypes, timeout, callback)` | 以消息 ID 为锚点查询私聊历史,见[历史查询](USAGE.md#历史翻页与计数)。 |
|
|
144
|
+
| `getGroupMessageByMessageId(gid, mid, desc, num, begin, end, mtypes, timeout, callback)` | 以消息 ID 为锚点查询群历史,见[历史查询](USAGE.md#历史翻页与计数)。 |
|
|
145
|
+
| `getRoomMessageByMessageId(rid, mid, desc, num, begin, end, mtypes, timeout, callback)` | 以消息 ID 为锚点查询房间历史,见[历史查询](USAGE.md#历史翻页与计数)。 |
|
|
146
|
+
| `getBroadcastMessageByMessageId(mid, desc, num, begin, end, mtypes, timeout, callback)` | 以消息 ID 为锚点查询广播历史,见[历史查询](USAGE.md#历史翻页与计数)。 |
|
|
147
|
+
| `getP2PMessageCount(ouid, begin, end, mtypes, timeout, callback)` | 查询私聊消息数量,见[消息计数](USAGE.md#历史翻页与计数)。 |
|
|
148
|
+
| `getGroupMessageCount(gid, begin, end, mtypes, timeout, callback)` | 查询群消息数量,见[消息计数](USAGE.md#历史翻页与计数)。 |
|
|
149
|
+
| `getRoomMessageCount(rid, begin, end, mtypes, timeout, callback)` | 查询房间消息数量,见[消息计数](USAGE.md#历史翻页与计数)。 |
|
|
150
|
+
| `getBroadcastMessageCount(begin, end, mtypes, timeout, callback)` | 查询广播消息数量,见[消息计数](USAGE.md#历史翻页与计数)。 |
|
|
151
|
+
| `enterRooms(rids, timeout, callback)` | 批量进入房间,见[群组和房间](USAGE.md#群组和房间)。 |
|
|
152
|
+
| `getUserRoomsAndLastMessage(mtypes, timeout, callback)` | 查询用户房间及最近消息,见[群组和房间](USAGE.md#群组和房间)。 |
|
|
153
|
+
| `setRoomProfile(rid, publicData, privateData, label, avatar, timeout, callback)` | 设置房间公共/私有资料、名称和头像,见[群组和房间](USAGE.md#群组和房间)。原 `setRoomInfo` 保留。 |
|
|
154
|
+
|
|
155
|
+
这 14 项是 `RTMClient` 新增业务方法的统计;`client.promises`、`createClient()` 和 SharedWorker 客户端属于额外的接入能力,不包含在这 14 项中。
|
|
156
|
+
|
|
157
|
+
### 上游类型声明与源码不一致的地方
|
|
158
|
+
|
|
159
|
+
以下差异需要按项目实际调用核对;它们不是 JS 方法改名。上游源码与其 `dist/rtm.d.ts` 已有不一致,当前声明更贴近实际源码参数:
|
|
160
|
+
|
|
161
|
+
| API | 上游声明 / 文档 | 上游源码与当前推荐调用 |
|
|
162
|
+
| --- | --- | --- |
|
|
163
|
+
| `getMessage` / `deleteMessage` / `getChat` / `deleteChat` | 上游 `.d.ts` 缺少首个 `from` 参数 | `method(from, mid, xid, type, timeout, callback)`。若 TypeScript 项目按旧声明只传五个参数,需要补发送者 ID;上游 JS 源码本来就要求这个参数。 |
|
|
164
|
+
| `imageCheck` | 声明和文档省略 `strategyId` | `imageCheck(image, type, undefined, timeout, callback)`,有策略时替换 `undefined`。 |
|
|
165
|
+
| `audioCheck` | 声明和文档省略 `strategyId` | `audioCheck(audio, type, lang, codec, srate, undefined, timeout, callback)`。 |
|
|
166
|
+
| `videoCheck` | 声明和文档省略 `strategyId` | `videoCheck(video, type, videoName, undefined, timeout, callback)`。 |
|
|
167
|
+
| `removeSession` 与五种 `get*ConversationList` | 存在于上游 JS,缺失于上游 `.d.ts` | 当前补充了这些声明;这些会话查询不是本次新增的 JS 能力。 |
|
|
168
|
+
|
|
169
|
+
当前构造配置也有实际类型约束,例如 `pid` 是 number、FPNN endpoint 是 string,使用 TypeScript 的项目应按照真实业务值修正此前被 `any` 隐藏的配置问题。
|
|
170
|
+
|
|
171
|
+
### 已修复的旧实现行为
|
|
172
|
+
|
|
173
|
+
上游 `getChat` 错误地递归调用自身,`deleteChat` 向 `deleteMessage` 多传了一个 `this`。当前实现分别正确委托 `getMessage` / `deleteMessage`;方法名和源码签名保留,依赖旧行为的自定义补丁应重新核对。这属于旧实现修复,不能视为逐行行为完全不变。
|
|
174
|
+
|
|
175
|
+
连接生命周期另外修复了旧连接回调污染新连接、重复重连定时器和 processor 定时器回收问题。FPNN 基础库本体只修改了 UMD 全局对象选择以支持 Worker,MessagePack、MD5、Int64 库与上游文件相同。
|
|
176
|
+
|
|
177
|
+
当前 SDK 仍保留上游的 `dataGet`、`dataSet`、`dataDelete`、`getGroupMembers(gid, online, timeout, callback)`、历史查询 `mtypes` 参数和 `translate(..., type, profanity, timeout, callback)` 等签名;这些不是迁移差异。也不要将 processor 的 `kickout` Push 事件误认为客户端主动踢人 API。
|
|
178
|
+
|
|
179
|
+
## 选择 TLV v1 是另一项迁移
|
|
180
|
+
|
|
181
|
+
继续使用 FPNN 时不需要更换消息事件名称。改用 TLV v1 时,创建客户端需显式设置 `protocol: 'tlv-v1'` 并提供部署方给出的完整 WebSocket URL。TLV Push 使用 `event.direct`、`event.group`、`event.room`、`event.broadcast` 等名称,字段结构也不同;应使用 `RTMConfig.TLV_SERVER_PUSH` 常量和对应契约处理。
|
|
182
|
+
|
|
183
|
+
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)。
|
|
184
|
+
|
|
185
|
+
## 迁移成本判断
|
|
186
|
+
|
|
187
|
+
| 迁移目标 | 预计改动 | 主要检查项 |
|
|
188
|
+
| --- | --- | --- |
|
|
189
|
+
| 上游 `RTMClient` → 当前 `RTMClient`,继续 FPNN | 低 | 包导入、构建方式、credential、Gate 配置;原登录和常用消息代码大多可沿用。 |
|
|
190
|
+
| 改用 `createClient()` 以共享多窗口连接 | 低到中 | 同 UID 页面连接配置一致;处理共享会话生命周期;验证不同窗口收到各自需要的 Push。 |
|
|
191
|
+
| 从 FPNN 切换到 TLV v1 | 中到高 | Push 名称和字段、错误结构、服务端 URI 支持范围、历史和未读行为及文件等不支持 API。 |
|
|
192
|
+
|
|
193
|
+
## 迁移验收
|
|
194
|
+
|
|
195
|
+
- 确认正在对照的是上述 GitHub commit,还是业务项目实际锁定的 npm 包、fork 或内部构建。
|
|
196
|
+
- 继续 FPNN 时,先用当前 `RTMClient` 做最小登录、Push、发送和重连验证;不要把 TLV WebSocket URL 填入 FPNN `endpoint`。
|
|
197
|
+
- 若切换到 `createClient()`,明确接受默认共享连接行为;若不需要共享,使用 `RTMClient` 或 `sharing: false`。
|
|
198
|
+
- 搜索项目中 `getUnreadMessage`、`removeSession`、`bye` 的调用,确认新增参数只在业务需要时启用。
|
|
199
|
+
- 切换 TLV v1 时,按支持矩阵逐项检查 API、Push 结构、错误与服务端权限。
|
|
200
|
+
|
|
201
|
+
## 相关文档
|
|
202
|
+
|
|
203
|
+
- [FPNN 与 TLV v1 协议迁移对照](PROTOCOL_MIGRATION.md)
|
|
204
|
+
- [当前 SDK 接入指南](USAGE.md)
|
|
205
|
+
- [Push 事件说明](EventProcess.md)
|
|
206
|
+
- [当前 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])** 房间人数
|