Classroom client SDK

This page provides the TypeScript API reference of the Agora Classroom SDK.

AgoraEduSDK is the basic interface of the Agora Classroom SDK and provides the main methods that can be invoked by your app.

static config(params: ConfigParams):void

Configure the SDK.

Sample code

AgoraEduSDK.config({

// Agora App ID

appId: "<YOUR AGORA APPID>",

// Region

region: "NA"

})

Parameter

Parameter	Description
params	The SDK global configuration. See ConfigParams.

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

Launch a classroom.

Sample code

// Configure courseware

let resourceUuid = "xxxxx"

let resourceName = "my ppt slide"

let sceneInfos = []

let sceneInfo = {

name: "1",

ppt: {

src: "pptx://....",

width: 480,

height: 360

}

}

sceneInfos.push(sceneInfo)

let courseWareList = [{

resourceUuid,

resourceName,

size: 10000,

updateTime: new Date().getTime(),

ext: "pptx",

url:null,

scenes: sceneInfos,

taskUuid: "xxxx",

taskToken: "xxx",

taskProgress: NetlessTaskProgress

}]

// Launch a classroom

AgoraEduSDK.launch(document.querySelector(`#${this.elem.id}`), {

rtmToken: "<your rtm token>",

userUuid: "test",

userName: "teacher",

roomUuid: "4321",

roleType: 1,

roomType: 4,

roomName: "demo-class",

pretest: false,

language: "en",

startTime: new Date().getTime(),

duration: 60 * 30,

courseWareList: [],

listener: (evt) => {

console.log("evt", evt)

}

})

Parameter

Parameter	Description
dom	See Document for details.
option	The classroom launching configuration. See LaunchOption.

Return value

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

The SDK global configuration. Used when calling AgoraEduSDK.config.

export type ConfigParams = {

appId: string;

region?: string;

};

Attributes	Description
appId	(Required) The Agora App ID. See Get the Agora App ID.
region	(Optional) The region where the classrooms is located. Agora recommends you set a region close to the region of the object storage service for your courseware or recording files, because cross-region transmission of large static resources can lead to delay. For example, if your S3 service is in North America, you should set this parameter to NA. All Smart Classroom clients must set the same area, otherwise they cannot communicate with each other. All clients must use the same region, otherwise, they may fail to communicate with each other. Flexible Classroom supports the following regions: CN: Mainland China AP: Asia Pacific EU: Europe NA: North America

export type ListenerCallback = (evt: AgoraEduClassroomEvent, ...args: unknown[]) => void;

The classroom launching configuration. Used when calling AgoraEduSDK.launch.

export type LaunchOption = {

userUuid: string;

userName: string;

roomUuid: string;

roleType: EduRoleTypeEnum;

roomType: EduRoomTypeEnum;

roomServiceType?: EduRoomServiceTypeEnum;

roomName: string;

listener: ListenerCallback;

pretest: boolean;

rtmToken: string;

language: LanguageEnum;

startTime?: number;

duration: number;

courseWareList: CourseWareList;

recordUrl?: string;

widgets?: {[key: string]: AgoraWidgetBase};

userFlexProperties?: {[key: string]: any};

mediaOptions?: MediaOptions;

latencyLevel?: 1 | 2;

platform?: Platform;

virtualBackgroundImages?: string[];

webrtcExtensionBaseUrl?: string;

rtcCloudProxyType?: AgoraCloudProxyType;

rtmCloudProxyEnabled? boolean;

};

Parameter	Description
rtmToken	(Required) The Signaling token used for authentication. For details, see Secure authentication with tokens.
userUuid	The user ID. This is the globally unique identifier of a user. Must be the same as the User ID that you use for generating an Signaling token. The string length must be less than 64 bytes. Supported character scopes are: All lowercase English letters: a to z. All numeric characters. 0-9 The space character. "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ","
userName	(Required) The user name for display in the classroom. The string length must be less than 64 bytes.
roomUuid	(Required) The room ID. This is the globally unique identifier of a classroom. The string length must be less than 64 bytes. Supported character scopes are: All lowercase English letters: a to z. All numeric characters. 0-9 The space character. "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ","
roomName	(Required) The room name for display in the classroom. The string length must be less than 64 bytes.
roleType	(Required) The role of the user in the classroom. See EduRoleTypeEnum.
roomType	(Required) The classroom type. See EduRoomTypeEnum.
roomServiceType	（Optional) The service type of big classrooms. See EduRoomServiceTypeEnum.
listener	(Required) Classroom event callback, please refer to the event type for details.
pretest	(Required) Whether to enable the pre-class device test: true: Enable the pre-class device test. After this function is enabled, end users can see a page for the device test before entering the classroom. They can check whether their camera, microphone, and speaker can work properly. false: Disable the pre-class device test.
language	(Required) The UI language. See LanguageEnum.
startTime	(Required) The start time (ms) of the class, determined by the first user joining the classroom.
duration	(Required) The duration (second) of the class, determined by the first user joining the classroom.
recordUrl	(Optional) The URL address to be recorded. Developers need to pass in the URL of the web page deployed by themselves for page recording, such as https://cn.bing.com/recordUrl.
widgets	(Optional) Extensive widgets that extend the classroom capabilities. See Embed a custom plugin for details.
courseWareList	(Optional) The configuration of courseware assigned by the educational institution, which cannot be edited by the client. See CourseWareList for details. After passing this object, the SDK downloads the courseware from the Agora cloud storage component to the local when launching the classroom.
userFlexProperties	(Optional) User properties customized by the developer.
mediaOptions	(Optional) Media stream configurations, including the encryption configuration and the encoding configurations of the screen-sharing stream and the video stream captured by the camera. See MediaOptions for details.
latencyLevel	(Optional) The latency level of an audience member in interactive live streaming: 1: Low latency. The latency from the sender to the receiver is 1500 ms to 2000 ms. (Default) Ultra-low latency. The latency from the sender to the receiver is 400 ms to 800 ms.
virtualBackgroundImages	(Optional) The URL of the virtual background image. The domain name of the resource should be the same as the domain name where you deployed smart classroom. Supports PNG and JPG format images.
webrtcExtensionBaseUrl	(Optional) The URL or the WebRtc extensions. The default value is https://solutions-apaas.agora.io/static. If you want to use the advanced features such as virtual backgrounds, AI noise suppression, and beauty options, you need to implement the WebRtc extensions and relevant resources in the Flexible Classroom SDK domain. These are the steps: 1. When you run yarn build:demo to complete packaging, the corresponding files are generated in packages/agora-demo-app/build/extensions. 2. Implement the directory in the domain of the Flexible Classroom SDK.
rtcCloudProxy	(Optional) The cloud proxy type for the RTC service: AgoraCloudProxyType.
rtmCloudProxyEnabled	(Optional) Where to enable cloud proxy for the RTM service.

export type MediaOptions = {

cameraEncoderConfiguration?: EduVideoEncoderConfiguration;

screenShareEncoderConfiguration?: EduVideoEncoderConfiguration;

encryptionConfig?: MediaEncryptionConfig;

channelProfile?: ChannelProfile;

web?: {

codec: SDK_CODEC;

mode: SDK_MODE;

};

};

Media options.

Parameter	Description
cameraEncoderConfiguration	The encoding configuration of the video stream captured by the camera. See EduVideoEncoderConfiguration.
screenShareEncoderConfiguration	The encoding configuration of the screen-sharing stream. See EduVideoEncoderConfiguration.
encryptionConfig	The media stream encryption configuration. See MediaEncryptionConfig.
channelProfile	Channel profile configuration. See ChannelProfile for details.
web	Web configuration for browser codec format and channel mode. codec: Browser codec format. Available values are as follows: "vp9": VP9 "h264": H.264 mode: 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. It costs less and has a higher latency than the communication mode.

export interface EduVideoEncoderConfiguration {

width: number;

height: number;

frameRate: number;

bitrate: number;

}

Video encoder configurations.

Parameter	Description
width	Width (pixel) of the video frame.
height	Height (pixel) of the video frame.
frameRate	The frame rate (fps) of the video.
bitrate	The bitrate (Kbps) of the video.

export declare interface MediaEncryptionConfig {

mode: MediaEncryptionMode,

key: string

}

The media stream encryption configuration. Used in MediaOptions.

Parameter	Description
mode	Encryption mode. See MediaEncryptionMode. All users in the same classroom must use the same encryption mode and encryption key.
key	The encryption key.

export enum MediaEncryptionMode {

AES_128_XTS = 1,

AES_128_ECB = 2,

AES_256_XTS = 3,

AES_128_GCM = 5,

AES_256_GCM = 6

}

Encryption modes. Used in MediaEncryptionConfig.

Parameter	Description
AES_128_XTS	128-bit AES encryption, XTS mode.
AES_128_ECB	128-bit AES encryption, ECB mode.
AES_256_XTS	256-bit AES encryption, XTS mode.
AES_128_GCM	128-bit AES encryption, GCM mode.
AES_256_GCM	256-bit AES encryption, GCM mode.

The courseware pre-download configuration. Used when calling AgoraEduSDK.launch.

export type CloudDriveResourceConvertProgress = {

totalPageSize: number;

convertedPageSize: number;

convertedPercentage: number;

convertedFileList: {

name: string;

ppt: {

width: number;

height: number;

preview?: string;

src: string;

};

}[];

currentStep: string;

};

export type CourseWareItem = {

resourceName: string;

resourceUuid: string;

ext: string;

url?: string;

size: number;

updateTime: number;

taskUuid: string;

conversion: {

type: string;

preview: boolean;

scale: number;

outputFormat: string;

};

taskProgress?: CloudDriveResourceConvertProgress;

};

export type CourseWareList = CourseWareItem[];

CourseWareList is an array that consists of CourseWareItem objects.

[

{

resourceName: xxxxxxx,

resourceUuid: xxxxxxxxx,

ext: 'pptx',

url: 'https://xxxxxxxxxxxxxx',

size: 0,

updateTime: xxxxxxxx,

taskUuid: 'xxxxxxxxx',

conversion: {

type: 'dynamic',

preview: true,

scale: 2,

outputFormat: 'png',

},

taskProgress: {

totalPageSize: 3,

convertedPageSize: 3,

convertedPercentage: 100,

convertedFileList: [

{

name: '1',

ppt: {

src: 'pptx://convertcdn.netless.link/dynamicConvert/3bxxxxxxx/1.slide',

width: 1280,

height: 720,

preview: 'dddddddddddddddurl',

},

},

...

] as any,

currentStep: '',

},

},

],

Parameter	Description
resourceName	The file name for display in the classroom. The string length must be less than 64 bytes.
resourceUuid	The file ID. This is the unique identifier of a file. The string length must be less than 64 bytes. Supported character scopes are: All lowercase English letters: a to z. All numeric characters. 0-9 The space character. "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ","
ext	The file suffix.
size	The file size (bytes).
updateTime	The latest modified time of the file.
taskUuid	The unique identifier of the file conversion task.
conversion	type: A string value that idicates the type of file conversion. You can set it as: static: Convert the PPT, PPTX, DOC, DOCX, or PDF file to a static image in PNG, JPG, JPEG, or WEBP format. The converted file does not retain the animation effects of the original file. dynamic: Convert the PPTX file (edited with Microsoft Office) to an HTML page. The converted file retains the animation effects of the original file. preview: A boolean value that indicates whether you need a preview window. scale: A number value that indicates the conversion scale. If you set it as 1, it means the file doesn't change the size after conversion. The range is [0, 3]. outputFormat: A string value that indicates the export format of the images after file conversion. For example, you can set it as "png".
url	The address of the file. Flexible Classroom clients automatically convert files with the suffixes of "ppt", "pptx", "doc", "docx", and "pdf" to formats that can be displayed on the whiteboard in classrooms. If the suffix name is not listed above, you must set url and leave scenes empty.
taskProgress	The JSON object, CloudDriveResourceConvertProgress, that indicates the progress of the file conversion task. It contains the following fields: totalPageSize: Total page size. convertedPageSize: The number of converted pages. convertedPercentage: The progress of the conversion task, expressed as a percentage. convertedFileList: A list of converted file pages. Each file page represents a record that contains the following fields: name: The name of the file page. ppt: Details of the slide included in the file page, which contains the following fields: width: The width of the slide. height: The height of the slide. src: The download URL of the converted page. preview: The URL of the preview image. currentStep: The current step of the conversion task. The possible values are extracting (extracting the resources), generatingPreview (generating the preview image), mediaTranscode (transcoding the media file), and packaging (packaging the file).

export enum EduRoleTypeEnum {

audience = 0,

teacher = 1,

student = 2,

assistant = 3

}

The role of the user in the classroom. Set in LaunchOption.

Parameter	Description
audience	0: Audience, only used for web page recording.
teacher	1: Teacher.
student	2: A student.
assistant	3: Teaching assistant.

export enum EduRoomTypeEnum {

Room1v1Class = 0,

RoomBigClass = 2,

RoomSmallClass = 4

}

The classroom type. Set in LaunchOption.

Parameter	Description
Room1v1Class	0: One-to-one Classroom. An online teacher gives an exclusive lesson to only one student.
RoomBigClass	2: Lecture Hall. A teacher gives an online lesson to multiple students. Students do not send their audio and video by default. There is no upper limit on the number of students. During the class, students can raise their hands to attract the teacher's attention and request to speak up. Once the teacher approves, the student can send their audio and video to interact with the teacher.
RoomSmallClass	4: Small Classroom. A teacher gives an online lesson to multiple students. Students do not send their audio and video by default. The maximum number of users in a classroom is 500. During the class, the teacher can invite students to speak up on stage and have real-time audio and video interactions with the teacher.

export enum EduRoomServiceTypeEnum {

LivePremium = 0,

}

The service type used in LaunchOption.

Parameter	Description
LivePremium	The classroom use the RTC service in the channel profile of live-broadcasting, with a latency of 400 ms. It works the same as interactive big classes.

export enum ChannelProfile {

Communication = 0,

LiveBroadcasting = 1,

}

Channel profiles, used in MediaOptions.

Values	Description
Communication	communication mode, commonly used for one-to-one or one-to-many classrooms.
LiveBroadcasting	live-streaming mode. It costs less and has a higher latency than the communication mode.

export type LanguageEnum = "en" | "zh"

The language of the user interface. Set in LaunchOption.

Parameter	Description
"en"	English.
"zh"	Chinese.

The cloud proxy type. Set in LaunchOptions.

Parameter	Description
Automatic	0: 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.
UDP	1: UDP.
TCP	2: TCP.

Classroom event listener. Set in LaunchOption.

Parameter	Description
Ready	1: Entered the classroom successfully.
Destroyed	2: The classroom has been destroyed. Includes the reason for leaving as a parameter: 1: Left the room voluntarily. 2: Have been kicked out of the room.
FailedToJoin	3: Failed to enter the classroom.
KickOut	101: Being kicked out of the room.
TeacherTurnOnMyMic	102: Audio streaming permission is enabled.
TeacherTurnOffMyMic	103: Audio streaming permission is turned off.
UserAcceptToStage	106: Get on the podium.
UserLeaveStage	107: Leave the podium.
RewardReceived	108: Reward received. Includes a list of rewarded users as a parameter.
TeacherTurnOnMyCam	109: The video streaming permission is enabled.
TeacherTurnOffMyCam	110: The video streaming permission has been turned off.
CurrentCamUnplugged	111: The current camera device is unplugged.
CurrentMicUnplugged	112: The current microphone device is unplugged.
CurrentSpeakerUnplugged	113: The current speaker is unplugged.
CaptureScreenPermissionDenied	114: No screen capture permission.
BatchRewardReceived	117: Receive bulk rewards. Includes a list of rewarded users as a parameter.
InvitedToGroup	118: Receive invitation to join group. Includes group information as parameters.
MoveToOtherGroup	119: Moved to other groups. Includes the following parameters: Previous group New group
JoinSubRoom	120: Join a group.
LeaveSubRoom	121: Leave the group.
AcceptedToGroup	122: The user accepts to join the group. Includes the following parameters: Group ID Accepting user
UserJoinGroup	123: Other users join the group. Includes the following parameters: Group ID List of joining users
UserLeaveGroup	124: Other users leave the group. Includes the following parameters: Group ID List of leaving users
RejectedToGroup	125: The user refuses to join the group. Includes the following parameters: Group ID List of refusing users
RTCStateChanged	201: RTC connection status change. Includes the RTC connection status as a parameter: 0: Not connected 1: Connecting 2: Connected 3: Reconnecting
ClassStateChanged	202: Classroom status changes. Includes the class status as a parameter: 0: Started 1: Not started 2: Dragging 3: Ended