Watch Conditions - Custom Authorization

1. Settings Information

1.1 Custom Authorization Settings Information

For details on custom authorization settings and server-side processing flow, refer to the help center document: Custom Authorization

Interface: AuthSettingItemCustom

2. Usage

2.1 Allow Verification of Custom Authorization

After redirecting back to the watch page from the authorization platform, use this method to determine whether custom authorization signature verification is allowed in the current environment.

Starting from version v0.11.0, when authorization passes but other configurations are normal, external authorization signature verification is also allowed. Additionally, through the new options parameter, developers can set { ignoreAuthorized:false } to achieve the same effect as previous versions.

Api Method: allowToVerifyCustomAuth(signParams: CustomAuthSignParams, options?: Object): Promise<boolean>

Parameter Description:

• signParams: Authorization signature parameters, type CustomAuthSignParams, required. Detailed type description is as follows:

• options: Configuration items, type Object, optional. Detailed type description is as follows:

Return Value Description: Whether custom authorization verification is allowed, type Promise<boolean>

Example:

import { parse } from '@polyv/utils/querystring';
import { CustomAuthSignParams } from '@polyv/live-watch-sdk';

async function example {
  const queryParams = parse(window.location.search.slice(1));
  const signParams: CustomAuthSignParams = {
    userid: queryParams.userid || '',
    ts: queryParams.ts || '',
    sign: queryParams.sign || '',
  };

  const allowVerify = watchCore.auth.allowToVerifyCustomAuth(signParams);
  if (allowVerify) {
    // TODO 验证自定义授权
  }
}

2.2 Verify Custom Authorization Signature Parameters

After redirecting back to the watch page from the authorization platform, use verifyCustomAuth to verify custom authorization parameters. Before calling, use allowToVerifyCustomAuth to check whether the signature parameters meet the requirements.

Api Method: verifyCustomAuth(signParams: CustomAuthSignParams, queryParams: object): Promise<VerifyCustomAuthResult>

Parameter Description:

• signParams: Authorization parameters, type CustomAuthSignParams, required. Detailed type description is as follows:

• queryParams: Link parameters, type object, required

Return Value Description: Authorization result, type Promise<VerifyCustomAuthResult>

Example:

import { parse } from '@polyv/utils/querystring';
import { CustomAuthSignParams } from '@polyv/live-watch-sdk';

async function example {
  const queryParams = parse(window.location.search.slice(1));
  const signParams: CustomAuthSignParams = {
    userid: queryParams.userid || '',
    ts: queryParams.ts || '',
    sign: queryParams.sign || '',
  };

  const allowVerify = watchCore.auth.allowToVerifyCustomAuth(signParams);
  if (!allowVerify) {
    return;
  }

  const result = await watchCore.auth.verifyCustomAuth(signParams, queryParams);
  if (result.success) {
    handleAuthVerifySuccess(result);
  } else {
    handleAuthVerifyFail(result);
  }
}

2.3 Allow Automatic Redirect to Custom Authorization URL

The authorization module provides a method to directly redirect viewers to the custom authorization URL when they enter the watch page, without going through the guide page. The internal judgment conditions are as follows:

• The viewer is not authorized
• Only custom authorization is set in the admin console
• The guide page switch is turned off in the admin console

Api Method: allowAutoRedirectCustomAuthUrl(): Promise<boolean>

Return Value Description: Whether to automatically redirect, type Promise<boolean>

Example:

const allowAutoRedirect = await watchCore.auth.allowAutoRedirectCustomAuthUrl();
// 当前不需要显示引导页，直接跳到自定义授权地址
if (allowAutoRedirect) {
  watchCore.auth.redirectCustomAuthUrl();
}

2.4 Get Custom Authorization URL

When the user clicks the authorization button, use this method to obtain the custom authorization link and perform the redirect.

Api Method: getCustomAuthUrl(): Promise<CustomAuthUrlData>

Return Value Description: Custom authorization redirect URL information, type Promise<CustomAuthUrlData>. Detailed type description is as follows:

Example:

document.querySelector('button').addEvenListener('click', async () => {
  const data = await watchCore.auth.getCustomAuthUrl();
  window.location.href = data.customAuthUrl;
});

2.5 Redirect to Custom Authorization URL

If you do not call getCustomAuthUrl to obtain the authorization URL, developers can call redirectCustomAuthUrl to perform the redirect. Use the method's return value to determine whether the page was redirected.

Api Method: redirectCustomAuthUrl(): Promise<boolean>

Return Value Description: Whether the redirect occurred, type Promise<boolean>

Example:

const result = await watchCore.auth.redirectCustomAuthUrl();
if (result.success) {
  console.log('页面已重定向');
} else {
  console.log('重定向失败，原因：', result.failReason);
}