觀看條件 - 外部授權

一、設定資訊

1.1 外部授權設定資訊

關於外部授權設定及服務端的處理流程可見幫助中心文件：外部授權

Interface 介面： AuthSettingItemExternal

二、使用方式

2.1 允許驗證外部授權

從授權平台重新導向到觀看頁後，透過該方法判斷目前環境是否允許進行外部授權簽名驗證。

從 v0.11.0 版本開始，在授權通過，但其他配置是正常的情況下，也允許進行外部授權簽名驗證。另外透過新增 options 參數，開發者可以設定 { ignoreAuthorized:false } 來達到和之前版本一樣的效果

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

參數說明：

• signParams：授權簽名參數，ExternalAuthSignParams 類型，必傳，詳細類型說明如下

• options：配置項，Object 類型，選傳，詳細類型說明如下

回傳值說明： 是否允許驗證外部授權，Promise<boolean> 類型

範例：

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 驗證外部授權簽名參數

從授權平台跳轉回觀看頁後，透過 verifyExternalAuth 進行外部授權簽名參數驗證，在呼叫前請呼叫 allowToVerifyExternalAuth 判斷簽名參數是否符合要求。

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

參數說明：

• signParams：授權參數，ExternalAuthSignParams 類型，必傳，詳細類型說明如下

• queryParams：連結參數，object 類型，必傳

回傳值說明： Promise<VerifyExternalAuthResult> 類型

範例：

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 允許自動重新導向到外部授權失敗頁面

當外部授權失敗或沒有觀看頁地址沒有外部授權簽名參數時，透過 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> 類型，詳細類型說明如下

範例：

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);
}

2.6 外部授權登入按鈕是否啟用

Api 方法： getExternalAuthButtonEnabled(): boolean

從 v0.4.0 版本開始支援