Watch Conditions - External Authorization

1. Configuration Information

1.1 External Authorization Configuration Information

For details on external authorization settings and server-side processing, please refer to the help center document: External Authorization

Interface: AuthSettingItemExternal

2. Usage

2.1 Allow Verification of External Authorization

After redirecting from the authorization platform to the watch page, use this method to determine whether the current environment allows external authorization signature verification.

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: allowToVerifyExternalAuth(signParams: ExternalAuthSignParams, options?: Object): Promise<boolean>

Parameter Description:

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

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

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

Example:

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

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

  const allowVerify = watchCore.auth.allowToVerifyExternalAuth(signParams);
  if (allowVerify) {
    // TODO 验证外部授权
  }
}

2.2 Verify External Authorization Signature Parameters

After redirecting from the authorization platform to the watch page, use verifyExternalAuth to verify the external authorization signature parameters. Before calling, please call allowToVerifyExternalAuth to check whether the signature parameters meet the requirements.

Api Method: verifyExternalAuth(signParams: ExternalAuthSignParams, queryParams: object): Promise<VerifyExternalAuthResult>

Parameter Description:

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

• queryParams: Link parameters, type object, required

Return Value Description: Type Promise<VerifyExternalAuthResult>

Example:

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

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

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

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

2.3 Allow Automatic Redirect to External Authorization Failure Page

When external authorization fails or the watch page URL lacks external authorization signature parameters, use the allowAutoRedirectExternalAuthFailUrl method to determine whether to automatically redirect to the external authorization failure address. Internal judgment conditions are as follows:

• The viewer is not authorized
• The admin console has only set external authorization (excluding independent authorization)

Api Method: allowAutoRedirectExternalAuthFailUrl(): Promise<boolean>

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

Example:

// 验证外部授权失败之后 / 无外部授权签名参数
const allowAutoRedirect = await watchCore.auth.allowAutoRedirectExternalAuthFailUrl();
if (allowAutoRedirect) {
  watchCore.auth.redirectExternalAuthFailUrl();
}

2.4 Get External Authorization Failure Address

When external authorization fails or there are no authorization signature parameters, use this method to obtain the custom authorization failure URL and redirect.

Api Method: getExternalAuthFailUrl(): Promise<ExternalAuthFailUrlData>

Return Value Description: External authorization failure address information, type Promise<ExternalAuthFailUrlData>. Detailed type description is as follows:

Example:

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

2.5 Redirect to External Authorization Failure Address

If you do not call getExternalAuthFailUrl to get the redirect address, developers can call redirectExternalAuthFailUrl to perform the redirect. Use the method's return result to determine whether the page was redirected.

Api Method: redirectExternalAuthFailUrl(): Promise<boolean>

Return Value Description: Whether redirected, type Promise<boolean>

Example:

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

2.6 Whether the External Authorization Login Button is Enabled

Api Method: getExternalAuthButtonEnabled(): boolean

Supported from version v0.4.0 onwards