通过阅读本文,您可以了解云导播台Web SDK的集成方法和诊断工具的使用。

注意

调用服务端API需要使用CommonRequest,调用方法说明请参见使用CommonRequest进行调用

前提条件

  • 您已充分了解云导播的功能区域和用途,以及OpenAPI的调用方式。
  • 您已开通云导播需要的相关服务并绑定域名,具体操作请参见开通
  • 录制功能已授予直播写入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

Demo体验

下载Demo下载包
// 安装serve作为本地静态资源服务器
$ npm install serve -g

// 进入到 demo 目录
$ serve

// 默认访问http://localhost:5000即可

开通云导播台Web SDK License

云导播台Web SDK服务需要开通License,可以通过邮箱或钉钉群方式完成申请。

通过邮箱申请开通

  1. 准备以下资料,并保证资料齐全、格式规范:公司或平台名称、阿里云的账号或UID(若没有账号请注册,具体操作请参见注册阿里云账号)、联系人、联系电话。
  2. 描述您的业务场景、正在使用的产品信息、是否需要运营专人对接等,以便阿里云进一步为您提供更精准的产品和服务。
  3. 将上述资料及描述发送至邮箱videosdk@service.aliyun.com。

为更快速响应申请,邮件主题请注明:申请云导播台License。我们将3个工作日之内处理完开通申请。

通过钉钉群申请开通

搜索开发者支持群,群号为35080444,或扫码加入。申请license

集成云导播Web SDK

  1. 添加集成代码。
    请按下面的示例将脚本及样式文件引用到您的页面中,即可完成最新云导播台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/2.2.10/index.css" />
    </head>
    <body>
      <!-- 导播台要挂载的元素 -->
      <div id=""caster-root></div>
      <!-- webrtc adapter -->
      <script src="https://g.alicdn.com/code/lib/adapterjs/0.15.4/adapter.min.js"></script>
      <!-- webrtc 播放工具 -->
      <script src="https://g.alicdn.com/amte-fe/lib-artc-open/0.1.0/artc.js"></script>
      <!-- 云导播台 sdk 脚本 -->
      <script src="https://g.alicdn.com/cdn-fe/caster-next/2.2.10/index.js"></script>
    </body>
    </html>
  2. 初始化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
         */
        Id: 'LIVEPRODUCER_POST-cn-0pp0galm107',
    
        /**
         * type: 'zh' | 'en
         * 可选语言 'zh'(简体中文) 'en'(英文-US),不传默认中文
         */
        // Language: 'en',
    
        /**
         * type: boolean
         * 是否开启诊断工具
         */
        // Debug: true
      },
    
      /**
       * type: object
       * 要注册的所有请求,见下文
       */
      services
    );
    
    // 当您不再使用导播台时,可以调用destroy方法清除副作用(如timers)
    caster.destory();

服务注册

云导播台Web SDK本身只负责界面和交互,不会发起请求。您需要在初始化时进行服务注册,将请求的逻辑提供给Web SDK调用。请求本身应该先发送给您自己的服务端,您自己的服务端再转发给相关的阿里云服务端。

示例代码
const services = {
    DescribeCasters: (params) => fetch('/DescribeCasters', params),
  // other services...
}

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

需要注册的服务列表
export interface ServicesImp {
  // 产品:LIVE(视频直播),API文档 https://help.aliyun.com/document_detail/48207.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>;
  DescribeLiveStreamsOnlineList: (...args: any[]) => Promise<Resp>;
  DescribeLiveDomainConfigs: (...args: any[]) => Promise<Resp>;
  DescribeLiveUserDomains: (...args: any[]) => Promise<Resp>;
  AddCasterComponent: (...args: any[]) => Promise<Resp>;
  ModifyCasterComponent: (...args: any[]) => Promise<Resp>;

  DescribeCasterRtcInfo: (...args: any[]) => Promise<Resp>;
  DescribeCasterSyncGroup: (...args: any[]) => Promise<Resp>;
  SetCasterSyncGroup: (...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>;

  // 产品:视频点播(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: (...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": "live.aliyuncs.com",
      "Code": "InvalidCaster.NotFound",
      "Message": "The CasterId provided does not exist in our records.",
      "Recommend": "https://error-center.aliyun.com/status/search?Keyword=InvalidCaster.NotFound&source=PopGw"
    }
    此时,使用resolve方法返回给SDK,会返回如下数据。
    {
      "code": "InvalidCaster.NotFound",
      "requestId": "F7FA5276-75D0-4C03-AC04-C5E35AB95CF4"
    }
需要忽略的异常

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

需要忽略的错误码及对应的API接口如下所示。
API接口 错误码
DescribeCasterStreamUrl 'InvalidScene.NotFound','InvalidDomainName.NotFound'
DescribeCasterScenes 'InvalidDomainName.NotFound'
UpdateCasterSceneConfig 'MissingLayoutId'

诊断工具

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

使用方式

  1. 在初始化SDK时增加参数Debug:true即开启诊断工具,代码示例如下:
    new Caster({
      BizCode: 'xxx',
      Container: 'xxx',
      Id: 'xxx',
      Region: 'xxx',
      Language: 'xxx',
      // 开启诊断工具
      Debug: true
    }, service);
  2. 打开浏览器控制台,刷新页面,控制台会输出各项诊断信息,如下图所示:打开浏览器控制台,刷新页面,控制台会输出各项诊断信息,如下图所示:
说明
  • 诊断工具仅支持V2.2.10及以上版本。
  • 请勿将Debug参数用于生产环境。

常见问题

请参见集成Web SDK常见问题