訪客模式與自研用戶體系對接指南

最近更新時間：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. 方案對比