Guest Mode and Custom User System Integration Guide

1. Applicable Scenarios

This guide is applicable when the integrator already has a custom user system and wants viewers to first enter the Polyv viewing page as guests, then convert to formal user identities through the integrator's login process when login is required.

Typical requirements include:

• Unauthenticated viewers can enter the viewing page to browse content first.
• Viewers enter the integrator's login process only when triggering actions requiring identity, such as interaction or posting comments.
• After viewers complete login on the integrator's login page, the custom user identity is synchronized to the Polyv viewing page.
• The Polyv viewing page subsequently identifies the viewer as a formal user.

Guest mode can be used for embedded SaaS viewing pages or integrated Web viewing page SDKs. The login trigger methods differ between the two integration approaches.

2. Solution 1: Embedded SaaS Viewing Page

2.1 Implementation Method

This approach is suitable when the integrator directly uses the Polyv SaaS viewing page and embeds it within a web page, app, or mini-program.

Implementation Logic:

• The integrator enables guest mode in the Polyv backend.
• The integrator enables guest external login.
• The integrator configures the custom login page redirect URL.
• Unauthenticated viewers enter the SaaS viewing page as guests.
• When a guest triggers an action requiring login, the SaaS viewing page directs the viewer to the integrator's login page.
• After the viewer completes login on the integrator's login page, the integrator calls the independent authorization API.
• The viewer returns to the viewing page and enters as a formal user.

Polyv Responsibilities:

• Support guest identity entry into the viewing page.
• When a guest triggers a login scenario, redirect to the integrator's configured login page.
• Receive the formal user identity passed by the integrator via independent authorization.
• Identify the formal user identity within the viewing page.

Integrator Responsibilities:

• Provide a custom login page.
• Enable guest mode and guest external login in the Polyv backend.
• Configure the external login redirect URL.
• Call the independent authorization API after the viewer logs in successfully.
• Bring the viewer back to the viewing page with the formal user identity parameters.

Advantages:

• Reuses the SaaS viewing page's guest access and login guidance capabilities.
• The integrator retains its own login system.
• The viewer's identity can ultimately enter the Polyv viewing page's formal user state.

Notes:

• The integrator's login page needs to handle the redirect logic after successful login.
• Parameters and signatures required for independent authorization must be generated by the integrator's server.
• The external login URL needs to be configured based on the actual terminal scenario, such as browser, app, or mini-program.

Backend Configuration Reference:

2.2 Integration Flow

1. The integrator enables guest mode in the Polyv backend.
2. The integrator enables guest external login.
3. The integrator configures the custom login page redirect URL.
4. An unauthenticated viewer opens the SaaS viewing page and enters as a guest.
5. The guest clicks on features requiring login, such as posting comments or interacting.
6. The SaaS viewing page displays a login prompt and redirects to the integrator's login page.
7. The viewer completes custom login on the integrator's login page.
8. The integrator's server calls the independent authorization API, passing external user ID, nickname, timestamp, signature, and other information.
9. The integrator brings the viewer back to the SaaS viewing page.
10. The viewing page identifies the viewer as a formal user.

The integrator needs to complete:

• Prepare the custom login page URL.
• Enable guest mode in the Polyv backend.
• Enable guest external login in the Polyv backend.
• Configure the external login redirect URL.
• Prepare user information such as external user ID and nickname.
• Generate timestamp and sign according to independent authorization requirements.
• Call the independent authorization API after the viewer logs in successfully.
• Redirect back to the viewing page after login.

Viewing Page Entry Examples:

Guest Identity Entry:

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

Formal User Identity Entry:

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

The channel URL, external user ID, nickname, timestamp, and signature parameters in the above examples must be based on the actual integration configuration.

3. Solution 2: Integrated Web Viewing Page SDK

3.1 Implementation Method

This approach is suitable when the integrator integrates the Web viewing page SDK themselves and wants to handle guest login within their own page logic.

Implementation Logic:

• The integrator enables guest mode in the Polyv backend.
• The integrator initializes the SDK without passing a formal user identity.
• The SDK identifies the guest identity and emits the guestLogin event.
• The integrator listens for this event and displays their own login entry or redirects to a login page.
• After the viewer completes login in the integrator's login flow, the integrator calls the independent authorization API.
• After successful authorization, the integrator refreshes the SDK user identity using updateAuth or reinitializes the SDK.

Polyv Responsibilities:

• The SDK supports initialization with a guest identity.
• The SDK emits the guestLogin event when login is required.
• Supports refreshing the viewing page identity with an authorized formal user identity.

Integrator Responsibilities:

• Integrate the Web viewing page SDK.
• Listen for the guestLogin event.
• Implement their own login flow.
• Call the independent authorization API after the viewer logs in successfully.
• Use updateAuth or reinitialize the SDK to update the user identity.

Advantages:

• Login interaction and page presentation are controlled by the integrator.
• Suitable for scenarios where the integrator builds their own viewing page or deeply integrates the SDK.
• Can be combined with the integrator's existing frontend routing, modals, and account system.

Notes:

• The integrator needs to handle the display of the login entry and identity refresh after login completion.
• In the SDK integration approach, the guest external login configuration can be used or not based on the integrator's page implementation.
• The integrator must ensure the independent authorization call succeeds before refreshing the SDK identity.

Backend Configuration Reference:

3.2 Integration Flow

1. The integrator enables guest mode in the Polyv backend.
2. The integrator initializes the SDK without passing externalUserId.
3. The SDK enters the viewing page as a guest.
4. The SDK triggers the guestLogin event when login is required.
5. The integrator listens for the event and displays a login entry or redirects to the integrator's login page.
6. The viewer completes custom login in the integrator's login flow.
7. The integrator's server calls the independent authorization API.
8. After successful authorization, the integrator passes the formal user identity via updateAuth or reinitializes the SDK.
9. The SDK continues viewing as a formal user.

The integrator needs to complete:

• Enable guest mode.
• Distinguish between guest identity and formal user identity when initializing the SDK.
• Listen for the guestLogin event.
• Implement the custom login flow.
• Prepare authorization parameters such as external user ID, nickname, timestamp, and signature.
• Call the independent authorization API.
• Refresh the SDK identity after successful authorization.

SDK Initialization Example:

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

Listening for Guest Login Event:

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

After the viewer logs in successfully, the integrator's server needs to call the independent authorization API:

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

Request parameters include external user ID, nickname, timestamp, sign, and other information. Specific parameters and signature rules are subject to the independent authorization API documentation.

After successful independent authorization, the SDK identity can be refreshed:

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

Alternatively, the SDK can be reinitialized based on the integrator's page implementation.

4. Solution Comparison