游客模式与自研用户体系对接指南

最近更新时间：2026年5月20日

1. 适用场景

本文适用于接入方已有自研用户体系，希望观看页观众先以游客身份进入保利威观看页，并在需要登录时通过接入方登录流程转换为正式用户身份的场景。

典型诉求包括：

• 未登录观众可以先进入观看页浏览内容。
• 观众触发互动、发言等需要身份的操作时，再进入接入方登录流程。
• 观众在接入方登录页完成登录后，将自研用户身份同步到保利威观看页。
• 保利威观看页后续以正式用户身份识别该观众。

游客模式可以用于内嵌 SaaS 观看页，也可以用于集成 Web 观看页 SDK。两类接入方式的登录触发方式不同。

2. 解决方案一：内嵌 SaaS 观看页

2.1 实现方式

这种方式适用于接入方直接使用保利威 SaaS 观看页，并通过网页、APP 或小程序内嵌方式打开观看页。

实现逻辑：

• 接入方在保利威后台开启游客模式。
• 接入方开启游客外部登录。
• 接入方配置自研登录页跳转地址。
• 未登录观众以游客身份进入 SaaS 观看页。
• 当游客触发需要登录的操作时，SaaS 观看页引导观众前往接入方登录页。
• 观众在接入方登录页完成登录后，由接入方调用独立授权接口。
• 观众返回观看页后，以正式用户身份进入。

保利威负责：

• 支持游客身份进入观看页。
• 在游客触发登录场景时，引导跳转接入方配置的登录页。
• 接收接入方通过独立授权传入的正式用户身份。
• 在观看页内识别正式用户身份。

接入方负责：

• 提供自研登录页。
• 在保利威后台配置游客模式和游客外部登录。
• 配置外部登录跳转地址。
• 观众登录成功后调用独立授权接口。
• 将观众带回观看页并携带正式用户身份参数。

优势：

• 可复用 SaaS 观看页的游客访问和登录引导能力。
• 接入方保留自己的登录体系。
• 观众身份最终可进入保利威观看页正式用户态。

注意事项：

• 接入方登录页需要处理登录成功后的回跳逻辑。
• 独立授权所需参数和签名需要由接入方服务端生成。
• 外部登录地址需要根据实际终端场景配置，例如浏览器、APP、小程序等。

后台配置参考：

2.2 对接流程

graph TD
    A["未登录观众进入 SaaS 观看页"] --> B["以游客身份浏览"]
    B --> C["触发发言/互动等登录场景"]
    C --> D["SaaS 跳转接入方登录页"]
    D --> E["观众完成登录"]
    E --> F["接入方调用独立授权接口"]
    F --> G["观众返回观看页"]
    G --> H["观看页以正式用户身份识别观众"]

1. 接入方在保利威后台开启游客模式。
2. 接入方开启游客外部登录。
3. 接入方配置自研登录页跳转地址。
4. 未登录观众打开 SaaS 观看页，以游客身份进入。
5. 游客点击发言、互动等需要登录的功能。
6. SaaS 观看页展示登录引导，并跳转接入方登录页。
7. 观众在接入方登录页完成自研登录。
8. 接入方服务端调用独立授权接口，传入外部用户 ID、昵称、时间戳、签名等信息。
9. 接入方将观众带回 SaaS 观看页。
10. 观看页以正式用户身份识别该观众。

接入方需要完成：

• 准备自研登录页地址。
• 在保利威后台开启游客模式。
• 在保利威后台开启游客外部登录。
• 配置外部登录跳转地址。
• 准备外部用户 ID、昵称等用户信息。
• 按独立授权要求生成 timestamp 和 sign。
• 观众登录成功后调用独立授权接口。
• 完成登录后的观看页回跳。

观看页进入方式示例：

游客身份进入：

https://live.polyv.cn/watch/123456

正式用户身份进入：

https://live.polyv.cn/watch/123456
&external_user_id=UID123
&nickname=张三
&timestamp=xxxx
&sign=xxxx

上述示例中的频道地址、外部用户 ID、昵称、时间戳和签名参数需以实际接入配置为准。

3. 解决方案二：集成 Web 观看页 SDK

3.1 实现方式

这种方式适用于接入方自行集成 Web 观看页 SDK，并希望在自己的页面逻辑中处理游客登录。

实现逻辑：

• 接入方在保利威后台开启游客模式。
• 接入方初始化 SDK 时不传正式用户身份。
• SDK 识别为游客身份后，抛出 guestLogin 事件。
• 接入方监听该事件，并展示自己的登录入口或跳转登录页。
• 观众在接入方登录流程中完成登录后，由接入方调用独立授权接口。
• 授权成功后，接入方通过 updateAuth 刷新 SDK 用户身份，或重新初始化 SDK。

保利威负责：

• SDK 支持游客身份初始化。
• SDK 在需要登录时抛出 guestLogin 事件。
• 支持通过授权后的正式用户身份刷新观看页身份。

接入方负责：

• 集成 Web 观看页 SDK。
• 监听 guestLogin 事件。
• 实现自己的登录流程。
• 观众登录成功后调用独立授权接口。
• 使用 updateAuth 或重新初始化 SDK 更新用户身份。

优势：

• 登录交互和页面表现由接入方控制。
• 适合接入方自建观看页或深度集成 SDK 的场景。
• 可与接入方已有前端路由、弹窗和账号体系结合。

注意事项：

• 接入方需要自行处理登录入口展示和登录完成后的身份刷新。
• SDK 接入方式下，游客外部登录配置可根据接入方页面实现方式选择是否使用。
• 接入方需要保证独立授权调用成功后再刷新 SDK 身份。

后台配置参考：

3.2 对接流程

graph TD
    A["接入方初始化 SDK，不传 externalUserId"] --> B["SDK 以游客身份进入观看页"]
    B --> C["SDK 触发 guestLogin 事件"]
    C --> D["接入方展示登录入口"]
    D --> E["观众完成登录"]
    E --> F["接入方调用独立授权接口"]
    F --> G["接入方 updateAuth 或重新初始化 SDK"]
    G --> H["SDK 以正式用户身份继续观看"]

1. 接入方在保利威后台开启游客模式。
2. 接入方初始化 SDK，不传 externalUserId。
3. SDK 以游客身份进入观看页。
4. SDK 在需要登录时触发 guestLogin 事件。
5. 接入方监听事件，并展示登录入口或跳转接入方登录页。
6. 观众在接入方登录流程中完成自研登录。
7. 接入方服务端调用独立授权接口。
8. 授权成功后，接入方通过 updateAuth 传入正式用户身份，或重新初始化 SDK。
9. SDK 以正式用户身份继续观看。

接入方需要完成：

• 开启游客模式。
• 初始化 SDK 时区分游客身份和正式用户身份。
• 监听 guestLogin 事件。
• 实现自研登录流程。
• 准备外部用户 ID、昵称、时间戳、签名等授权参数。
• 调用独立授权接口。
• 授权成功后刷新 SDK 身份。

SDK 初始化示例：

const player = new PolyvLivePlayer({
  channelId: 'xxx',
  authParams: {}
});

监听游客登录事件：

player.on('guestLogin', () => {
  // 此时观看页需要登录，可在这里展示接入方登录入口或跳转接入方登录页
});

观众登录成功后，接入方服务端需调用独立授权接口：

POST https://api.polyv.net/live/v4/user/viewerrecord/direct_auth

请求参数包括外部用户 ID、昵称、timestamp、sign 等信息，具体参数和签名规则以独立授权接口文档为准。

独立授权成功后，可刷新 SDK 身份：

player.updateAuth({
  externalUserId: 'UID123',
  nickname: '张三',
  sign: 'xxxx'
});

也可根据接入方页面实现方式重新初始化 SDK。

4. 方案对比