FcrUIScene TypeScript API

本页提供声网 FcrUIScene for Web 的 TypeScript API 参考。

FcrUIScene

FcrUIScene 是声网云课堂场景的基础接口类，提供在线教育场景下的核心方法。

launch

TypeScript

static launch(dom: HTMLElement, option: LaunchOptions, callbackSuccess?: () => void, callbackFailure?: (err: Error) => void, callbackDestroy?: (type: number) => void): () => void

启动云课堂。

参数

参数	描述
dom	详见 Document。
option	课堂启动配置，详见 LaunchOption。
callbackSuccess	课堂启动成功回调函数。
callbackFailure	课堂启动失败回调函数，err 为错误对象。
callbackDestroy	课堂销毁回调函数，type 为退出原因：1、正常退出，2、被踢出房间。

返回值

返回一个函数，用于销毁场景回收资源。

类型定义

LaunchOptions

TypeScript

export type LaunchOptions = {
  appId: string;
  region: EduRegion;
  language: Language;
  userUuid: string;
  userName: string;
  roleType: EduRoleTypeEnum;
  token: string;
  roomUuid: string;
  roomName: string;
  roomType: EduRoomTypeEnum;
  startTime?: number;
  duration: number;
  devicePretest: boolean;
  coursewareList?: CoursewareList;
  userFlexProperties?: { [key: string]: unknown };
  latencyLevel?: AgoraLatencyLevel;
  recordUrl?: string;
  recordRetryTimeout?: number;
  virtualBackgroundImages?: string[];
  webrtcExtensionBaseUrl?: string;
  mediaOptions?: LaunchMediaOptions;
  shareUrl?: string;
  widgets?: Record<string, typeof FcrUISceneWidget>;
  rtcCloudProxyType?: AgoraCloudProxyType;
  rtmCloudProxyEnabled? boolean;
};

课堂启动配置。用于 FcrUIScene.launch 方法。

参数	描述
appId	（必填）声网 App ID。
region	（选填）区域。建议设置为靠近你的课件或录制文件对象存储服务所在的区域，因为跨区域传输较大的静态资源会造成比较大的延迟。举例来说，如果你的 S3 服务在北美，则建议将 region 也设为北美区域。所有灵动课堂客户端必须设置相同的区域，否则无法互通。支持以下区域： CN: （默认）中国大陆 AP: 亚太地区 EU: 欧洲 NA: 北美
language	（必填）课堂界面的语言，详见 LanguageEnum。
userUuid	（必填）用户 ID。这是用户的全局唯一标识，需要与你生成 RTM Token 时使用的 UID 一致。填写方式见 userUuid 的填写方式。同时需满足长度在 64 字节以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
userName	（必填）用户名，用于课堂内显示，长度在 64 字节以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
roleType	（必填）用户在课堂中的角色，详见 EduRoleTypeEnum。
token	（必填）用于鉴权的 RTM Token。详见使用 Token 鉴权。
roomUuid	（必填）课堂 ID。这是课堂的全局唯一标识。长度在 64 字节以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
roomName	（必填）课堂名，用于课堂内显示，长度在 64 字节以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
roomType	（必填）课堂类型，详见 EduRoomTypeEnum。
startTime	（选填）课堂开始时间（毫秒），以第一个进入课堂的用户传入的参数为准。
duration	（必填）课堂持续时间（秒），以第一个进入课堂的用户传入的参数为准。最大值为 86,400 秒，建议根据课堂实际时长设置。
devicePretest	（必填）是否开启课前设备检测： true: 开启课前设备检测。开启后，在加入课堂前会弹出设备检测页面，测试终端用户的摄像头、麦克风和扬声器是否能正常工作。 false: 不开启课前设备检测。
coursewareList	（选填）教育机构指派的课件配置，客户端无法编辑。详见 CoursewareList。配置后，SDK 会在启动课堂时将相应的课件从声网云盘组件中下载至本地。
userFlexProperties	（选填）由开发者自定义的用户属性。详见如何设置自定义用户属性？
latencyLevel	（选填）观众端延时级别。只对非连麦用户有效。 1: 低延时。发流端与观众端的延时为 1500 ms - 2000 ms。 2:（默认）超低延时。发流端与观众端的延时为 400 ms - 800 ms。
recordUrl	（选填）待录制 URL 地址，开发者需传入自己部署的网页地址，用于页面录制，例如 https://cn.bing.com/recordUrl。
recordRetryTimeout	（选填）录制页面启动超时失败时间（秒）。当启动录制在一定时间内未成功进入教室，则重启录制。默认60秒。
virtualBackgroundImages	（选填）视频虚拟背景墙图片链接，资源所在域名应与你部署灵动课堂的域名相同。支持 PNG、JPG 格式图片。
webrtcExtensionBaseUrl	（选填）WebRTC 插件部署地址。默认为 https://solutions-apaas.agora.io/static。如果你需要在 Web 端使用虚拟背景、AI 降噪、美颜等高级功能，你需要将 WebRTC 插件和相应的资源文件部署到 FcrUIScene SDK 所在域名下。具体使用步骤：当你运行 yarn build:demo 完成打包后，packages/agora-demo-app/build/extensions 目录下会生成对应文件。将 extensions 目录部署到 FcrUIScene SDK 所在域名下。
mediaOptions	（选填）媒体流相关设置，包含媒体流加密、摄像头视频流编码参数配置和屏幕共享视频流编码参数配置，详见 LaunchMediaOptions。
shareUrl	（选填）邀请链接。
widgets	（选填）扩展插件集合，扩展教室能力，详见自定义插件。
rtcCloudProxyType	（选填）云代理模式。详见 AgoraCloudProxyType。
rtmCloudProxyEnabled	(选填) 开启 RTM 云代理。

LaunchMediaOptions

TypeScript

export type LaunchMediaOptions = {
    cameraEncoderConfiguration?: EduVideoEncoderConfiguration;
    screenShareEncoderConfiguration?: EduVideoEncoderConfiguration;
    encryptionConfig?: MediaEncryptionConfig;
    web?: {
        codec: SDK_CODEC;
        mode: SDK_MODE;
    };
};

媒体流相关设置。

参数	描述
cameraEncoderConfiguration	摄像头采集视频流编码参数配置，详见 EduVideoEncoderConfiguration。
screenShareEncoderConfiguration	屏幕共享视频流编码参数配置，详见 EduVideoEncoderConfiguration。
encryptionConfig	媒体流加密配置，详见 MediaEncryptionConfig。
web	用于配置浏览器编码格式和频道场景： codec: 浏览器编码格式，可以为如下： "vp8": VP8 编码。 "h264": H.264 编码。 mode: 频道场景，可以为如下： "rtc": 通信模式，一般用于一对多或一对一的小班课。 "live": 直播模式，相较于通信模式，更低费用，同时延迟相较于通信模式较大。

EduVideoEncoderConfiguration

TypeScript

export interface EduVideoEncoderConfiguration {
    width: number;
    height: number;
    frameRate: number;
    bitrate: number;
}

视频编码参数配置。

参数	描述
width	视频帧宽度，单位为 pixel，默认值为 320。
height	视频帧高度，单位为 pixel，默认值为 240。
frameRate	视频帧率，单位为 FPS，默认值为 15。
bitrate	视频码率，单位为 Kbps，默认值为 200。

MediaEncryptionConfig

TypeScript

export declare interface MediaEncryptionConfig {
    mode: MediaEncryptionMode;
    key: string;
}

媒体流加密配置，用于 LaunchMediaOptions。

参数	描述
mode	媒体流加密模式，详见 MediaEncryptionMode。同一教室内所有老师和学生必须使用相同的加密模式和密钥。
key	加密密钥。

MediaEncryptionMode

媒体流加密模式，用于 MediaEncryptionConfig。

参数	描述
AES_128_XTS	1：128 位 AES 加密，XTS 模式。
AES_128_ECB	2：128 位 AES 加密，ECB 模式。
AES_256_XTS	3：256 位 AES 加密，XTS 模式。
AES_128_GCM	5：128 位 AES 加密，GCM 模式。
AES_256_GCM	6：256 位 AES 加密，GCM 模式。

EduRoleTypeEnum

用户在课堂中的角色。在 LaunchOption 中设置。

参数	描述
teacher	1: 老师。
student	2: 学生。

EduRoomTypeEnum

课堂类型。在 LaunchOption 中设置。

参数	描述
RoomSmallClass	4: 云课堂。1 位老师进行在线教学，多名学生实时观看和收听。课堂人数上限为 200。

LanguageEnum

界面语言。在 LaunchOption 中设置。

参数	描述
en	英文。
zh	中文。

AgoraCloudProxyType

云代理类型。在 LaunchOption 中设置。

参数	描述
Automatic	0: 自动模式。该模式下，SDK 会首先尝试直接连接到 SD-RTN™。如果尝试失败，SDK 会自动退回到在 TLS 443 上发送媒体。如果你不确定最终用户的网络环境是否有防火墙，Automatic 模式为最佳实践。虽然在 TLS 443 上传输媒体可能不如 UDP 快速高效，但 TLS 443 上的连接可以通过大多数防火墙。
UDP	1: 使用 UDP 云代理。
TCP	2: 使用 TCP 云代理。