Watch Condition Module

观看条件模块(auth) is primarily responsible for watch condition authorization. Before a viewer enters the live streaming page, they must complete watch condition authorization. Developers can use the watchCore.auth.isAuthorized method to obtain the viewer's authorization status:

• Unauthorized: Display a guide/authorization page for authorization. After authorization, re-watchCore.setup the core instance of the watch page and call watchCore.connect to connect to the chat room. Once connected, display the live streaming watch page.
• Authorized: Directly call watchCore.connect to connect to the chat room. Once connected, display the live streaming watch page.

Example:

// 观众未进行观看条件授权
if (!watchCore.auth.isAuthorized()) {
  // TODO：显示引导/授权页

  // 观众点击观看页入口或执行观看条件授权，如：无条件授权
  const result = await watchCore.auth.verifyNoneAuth();
  if (!result.success) {
    console.error('授权失败了！！', result.failReason);
    return;
  }

  // 当观众执行观看条件授权成功，需要重新安装 watchCore
  await watchCore.setup();
}

// 当完成观看条件授权后，即可连接聊天室进入直播观看页
await watchCore.connect();

// TODO：连接成功，显示直播观看页

For details on each watch condition, please refer to the development documentation for this module.

1. Watch Condition Types

Enum: AuthType

2. Usage

2.1 Get Watch Condition Settings List

Refer to the corresponding documentation for details on each watch condition's settings.

• When no watch restrictions are enabled in the backend, the settings list returns [Unconditional Authorization].
• When watch restrictions are enabled in the backend, the settings list returns [Primary Watch Condition, Secondary Watch Condition].

API Method: getAuthSettings(): AuthSettingItem[]

Return Value Description: Watch condition settings list, type AuthSettingItem[]

Example:

const authSettings = watchCore.auth.getAuthSettings();
authSettings.forEach(settingItem => {
  console.log('设置类型信息', settingItem);
  console.log('设置类型', settingItem.authType);
});

2.2 Check if the Current User Has Completed Watch Condition Authorization

API Method: isAuthorized(): boolean

Return Value Description: Whether authorization is complete

Example:

const isAuthorized = watchCore.auth.isAuthorized();
if (isAuthorized) {
  console.log('观众已进行观看条件授权，进入观看页');
} else {
  console.log('观众未进行观看条件授权，进入引导页进行授权');
}

3. Verifying Watch Conditions

The watch page SDK provides verification APIs for each watch condition. Developers can use the corresponding API to verify the watch condition. Once verification is successful, the live streaming watch page can be displayed.

3.1 Execute a Single Watch Condition Verification

Regardless of whether the verification is successful or not, the Promise for all watch condition verification methods will return the verification result result, which is of type AuthVerifyResult. When result.success is true, it indicates successful watch condition verification; false indicates failure. For specific failures, see Watch Condition Verification Failure Handling.

Code example:

/**
 * 验证白名单观看
 * @param phone 白名单
 */
async function verifyPhoneAuth(phone) {
  const result = await watchCore.auth.verifyPhoneAuth({
    phone,
  });

  if (result.success) {
    // 验证成功
    handleAuthVerifySuccess(result);
  } else {
    // 验证失败
    handleAuthVerifyFail(result);
  }
}

/**
 * 统一处理验证观看条件成功
 */
async function handleAuthVerifySuccess(successResult) {
  if (!successResult.success) {
    return;
  }

  // 重新安装观看页
  await watchCore.setup();
  console.log(watchCore.auth.isAuthorized()); // 此时返回 true
  console.log('验证成功，进入观看页');
}

AuthVerifyResult Type

/** 观看条件验证结果 */
type AuthVerifyResult<T extends AuthType> = AuthVerifyResultSuccess<T> | AuthVerifyResultFail<T>;

/** 观看条件验证结果（成功） */
interface AuthVerifyResultSuccess<T extends AuthType = AuthType> {
  /** 观看条件类型 */
  authType: T;
  /** 成功状态 */
  success: true;
}

/** 观看条件验证结果（失败） */
interface AuthVerifyResultFail<T extends AuthType = AuthType> {
  /** 观看条件类型 */
  authType: T;
  /** 成功状态 */
  success: false;
  /** 失败原因 */
  failReason: AuthVerifyError;
  /** 失败信息 */
  failMessage?: string;
  /** 获取重定向跳转地址 */
  getRedirectUrl?: () => string;
}

3.2 Verification Failure Handling

When watch condition verification fails (i.e., result.success is false), the failure reason can be obtained via result.failReason. Then, error prompts or other handling can be performed on the page. This field is of type AuthVerifyError enum. Example code:

/**
 * 处理观看条件失败
 * @param failResult 失败结果
 */
function handleAuthVerifyFail(failResult) {
  switch (failResult.failReason) {
    // 未知原因
    case AuthVerifyError.Unknow:
      toast.error('验证失败：未知原因');
      break;

    // 白名单不存在
    case AuthVerifyError.PhoneNotExist:
      toast.error('验证失败：白名单不存在');
      break;

    // 需要重定向
    case AuthVerifyError.RedirectUrl:
      if (failResult.getRedirectUrl) {
        const redirectUrl = failResult.getRedirectUrl();
        toast.error('验证失败，需要重定向', redirectUrl);
      }
      break;
    // ...其他错误处理
  }
}

3.3 Watch Condition Verification Failure Reasons

Enum: AuthVerifyError

4. API Method Overview