Skip to main content
Android
iOS
Web
Electron

Proctor SDK

This page provides the TypeScript API reference for the Agora Proctor SDK for Web and Electron.

AgoraProctorSDK

AgoraProctorSDK is the basic interface of the Agora Proctor SDK and provides the main methods for a flexible classroom in proctoring scenarios.

config

static config(config: ConfigParams):void
Copy

Configures the Agora Proctor SDK.

Parameters

ParameterDescription
configThe configuration for the flexible classroom, see ConfigParams for details.

launch

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

Launches a flexible classroom in a proctoring scenario.

Parameters

ParameterDescription
domThe Document Object Model (DOM). See Document for details.
optionThe classroom launching configuration, see LaunchOption for details.

Return value

Returns a function used to destroy the scene and recycle resources.

Type Definitions

ConfigParams

The global SDK configuration, used in AgoraProctorSDK.config.

export type ConfigParams = {
appId: string;
region?: string;
};
Copy
PropertyDescription
appIdThe Agora App ID. See Get the Agora App ID.
region(Optional) The region where the classroom is. All clients must use the same region; otherwise, they may fail to communicate with each other. The following regions are supported:
  • CN: Mainland China
  • NA: North America
  • EU: Europe
  • AP: Asia Pacific

LaunchOption

The classroom launching configuration used in AgoraProctorSDK.launch.

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;
};
Copy
PropertyDescription
userUuidThe user ID. This is the globally unique identifier of a user. This value must be the same as the User ID that you use for generating an RTM token. Refer to the relevant instructions in Integrate Flexible Classroom. This value must be less than 64 bytes. The following characters are supported:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0-9.
  • The space character.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
userNameThe user name for display in the classroom. This value must be less than 64 bytes.
roomUuidThe room ID. This is the globally unique identifier of a classroom. This value must be less than 64 bytes. The following characters are supported:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0-9.
  • The space character.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
roleTypeThe user's role in the classroom. See EduRoleTypeEnum for details.
roomTypeThe classroom type. See EduRoomTypeEnum for details.
roomNameThe room name for display in the classroom. The string length must be less than 64 bytes.
listenerThe state of classroom launching.
  • ready: The classroom is ready.
  • destroyed: The classroom has been destroyed.
pretestWhether to enable the pre-class device test:
  • true: Enable the pre-class device test. After this function is enabled, end users see a pop-up window to test their devices before entering the classroom. They can check whether their camera, microphone, and speaker are working properly.
  • false: Disable the pre-class device test.
rtmTokenThe signaling token used for authentication. For details, see Generate a Signaling Token.
languageThe language on the classroom UI. See LanguageEnum for details.
startTime(Optional) The start time (ms) of the class, determined by the first user joining the classroom.
durationThe duration (seconds) of the class, determined by the first user joining the classroom. The maximum value is 86,400. Agora recommends that you set this value as the actual class duration.
widgets(Optional) Extensive widgets that extend the classroom capabilities. See Embed a custom plugin for details.
userFlexProperties(Optional) User properties customized by the developer. See How can I set user properties and classroom properties for details.
mediaOptions(Optional) Media options, including the media encryption configuration, camera video encoder configuration, and screen sharing video encoder configuration. See LaunchMediaOptions for details.
latencyLevel(Optional) The latency level of an audience member. This property does not apply to cohosting users.
  • 1: Low latency. The latency from the sender to the receiver is between 1500 ms and 2000 ms.
  • 2: (default value) Ultra-low latency. The latency from the sender to the receiver is between 400 ms and 800 ms.
uiMode(Optional) The UI theme mode of the classroom. The default value is light, which means a light theme. See FcrMultiThemeMode for details.
checkStudentScreenShareState(Optional) Whether to kicks students out of the classroom immediately when they stop screen sharing:
  • true: Kick students out when they stop screen sharing.
  • false: Do not kick students out when they stop screen sharing.
rtcCloudProxy(Optional) The cloud proxy type for the RTC service: AgoraCloudProxyType.
rtmCloudProxyEnabled(Optional) Where to enable cloud proxy for the RTM service.

LaunchMediaOptions

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

Media options, including the media encryption configuration, camera video encoder configuration, and screen sharing video encoder configuration. Set in LaunchOption.

PropertyDescription
cameraEncoderConfiguration(Optional) The encoding configuration of the video stream captured by the camera. See EduVideoEncoderConfiguration for details.
screenShareEncoderConfiguration(Optional) The encoding configuration of the screen sharing stream. See EduVideoEncoderConfiguration for details.
encryptionConfig(Optional) The media stream encryption configuration. See MediaEncryptionConfig for details.
channelProfileThe channel profile configuration. See ChannelProfile for details.
webThe web configuration for browser codec format and channel mode.
  • codec: The browser codec format. Available values are as follows:
    • "vp9": VP9
    • "h264": H.264
  • mode: The channel mode. Available values are as follows:
    • "rtc": Communication mode, commonly used for one-to-one or one-to-many classrooms.
    • "live": Live-streaming mode; this option costs less than the communication mode and has a higher latency.

EduVideoEncoderConfiguration

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

The video encoder configuration.

PropertyDescription
dimensionWidthThe width of the video frame in pixels. The default value is 320.
dimensionHeightThe height of the video frame in pixels. The default value is 240.
frameRateThe frame rate of the video in FPS. The default value is 15.
bitRateThe bitrate of the video in Kbps. The default value is 200.

MediaEncryptionConfig

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

The media stream encryption configuration used in LaunchMediaOptions.

PropertyDescription
modeThe encryption mode. See MediaEncryptionMode. Teachers and students in the same classroom must use the same encryption mode and key.
keyThe encryption key.

ChannelProfile

export enum ChannelProfile {
Communication = 0,
LiveBroadcasting = 1,
}
Copy

The channel profiles, used in LaunchMediaOptions.

ValueDescription
CommunicationCommunication mode, commonly used for one-to-one or one-to-many classrooms.
LiveBroadcastingLive-streaming mode; this option costs less than communication mode and has a higher latency.

MediaEncryptionMode

export enum MediaEncryptionMode {
AES_128_XTS = 1,
AES_128_ECB = 2,
AES_256_XTS = 3,
AES_128_GCM = 5,
AES_256_GCM = 6,
}
Copy

The media stream encryption mode, used in MediaEncryptionConfig.

ValueDescription
AES_128_XTS128-bit AES encryption, XTS mode.
AES_128_ECB128-bit AES encryption, ECB mode.
AES_256_XTS256-bit AES encryption, XTS mode.
AES_128_GCM128-bit AES encryption, GCM mode.
AES_256_GCM256-bit AES encryption, GCM mode.

FcrMultiThemeMode

export enum FcrMultiThemeMode {
light = 'light',
dark = 'dark',
}
Copy

The UI theme mode of the classroom, used in LaunchOption.

ValueDescription
lightLight theme.
darkDark theme.

EduRoleTypeEnum

export enum EduRoleTypeEnum {
teacher = 1,
student = 2,
}
Copy

The role of the user in the classroom, used in LaunchOption.

ValueDescription
teacher1: Teacher/Proctor
student2: Student/Exam taker

EduRoomTypeEnum

export enum EduRoomTypeEnum {
RoomProctor = 6,
}
Copy

The classroom type, used in LaunchOption.

ValueDescription
RoomProctor6: A proctored exam. In proctoring scenarios, roomType can only set as this value.

LanguageEnum

export type LanguageEnum = "en" | "zh";
Copy

The language on the UI, used in LaunchOption.

ValueDescription
"en"English
"zh"Chinese

DeviceTypeEnum

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

Device types.

For more about main devices and supportive devices, see the relevant instructions in Integrate Flexible Classroom.

ValueDescription
MainMain device
SubSupportive device

AgoraCloudProxyType

The cloud proxy type. Set in LaunchOptions.

ParameterDescription
Automatic0: The automatic mode. In this mode, the SDK will first attempt to connect directly to SD-RTN™. If the attempt fails, the SDK will automatically fall back to sending media over TLS 443. If you are unsure whether the end user's network environment has a firewall, 'Automatic' mode is recommended as best practice. While transmitting media over TLS 443 may not be as fast and efficient as UDP, connections on TLS 443 can pass through most firewalls.
UDP1: UDP.
TCP2: TCP.
vundefined