@cg-devcenter/rtc-fpnn-webjs-sdk 1.0.0-cg.7 → 1.0.0-cg.8
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 +7 -5
- package/dist/rtm.d.mts +2 -0
- package/dist/rtm.d.ts +21 -7
- package/dist/rtm.min.js +5 -5
- package/dist/rtm.mjs +1 -1
- package/dist/rtm.vite.d.ts +2 -0
- package/docs/CAPABILITIES.md +1 -1
- package/docs/NPM_MODERNIZATION_PLAN.md +19 -18
- package/docs/RTM_MIGRATION.md +4 -2
- package/docs/USAGE.md +22 -14
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,7 +8,9 @@ RTC WebSocket Client SDK。新接入建议使用 `protocol: 'tlv-v1'`;`fpnn`
|
|
|
8
8
|
npm install @cg-devcenter/rtc-fpnn-webjs-sdk@latest
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
包根 ESM 入口和 `/vite-plugin`
|
|
11
|
+
包根 ESM 入口和 `/vite-plugin` 已包含在 npm `latest` 中。普通业务项目和三个框架 Demo 直接从 npm 安装 SDK;HTML Demo 使用仓库构建出的 UMD 文件。发布包入口与验证范围见 [实现与验证记录](docs/NPM_MODERNIZATION_PLAN.md)。
|
|
12
|
+
|
|
13
|
+
当前工作区包版本为 `1.0.0-cg.8`,是本地构建版本,尚未发布到 npm;registry `latest` 仍为 `1.0.0-cg.7`。本地 `npm pack` 可生成并审计 `cg.8` tarball;发布前使用 `@latest` 仍会安装 `cg.7`。
|
|
12
14
|
|
|
13
15
|
## 本地构建
|
|
14
16
|
|
|
@@ -26,7 +28,7 @@ Node.js 使用 TLV v1 时,需自行提供 `webSocketFactory(url)`。SDK 不携
|
|
|
26
28
|
|
|
27
29
|
### 默认共享入口
|
|
28
30
|
|
|
29
|
-
`createClient()` 在浏览器支持 SharedWorker
|
|
31
|
+
工作区当前的 `createClient()` 在浏览器支持 SharedWorker 且配置可安全传递时默认共享连接;浏览器不支持或配置含页面运行时值时自动使用当前页面的独立连接。`1.0.0-cg.8` 工作区构建版可通过 `client.getConnectionInfo()` 报告所选模式和回退原因。npm `latest` `1.0.0-cg.7` 尚未包含配置回退和此诊断 API:它只会在浏览器没有 SharedWorker 时改用页面内连接。省略 `protocol` 时默认使用 FPNN,以兼容旧 `RTMClient` 接入。新项目使用 TLV 时请显式设置 `protocol: 'tlv-v1'`。支持共享的环境中,SDK 自动按 PID、协议、UID 和 Gate 地址隔离会话;同一环境的页面自动复用,业务无需配置 Worker 名称或路径。UID 可直接从 `login()` 获取。
|
|
30
32
|
|
|
31
33
|
```js
|
|
32
34
|
const client = rtm.createClient({ protocol: 'tlv-v1', pid, tlvEndpoint: endpoint });
|
|
@@ -37,7 +39,7 @@ await client.promises.sendChat(peerUid, 'hello', '{}');
|
|
|
37
39
|
client.destroy();
|
|
38
40
|
```
|
|
39
41
|
|
|
40
|
-
片段中的 `rtm`、项目参数、credential 和 `renderMessage` 由应用提供;完整流程和能力边界见 [默认共享接入](docs/USAGE.md
|
|
42
|
+
片段中的 `rtm`、项目参数、credential 和 `renderMessage` 由应用提供;完整流程和能力边界见 [默认共享接入](docs/USAGE.md#默认共享接入)。从旧 `new RTMClient()` 迁移且继续使用 FPNN 时,可将构造器替换为 `createClient()` 并沿用 `endpoint` 配置;工厂默认协议为 FPNN。在浏览器支持 SharedWorker 且配置可传递时自动共享;当前工作区新版在不支持或存在函数、自定义实例等运行时配置时自动使用独立连接,并可通过 `client.getConnectionInfo()` 报告实际模式和回退原因。npm `latest` `1.0.0-cg.7` 尚无配置回退或诊断方法,仅在 SharedWorker 不可用时使用独立连接。显式设置 `sharing: false` 也会选择独立连接。现代 ESM 项目从包根导入;Vite 项目另在配置中注册 `/vite-plugin`,避免开发依赖预构建改写 SDK 的 Worker URL;Worker 资源由 Vite 构建输出。详见 [npm 接入现代化说明](docs/NPM_MODERNIZATION_PLAN.md)。
|
|
41
43
|
|
|
42
44
|
### 原有单连接入口
|
|
43
45
|
|
|
@@ -74,11 +76,11 @@ async function startChat(rtm, { pid, endpoint, uid, peerUid, credential }) {
|
|
|
74
76
|
|
|
75
77
|
## 同 UID 多窗口
|
|
76
78
|
|
|
77
|
-
需要同一浏览器内多个同源页面共用一个 UID 的 RTC 登录和 WebSocket 时,新接入推荐使用 SDK 的 `createClient()` 默认共享入口。支持 SharedWorker 时,SDK 按 PID、协议、UID 和 Gate 地址确定共享会话,业务代码无需维护 Worker 配置;普通浏览器部署时将 `rtm.min.js` 和 `rtm.shared-worker.js` 放在同一同源目录即可。浏览器不支持 SharedWorker 时,`createClient()` 自动改用当前页面的独立连接,各页面不共享登录态。首次登录需要 credential;同 UID 后续页面在支持共享的环境中复用会话。完整说明见 [默认共享接入](docs/USAGE.md
|
|
79
|
+
需要同一浏览器内多个同源页面共用一个 UID 的 RTC 登录和 WebSocket 时,新接入推荐使用 SDK 的 `createClient()` 默认共享入口。支持 SharedWorker 时,SDK 按 PID、协议、UID 和 Gate 地址确定共享会话,业务代码无需维护 Worker 配置;普通浏览器部署时将 `rtm.min.js` 和 `rtm.shared-worker.js` 放在同一同源目录即可。浏览器不支持 SharedWorker 时,`createClient()` 自动改用当前页面的独立连接,各页面不共享登录态。首次登录需要 credential;同 UID 后续页面在支持共享的环境中复用会话。完整说明见 [默认共享接入](docs/USAGE.md#默认共享接入)。
|
|
78
80
|
|
|
79
81
|
Vite 项目从 `@cg-devcenter/rtc-fpnn-webjs-sdk` 导入 ESM 入口,并在 Vite 配置中增加一次 `rtmSdkVitePlugin()`;Worker 由构建流程打包,业务无需填写路径。旧 `/vite` 导入仍保留兼容。若使用底层 `RTMSharedWorkerClient` 构造器,可通过 `uid` 自动生成 Worker 名称,或显式传入 `workerName`;`createClient()` 会按登录 UID 自动绑定,不要求手动设置名称。最后一个页面 detach 后默认 5 秒关闭共享连接。
|
|
80
82
|
|
|
81
|
-
常规接入不需要传 `workerUrl`:普通 HTML 将 `rtm.min.js` 与 `rtm.shared-worker.js` 放在同源同目录;Vite
|
|
83
|
+
常规接入不需要传 `workerUrl`:普通 HTML 将 `rtm.min.js` 与 `rtm.shared-worker.js` 放在同源同目录;Vite 项目在开发配置中注册上述插件;Webpack 4 项目配置 SDK 的 `/webpack4` 插件。Vue、React 或普通 JS 使用相同的 SDK API,Worker 资源由对应的构建方式定位和输出。只有自定义 Worker 部署位置时,才需要用 `workerUrl` 覆盖默认解析结果。详见[接入指南的 SharedWorker 章节](docs/USAGE.md#4-同-uid-多窗口sharedworker)。
|
|
82
84
|
|
|
83
85
|
如果直接从 unpkg 或 jsDelivr 加载 UMD,默认 Worker URL 会指向 CDN,无法用于页面的 SharedWorker。请把同版本 Worker 放到应用同源目录并传入 `workerUrl`,或设置 `sharing: false`。详见[CDN 与 Worker 同源要求](docs/USAGE.md#引用与运行环境)。
|
|
84
86
|
|
package/dist/rtm.d.mts
CHANGED
|
@@ -20,6 +20,8 @@ export type RTMSharedWorkerOptions = rtm.RTMSharedWorkerOptions;
|
|
|
20
20
|
export type RTMSharedCreateClientOptions = rtm.RTMSharedCreateClientOptions;
|
|
21
21
|
export type RTMIndependentCreateClientOptions = rtm.RTMIndependentCreateClientOptions;
|
|
22
22
|
export type RTMCreateClientOptions = rtm.RTMCreateClientOptions;
|
|
23
|
+
export type RTMConnectionInfo = rtm.RTMConnectionInfo;
|
|
24
|
+
export type RTMConnectionInfoProvider = rtm.RTMConnectionInfoProvider;
|
|
23
25
|
export type RTMDefaultClient = rtm.RTMDefaultClient;
|
|
24
26
|
export type RTMSharedSessionSnapshot = rtm.RTMSharedSessionSnapshot;
|
|
25
27
|
export type RTMSharedLoginResult = rtm.RTMSharedLoginResult;
|
package/dist/rtm.d.ts
CHANGED
|
@@ -267,15 +267,29 @@ declare namespace rtm {
|
|
|
267
267
|
conversation?: RTMConversation | null;
|
|
268
268
|
}
|
|
269
269
|
|
|
270
|
-
|
|
270
|
+
/** Flat createClient options. Unlike RTMSharedWorkerClient, createClient accepts the full RTMClient runtime config and falls back to a page-local client when a value cannot be preserved across Worker messaging. */
|
|
271
|
+
export type RTMSharedCreateClientOptions = RTMClientOptions &
|
|
271
272
|
Omit<RTMSharedWorkerOptions, 'clientOptions'> & { sharing?: true };
|
|
272
|
-
export type RTMIndependentCreateClientOptions = RTMClientOptions &
|
|
273
|
+
export type RTMIndependentCreateClientOptions = RTMClientOptions &
|
|
274
|
+
Omit<RTMSharedWorkerOptions, 'clientOptions'> & { sharing: false };
|
|
273
275
|
|
|
274
|
-
/** Flat client options. Sharing
|
|
276
|
+
/** Flat client options. Sharing is preferred by default; protocol defaults to FPNN in both modes. */
|
|
275
277
|
export type RTMCreateClientOptions = RTMSharedCreateClientOptions | RTMIndependentCreateClientOptions;
|
|
276
278
|
|
|
277
|
-
|
|
278
|
-
|
|
279
|
+
export interface RTMConnectionInfo {
|
|
280
|
+
/** `shared` uses the SharedWorker backend; `direct` uses an RTMClient in this page. */
|
|
281
|
+
mode: 'shared' | 'direct';
|
|
282
|
+
/** Null when direct mode was explicitly requested or no fallback was needed. */
|
|
283
|
+
fallbackReason: string | null;
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
export interface RTMConnectionInfoProvider {
|
|
287
|
+
/** Reports the selected backend and the reason createClient fell back to direct mode, if any. */
|
|
288
|
+
getConnectionInfo(): RTMConnectionInfo;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
/** createClient facade for either backend. The Worker attaches on login, or immediately when options.uid is set. */
|
|
292
|
+
export interface RTMDefaultClient extends Omit<RTMSharedWorkerClient, 'promises' | 'login' | 'whenReady'>, RTMConnectionInfoProvider {
|
|
279
293
|
readonly promises: RTMDefaultPromiseApi;
|
|
280
294
|
on(type: 'SharedWorkerReady' | 'SharedSessionState', callback: (session: RTMSharedSessionSnapshot) => void): this;
|
|
281
295
|
on(type: string, callback: (...args: any[]) => void): this;
|
|
@@ -289,9 +303,9 @@ declare namespace rtm {
|
|
|
289
303
|
emit(type: string, ...args: any[]): void;
|
|
290
304
|
}
|
|
291
305
|
|
|
292
|
-
export function createClient(options: RTMIndependentCreateClientOptions):
|
|
306
|
+
export function createClient(options: RTMIndependentCreateClientOptions): RTMDefaultClient;
|
|
293
307
|
export function createClient(options: RTMSharedCreateClientOptions): RTMDefaultClient;
|
|
294
|
-
export function createClient(options
|
|
308
|
+
export function createClient(options?: RTMCreateClientOptions): RTMDefaultClient;
|
|
295
309
|
|
|
296
310
|
export interface RTMSharedSessionSnapshot {
|
|
297
311
|
status: 'idle' | 'connecting' | 'authenticated';
|