云导播台WebSDK的集成方法和诊断工具的使用

说明

如果您正在使用V2.3.0之前的版本，可能会出现异常情况，建议您先升级至V2.3.0版本。升级步骤，请参见V2.2.X升级至V2.3.0。
如果您想使用V2.3.0以上版本，需先升级至V2.3.0版本后参考本文云导播Web SDK最新版本的集成方法。

前提条件

您已充分了解云导播的功能区域和用途，以及OpenAPI的调用方式，详细内容，请参见控制台操作指南、使用CommonRequest进行调用。
您已开通Web SDK License授权，具体操作，请参见开通License。
您已开通云导播需要的相关服务并绑定域名，具体操作，请参见开通服务、添加域名。
（可选）录制功能已授予直播写入OSS的权限，具体操作，请参见录制存储至OSS。

云导播台Web SDK可兼容以下版本的浏览器。


浏览器	支持的最低版本
Google Chrome	60
Firefox	25
Microsoft Edge	12
Safari	10
Opera	36
QQ Browser	10
360 Browser	stable
Sogou Browser	stable
UC Browser	stable
LieBao Browser	stable

集成云导播Web SDK

添加集成代码。

请按下面的示例将脚本及样式文件引用到您的页面中，即可完成最新云导播台Web SDK页面代码的添加。

重要引用下方代码时，请将@@version@@替换为Web SDK最新版本号。格式为a.b.c，示例：2.3.4。最新版本号请参见Web SDK发布历史。

<!doctype html>
<html>
<head>
  <meta charset="utf-8" />
  <title>Your App</title>
  <!-- 云导播台样式文件 -->
  <link rel="stylesheet" href="https://g.alicdn.com/cdn-fe/caster-next/@@version@@/index.css" />
  <link rel="stylesheet" href="https://g.alicdn.com/de/prismplayer/2.9.19/skins/default/aliplayer-min.css">
</head>
<body>
  <!-- 导播台要挂载的元素 -->
  <div id="caster-root"></div>
  <!-- 播放器脚本 -->
  <script src="https://g.alicdn.com/de/prismplayer/2.9.19/aliplayer-min.js"></script>
  <!-- 云导播台 sdk 脚本 -->
  <script src="https://g.alicdn.com/cdn-fe/caster-next/@@version@@/index.js"></script>
</body>
</html>

初始化SDK。

传入业务名称标识、云导播台需挂载的元素ID、导播台ID、（可选）语言选项。
注册所有服务（Service），详情请参见服务（接口）注册。

const { default: Caster } = window.AliCaster;

// 云导播台sdk加载后，会在全局挂载AliCaster对象
const services = {};
const caster = new Caster(
  {
    /**
     * type: string
     * 请传入您的业务名称标识
     * 通过邮件申请license取得
     */
    BizCode: 'BizCode',

    /**
     * type: string
     * 导播台要挂载的元素id，请确保此元素已创建
     */
    Container: 'caster-root',

    /**
     * type: string
     * 请填写您API接入的服务地域
     * 华东2：cn-shanghai
     * 华北2：cn-beijing
     */
    Region: 'cn-shanghai',

    /**
     * type: string
     * 导播台id，查看CreateCaster 返回参数CasterId值；如果通过直播控制台创建导播台，云导播台页面导播台列表中的导播台名称即导播台ID。
     */
    Id: 'LIVEPRODUCER_POST-cn-0pp0gal****',

    /**
     * type: boolean
     * 固定传 true
     */
    UseRts: true,

    /**
     * type: 'zh' | 'en
     * 可选语言 'zh'(简体中文) 'en'（英文-US），不传默认中文
     */
    // Language: 'en',

    /**
     * type: boolean
     * 是否开启诊断工具，注意：请勿将Debug参数用于生产环境。更多信息，请参见诊断工具。
     */
    // Debug: true
  },

  /**
   * type: object
   * 要注册的所有请求，services示例代码，请参见服务（接口）注册。
   */
  services
);

// 当您不再使用导播台时，可以调用destroy方法清除副作用（如timers）
caster.destory();

服务（接口）注册

云导播台Web SDK本身只负责界面和交互，没有内置请求的逻辑。您需要将每个请求封装成JS函数，在初始化SDK的时候将其传入，SDK在需要的时候会调用这些函数，发起请求。请求本身应该先发送给您自己的服务端，您自己的服务端再转发给相关的阿里云服务端。

前端视角

以下示例代码演示了初始化的时候将请求函数传给SDK注册：

const services = {
  // 可以将 fetch 替换成任意请求库；注意透传参数
  DescribeCasters: (params) => fetch('/DescribeCasters', params),
  // other services...
};
const caster = new Caster({/** configs **/}, services);

上述示例注册了DescribeCasters函数，函数内容是发起一个/DescribeCasters请求（注意透传参数），并返回这个请求的Promise。其中，/DescribeCasters调用您服务端的API，服务端再调用阿里云OpenAPI。

需要注册的接口列表

export interface ServicesImp {
  // 产品：云导播，API文档 https://help.aliyun.com/document_detail/60293.html
  DescribeCasters: (...args: any[]) => Promise<Resp>;
  DescribeCasterConfig: (...args: any[]) => Promise<Resp>;
  StopCaster: (...args: any[]) => Promise<Resp>;
  StartCaster: (...args: any[]) => Promise<Resp>;
  DescribeCasterVideoResources: (...args: any[]) => Promise<Resp>;
  AddCasterVideoResource: (...args: any[]) => Promise<Resp>;
  DeleteCasterVideoResource: (...args: any[]) => Promise<Resp>;
  DescribeCasterChannels: (...args: any[]) => Promise<Resp>;
  DescribeCasterScenes: (...args: any[]) => Promise<Resp>;
  StartCasterScene: (...args: any[]) => Promise<Resp>;
  StopCasterScene: (...args: any[]) => Promise<Resp>;
  UpdateCasterSceneConfig: (...args: any[]) => Promise<Resp>;
  DescribeCasterLayouts: (...args: any[]) => Promise<Resp>;
  DescribeCasterComponents: (...args: any[]) => Promise<Resp>;
  DeleteCasterComponent: (...args: any[]) => Promise<Resp>;
  EffectCasterUrgent: (...args: any[]) => Promise<Resp>;
  DeleteCasterSceneConfig: (...args: any[]) => Promise<Resp>;
  DescribeCasterSceneAudio: (...args: any[]) => Promise<Resp>;
  DeleteCasterLayout: (...args: any[]) => Promise<Resp>;
  SetCasterConfig: (...args: any[]) => Promise<Resp>;
  ModifyCasterVideoResource: (...args: any[]) => Promise<Resp>;
  SetCasterChannel: (...args: any[]) => Promise<Resp>;
  ModifyCasterLayout: (...args: any[]) => Promise<Resp>;
  AddCasterLayout: (...args: any[]) => Promise<Resp>;
  CopyCasterSceneConfig: (...args: any[]) => Promise<Resp>;
  UpdateCasterSceneAudio: (...args: any[]) => Promise<Resp>;
  DescribeCasterStreamUrl: (...args: any[]) => Promise<Resp>;
  AddCasterComponent: (...args: any[]) => Promise<Resp>;
  ModifyCasterComponent: (...args: any[]) => Promise<Resp>;

  // 虚拟演播厅类型的导播台接口
  ModifyStudioLayout: (...args: any[]) => Promise<Resp>;
  AddStudioLayout: (...args: any[]) => Promise<Resp>;
  DescribeStudioLayouts: (...args: any[]) => Promise<Resp>;
  DeleteStudioLayout: (...args: any[]) => Promise<Resp>;
  DescribeStudioDefaultBgImageList: (...args: any[]) => Promise<Resp>;
  CasterSnapshotReferScene: (...args: any[]) => Promise<Resp>;
  DescribeCasterRoomUsers: (...args: any[]) => Promise<Resp>;

  // 播单型导播台接口
  DescribeShowList: <R = any, T = any>(payload: R) => Promise<Resp<T>>;
  AddShowIntoShowList: <R = any, T = any>(payload: R) => Promise<Resp<T>>;
  RemoveShowFromShowList: (...args: any[]) => Promise<Resp>;
  ModifyShowList: (...args: any[]) => Promise<Resp>;
  PlayChoosenShow: (...args: any[]) => Promise<Resp>;

  // 产品：LIVE(视频直播)，API文档 https://help.aliyun.com/document_detail/48207.html
  DescribeLiveStreamsOnlineList: (...args: any[]) => Promise<Resp>;
  DescribeLiveDomainConfigs: (...args: any[]) => Promise<Resp>;
  DescribeLiveUserDomains: (...args: any[]) => Promise<Resp>;

  // 产品：视频点播（VOD），API文档 https://help.aliyun.com/document_detail/60574.html
  GetPlayInfo: (...args: any[]) => Promise<Resp>;
  CreateUploadImage: (...args: any[]) => Promise<Resp>;
  SearchMedia: (...args: any[]) => Promise<Resp>;
  GetImageInfo: <T = any>(...args: any[]) => Promise<Resp<T>>;
  GetVideoInfos: (...args: any[]) => Promise<Resp>;

  // 产品：对象存储（OSS），API文档 https://help.aliyun.com/document_detail/31948.html
  GetService: (...args: any[]) => Promise<Resp>;
  GetBucket: (...args: any[]) => Promise<Resp>;

  // 产品：访问控制（RAM），API文档 https://help.aliyun.com/document_detail/62184.html
  ListPoliciesForRole: (...args: any[]) => Promise<Resp>;
}

export interface Resp<T = any> {
  code: string;
  httpStatusCode: string;
  requestId: string;
  successResponse: boolean;
  data: T;  //业务数据
}

服务返回值的处理

每个服务应返回一个Promise对象，无论请求是否成功，总是会调用resolve方法返回结果。

返回的数据结构遵循以下规范，其中，data是具体的业务数据。

interface Resp<T = any> {
  code: string;
  httpStatusCode: string;
  requestId: string;
  successResponse: boolean;
  data: T;
}

如果OpenAPI请求成功，会返回类似如下数据。

{
  "RequestId": "996B6B22-FF2C-4069-929A-5B63261410C2",
  "Total": 0,
  "CasterList": {
    "Caster": []
  }
}

将返回的数据放入data段，使用resolve方法返回给SDK，应返回如下完整数据。

{
  "code": "200",
  "httpStatusCode": "200",
  "requestId": "996B6B22-FF2C-4069-929A-5B63261410C2",
  "successResponse": true,
  "data": {
    "RequestId": "996B6B22-FF2C-4069-929A-5B63261410C2",
    "Total": 0,
    "CasterList": {
      "Caster": []
    }
  }
}

如果OpenAPI请求失败，会返回类似如下数据。

{
  "RequestId": "F7FA5276-75D0-4C03-AC04-C5E35AB95CF4",
  "HostId": "example.aliyundoc.com",
  "Code": "InvalidCaster.NotFound",
  "Message": "The CasterId provided does not exist in our records.",
  "Recommend": "https://error-example.aliyundoc.com/status/search?Keyword=InvalidCaster.NotFound&source=PopGw"
}

此时，使用resolve方法返回给SDK，会返回如下数据。

{
  "code": "InvalidCaster.NotFound",
  "requestId": "F7FA5276-75D0-4C03-AC04-C5E35AB95CF4"
}

需要忽略的异常

一般情况下，如果返回结果的状态码为非200，您需要进行异常处理，但以下错误码除外。


API接口	错误码
DescribeCasterStreamUrl	'InvalidScene.NotFound'，'InvalidDomainName.NotFound'
DescribeCasterScenes	'InvalidDomainName.NotFound'
UpdateCasterSceneConfig	'MissingLayoutId'

服务端视角

重要

云导播Web SDK按照OpenAPI文档规范调用接口，服务端请使用CommonRequest方式调用OpenAPI，不要使用各自产品的SDK调用，否则会出现返回结构不一致、字段大小写不一致等问题。

以下是使用CommonRequest发起DescribeLiveUserDomains请求的示例：

import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.profile.DefaultProfile;
public class Sample {
    public static void main(String[] args) {
        // 创建DefaultAcsClient实例并初始化
        DefaultProfile profile = DefaultProfile.getProfile(
            "<your-region-id>",          // 您的地域ID
            "<your-access-key-id>",      // 您的AccessKey ID
            "<your-access-key-secret>"); // 您的AccessKey Secret
        IAcsClient client = new DefaultAcsClient(profile);
        // 创建API请求并设置参数
        CommonRequest request = new CommonRequest();
        // 视频直播相关配置
        request.setSysDomain("live.aliyuncs.com");
        request.setSysVersion("2016-11-01");
        // API：https://help.aliyun.com/document_detail/88332.html
        request.setSysAction("DescribeLiveUserDomains");
        // 透传来自 Web SDK 前端的参数
        request.putQueryParameter("LiveDomainType", "liveVideo");
        try {
            CommonResponse response = client.getCommonResponse(request);
            System.out.println(response.getData());
        } catch (ServerException e) {
            e.printStackTrace();
        } catch (ClientException e) {
            e.printStackTrace();
        }
    }
}

上述示例中的setSysDomain/setSysVersion参数取决于调用的不同产品，此处为视频直播的示例，其他产品（VOD/OSS/RAM）请参考对应文档说明（上文接口列表中有各产品的文档链接）。

诊断工具

为方便开发者排查接入过程中的问题，云导播台Web SDK提供一个诊断工具，可以在初始化前自动检查各项参数、环境、服务注册等是否正确。

说明

诊断工具仅支持V2.2.10及以上版本。
请勿将Debug参数用于生产环境。

使用方式

在初始化SDK时增加参数Debug:true即开启诊断工具，代码示例如下：

new Caster({
  BizCode: 'xxx',
  Container: 'xxx',
  Id: 'xxx',
  Region: 'xxx',
  Language: 'xxx',
  // 开启诊断工具
  Debug: true
}, service);

打开浏览器控制台，刷新页面，控制台会输出各项诊断信息，如下图所示：

常见问题

请参见集成Web SDK常见问题。