在对导播台的功能区域及用途、OpenAPI的调用方式有一定认识后,通过阅读本文,您可以了解云导播台Web SDK的集成方法。

前提条件

  • 已开通导播需要的相关服务并绑定域名,具体操作请参见服务开通
  • 录制功能需授予直播写入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. 将上述资料发送至邮箱videosdk@service.aliyun.com。
    为更快速响应申请,邮件主题请注明:申请云导播台License。我们将3个工作日之内处理完开通申请。
  • 通过钉钉群申请开通:搜索开发者支持群群号35080444,或扫码加入。申请license

操作步骤

  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.5/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.5/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
         * 请传入您的业务名称标识
         */
        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: 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'