Proctor SDK TypeScript API

本页提供声网 Proctor SDK for Web/Electron 的 TypeScript API 参考。

AgoraProctorSDK

AgoraProctorSDK 是声网 Proctor SDK 的基础接口类，提供在线监考场景下灵动课堂的核心方法。

config

TypeScript

static config(config: ConfigParams):void

配置 Proctor SDK。

参数	描述
params	全局配置参数，详见 ConfigParams。

launch

TypeScript

static launch(dom: HTMLElement, option: LaunchOption):() => void

启动在线监考场景下的灵动课堂。

参数

参数	描述
dom	详见 Document。
option	课堂启动配置，详见 LaunchOption。

返回值

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

类型定义

ConfigParams

TypeScript

export type ConfigParams = {
    appId: string;
    region?: string;
};

SDK 全局配置。用于 AgoraProctorSDK.config 方法。

属性	描述
appId	（必填）声网 App ID。
region	（选填）区域。建议设置为靠近你的课件或录制文件对象存储服务所在的区域，因为跨区域传输较大的静态资源会造成比较大的延迟。举例来说，如果你的 S3 服务在北美，则建议将 region 也设为北美区域。所有灵动课堂客户端必须设置相同的区域，否则无法互通。支持以下区域： CN: （默认）中国大陆 AP: 亚太地区 EU: 欧洲 NA: 北美

LaunchOption

TypeScript

export type LaunchOption = {
  userUuid: string;
  userName: string;
  roomUuid: string;
  roleType: EduRoleTypeEnum;
  roomType: EduRoomTypeEnum;
  roomName: string;
  listener: ListenerCallback;
  pretest: boolean;
  rtmToken: string;
  language: LanguageEnum;
  startTime?: number;
  duration: number;
  widgets?: { [key: string]: typeof AgoraWidgetBase };
  userFlexProperties?: { [key: string]: any };
  mediaOptions?: LaunchMediaOptions;
  latencyLevel?: 1 | 2;
  uiMode?: FcrMultiThemeMode;
  checkStudentScreenShareState?: boolean;
  rtcCloudProxyType?: AgoraCloudProxyType;
  rtmCloudProxyEnabled?: boolean;
};

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

参数	描述
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 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
roomUuid	（必填）课堂 ID。这是课堂的全局唯一标识。长度在 64 字节以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
roleType	（必填）用户在课堂中的角色，详见 EduRoleTypeEnum。
roomType	（必填）课堂类型，详见 EduRoomTypeEnum。
roomName	（必填）课堂名，用于课堂内显示，长度在 64 字节以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
listener	（必填）课堂启动状态： ready: 课堂准备完毕。 destroyed: 课堂已销毁。
pretest	（必填）是否开启课前设备检测： true: 开启课前设备检测。开启后，在加入课堂前会弹出设备检测页面，测试终端用户的摄像头、麦克风和扬声器是否能正常工作。 false: 不开启课前设备检测。
rtmToken	（必填）用于鉴权的 RTM Token。详见使用 Token 鉴权。
language	（必填）课堂界面的语言，详见 LanguageEnum。
startTime	（选填）课堂开始时间（毫秒），以第一个进入课堂的用户传入的参数为准。
duration	（必填）课堂持续时间（秒），以第一个进入课堂的用户传入的参数为准。最大值为 86,400 秒，建议根据课堂实际时长设置。
widgets	（选填）扩展插件集合，扩展教室能力，详见自定义插件。
userFlexProperties	（选填）由开发者自定义的用户属性。详见如何设置自定义用户属性？
mediaOptions	（选填）媒体流相关设置，包含媒体流加密、摄像头视频流编码参数配置和屏幕共享视频流编码参数配置，详见 LaunchMediaOptions。
latencyLevel	（选填）观众端延时级别。只对非连麦用户有效。 1: 低延时。发流端与观众端的延时为 1500 ms - 2000 ms。 2:（默认）超低延时。发流端与观众端的延时为 400 ms - 800 ms。
uiMode	（选填）课堂界面模式，详见 FcrMultiThemeMode。
checkStudentScreenShareState	（选填）是否在学生屏幕共享断开后，立即将学生踢出房间： true: 立即踢出房间。 false: 不立即踢出房间。
rtcCloudProxyType	（选填）云代理模式。详见 AgoraCloudProxyType。
rtmCloudProxyEnabled	(选填) 开启 RTM 云代理。

LaunchMediaOptions

TypeScript

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

媒体流相关设置。

参数	描述
cameraEncoderConfiguration	摄像头采集视频流编码参数配置，详见 EduVideoEncoderConfiguration。
screenShareEncoderConfiguration	屏幕共享视频流编码参数配置，详见 EduVideoEncoderConfiguration。
encryptionConfig	媒体流加密配置，详见 MediaEncryptionConfig。
channelProfile	频道配置，详见 ChannelProfile。
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	加密密钥。

ChannelProfile

频道配置，用于 LaunchMediaOptions。

参数	描述
Communication	0：通信模式，一般用于一对多或一对一的小班课。
LiveBroadcasting	1：直播模式，相较于通信模式，更低费用，同时延迟相较于通信模式较大。

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 模式。

FcrMultiThemeMode

课堂界面显示模式。在 LaunchOption 中设置。

参数	描述
light	（默认）明亮模式。
dark	暗黑模式。

EduRoleTypeEnum

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

参数	描述
teacher	1: 老师，监考官。
student	2: 学生，参考线上考试。

EduRoomTypeEnum

课堂类型。在 LaunchOption 中设置。

参数	描述
RoomProctor	6: 在线监考房间。在线监考场景下，roomType 仅支持设为此类型。

LanguageEnum

界面语言。在 LaunchOption 中设置。

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

DeviceTypeEnum

TypeScript

export enum DeviceTypeEnum {
  Main = 'main',
  Sub = 'sub',
}

设备类型。

主副设备介绍详见 userUuid 的填写方式。

参数	描述
Main	main：主设备。
Sub	sub：副设备。

AgoraCloudProxyType

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

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