观看条件 - 外部授权

一、设置信息

1.1 外部授权设置信息

关于外部授权设置及服务端的处理流程可见帮助中心文档：外部授权

Interface 接口： AuthSettingItemExternal

属性名	说明	类型
authType	条件类型	External
enabled	是否启用	null | YN
externalUri	授权 url	string
externalRedirectUri	授权失败重定向 url	string
externalEntryText	入口文本	null | string
externalButtonEnabled	入口登录按钮是否启用，默认为 Y	null | YN

二、使用方式

2.1 允许验证外部授权

从授权平台重定向到观看页后，通过该方法判断当前环境是否允许进行外部授权签名验证。

从 v0.11.0 版本开始，在授权通过，但其他配置是正常的情况下，也允许进行外部授权签名验证。另外通过新增 options 参数，开发者可以设置 { ignoreAuthorized:false } 来达到和之前版本一样的效果

Api 方法： allowToVerifyExternalAuth(signParams: ExternalAuthSignParams, options?: Object): Promise<boolean>

参数说明：

• signParams：授权签名参数，ExternalAuthSignParams 类型，必传，详细类型说明如下

参数名	说明	类型	必须	默认值
userid	用户 id	string	是	-
ts	时间戳	string	是	-
sign	授权签名	string	是	-

• options：配置项，Object 类型，选传，详细类型说明如下

参数名	说明	类型	必须	默认值
ignoreAuthorized	忽略授权情况，默认 true	boolean	否	-

返回值说明： 是否允许验证外部授权，Promise<boolean> 类型

示例：

import { parse } from '@just4/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 验证外部授权签名参数

从授权平台跳转回观看页后，通过 verifyExternalAuth 进行外部授权签名参数验证，在调用前请调用 allowToVerifyExternalAuth 判断签名参数是否符合要求。

Api 方法： verifyExternalAuth(signParams: ExternalAuthSignParams, queryParams: object): Promise<VerifyExternalAuthResult>

参数说明：

• signParams：授权参数，ExternalAuthSignParams 类型，必传，详细类型说明如下

参数名	说明	类型	必须	默认值
userid	用户 id	string	是	-
ts	时间戳	string	是	-
sign	授权签名	string	是	-

• queryParams：链接参数，object 类型，必传

返回值说明： Promise<VerifyExternalAuthResult> 类型

示例：

import { parse } from '@just4/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 允许自动重定向到外部授权失败页面

当外部授权失败或没有观看页地址没有外部授权签名参数时，通过 allowAutoRedirectExternalAuthFailUrl 方法判断是否自动跳转到外部授权失败地址，内部判断条件如下：

• 观众未授权

• 管理后台只设置了外部授权（除独立授权）

Api 方法： allowAutoRedirectExternalAuthFailUrl(): Promise<boolean>

返回值说明： 是否自动重定向，Promise<boolean> 类型

示例：

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

2.4 获取外部授权失败的地址

当外部授权失败或无授权签名参数时，通过该方法获取授权失败自定义 URL 并进行跳转

Api 方法： getExternalAuthFailUrl(): Promise<ExternalAuthFailUrlData>

返回值说明： 外部授权失败地址信息，Promise<ExternalAuthFailUrlData> 类型，详细类型说明如下

属性名	说明	类型
externalAuthFailUrl	外部授权失败跳转地址	undefined | string

示例：

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

2.5 重定向到外部授权失败地址

如果不调用 getExternalAuthFailUrl 获取重定向地址，开发者可以调用 redirectExternalAuthFailUrl 进行跳转，通过方法返回的结果判断页面是否被跳转。

Api 方法： redirectExternalAuthFailUrl(): Promise<boolean>

返回值说明： 是否重定向，Promise<boolean> 类型

示例：

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