Classroom client SDK

This page provides the Kotlin API reference of the Agora Classroom SDK for Android.

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

_1

public static String version();

Gets the SDK version.

Returns

The SDK version.

_1

public static void setConfig(AgoraEduSDKConfig agoraEduSDKConfig);

Globally configures the SDK.

Sample code

_6

/** Global Configuration */

_6

// Agora App ID

_6

String appId = "XXX";

_6

// Whether to enable eye care mode

_6

boolean eyeCare = false;

_6

AgoraClassSdk.setConfig(new AgoraClassSdkConfig(appId, eyeCare));

Parameter

Parameter	Description
agoraEduSDKConfig	The SDK global configuration. See AgoraClassSdkConfig.

_3

public static AgoraEduClassRoom launch(@NotNull Context context,

_3

@NotNull AgoraEduLaunchConfig config,

_3

@NotNull AgoraEduLaunchCallback callback);

Launches a flexible classroom.

Sample code

_30

/** Classroom launching configuration */

_30

// The user name

_30

String userName = "XXX";

_30

// The user ID. Must be the same as the user ID that you use for generating an <Vg k="MESS" /> token.

_30

String userUuid = "XXX";

_30

// The classroom name

_30

String roomName = "XXX";

_30

// The classroom ID

_30

String roomUuid = "XXX";

_30

// The user role

_30

int roleType = AgoraEduRoleType.AgoraEduRoleTypeStudent.getValue();

_30

// The classroom type

_30

int roomType = AgoraEduRoomType.AgoraEduRoomType1V1.getValue()/AgoraEduRoomType.AgoraEduRoomTypeSmall.getValue()/AgoraEduRoomType.AgoraEduRoomTypeBig.getValue();

_30

// The <Vg k="MESS" /> token

_30

String rtmToken = "";

_30

// The start time (ms) of the class, determined by the first user joining the classroom.

_30

long startTime = System.currentTimeMillis() + 100;

_30

// The duration (ms) of the class, determined by the first user joining the classroom.

_30

long duration = 310L;

_30

// The region where the classroom is located. All clients must set the same region, otherwise, they may fail to communicate with each other.

_30

String region = AgoraEduRegion.cn;

_30

_30

AgoraEduLaunchConfig agoraEduLaunchConfig = new AgoraEduLaunchConfignew AgoraEduLaunchConfig(

_30

userName, userUuid, roomName, roomUuid, roleType,

_30

roomType, rtmToken, startTime, duration, region, null, null,

_30

AgoraBoardFitMode.Retain, streamState, AgoraEduLatencyLevel.AgoraEduLatencyLevelUltraLow,

_30

null, null);

_30

AgoraClassSdk.launch(MainActivity2.this, agoraEduLaunchConfig, (state) -> {

_30

Log.e(TAG, "launch-classroom-state:" + state.name());

_30

});

Parameter

Parameter	Description
context	The context of the app.
config	The classroom launching configuration. See AgoraEduLaunchConfig.
callback	The SDK uses the AgoraEduLaunchCallback class to report events related to classroom launching to the app.

Returns

The AgoraEduClassRoom class.

_1

public static void configCourseWare(@NotNull List<AgoraEduCourseware> coursewares);

Configures courseware downloading.

Sample code

_22

/** Construct and configure courseware */

_22

// Configure the courseware

_22

String taskUuid = "xxxxx";

_22

// The courseware download address

_22

String resourceUrl = String.formate("https://convertcdn.netless.link/dynamicConvert/{taskUuid}.zip", taskUuid);

_22

// The courseware name

_22

String resourceName = "xxxxxxx"

_22

// The list of courseware pages

_22

List<SceneInfo> sceneInfos = new ArrayList();

_22

// The link of a converted page

_22

String src = "http://xxxxxxx";

_22

Ppt ppt = new Ppt(src, 360, 640);

_22

SceneInfo sceneInfo = new SceneInfo(1, ppt, "ppt-file-name");

_22

List<SceneInfo> sceneInfos = new ArrayList();

_22

sceneInfos.add(sceneInfo);

_22

// The path for storing the courseware

_22

String scenePath = resourceName + "/" + sceneInfos.get(0).name;

_22

AgoraEduCourseware courseware = new AgoraEduCourseware(resourceName, scenePath, sceneInfos, resourceUrl);

_22

List<AgoraEduCourseware> wares = new ArrayList();

_22

wares.add(courseware);

_22

// Configure the courseware pre-downloading

_22

configCoursewares(wares);

Parameter

Parameter	Description
wares	The courseware pre-download configuration. See AgoraEduCourseware.

_2

public static void downloadCourseWare(@NotNull Context context, @Nullable AgoraEduCoursewarePreloadListener listener)

_2

throws Exception;

Pre-downloads the courseware.

Sample code

_15

// Download the configured courseware

_15

downloadCoursewares(activityContext, new AgoraEduCoursewarePreloadListener() {

_15

@Override

_15

public void onStartDownload(@NotNull AgoraEduCourseware ware) {

_15

}

_15

@Override

_15

public void onProgress(@NotNull AgoraEduCourseware ware, double progress) {

_15

}

_15

@Override

_15

public void onComplete(@NotNull AgoraEduCourseware ware) {

_15

}

_15

@Override

_15

public void onFailed(@NotNull AgoraEduCourseware ware) {

_15

}

_15

});

Parameter

Parameter	Description
context	The context of the app.
listener	The SDK reports events related to courseware preloading to the app through the AgoraEduCoursewarePreloadListener class.

_1

public static void registerExtensionApp(List<AgoraExtAppConfiguration> apps);

Register an extension application by using the ExtApp tool. ExtApp is a tool for embedding extension applications in Flexible Classroom. For details, see Customize Flexible Classroom with ExtApp.

The AgoraEduLaunchCallback class reports events related to classroom launching to the app.

_1

void onCallback(AgoraEduEvent state);

Reports classroom events.

Parameter	Description
state	The classroom events. See AgoraEduEvent.

The AgoraEduCoursewarePreloadListener class reports events related to courseware preloading to the app.

_1

void onStartDownload(@NotNull AgoraEduCourseware ware);

Indicates that the SDK starts downloading the courseware.

Parameter	Description
ware	The courseware pre-download configuration. See AgoraEduCourseware.

_1

void onProgress(@NotNull AgoraEduCourseware ware, double progress);

Indicates the progress of courseware pre-downloading.

Parameter	Description
ware	The courseware pre-download configuration. See AgoraEduCourseware.
progress	Indicates the progress of courseware pre-downloading.

_1

void onComplete(@NotNull AgoraEduCourseware ware);

Indicates that the courseware pre-downloading completes.

Parameter	Description
ware	The courseware pre-download configuration. See AgoraEduCourseware.

_1

void onFailed(@NotNull AgoraEduCourseware ware);

The courseware pre-downloading fails.

Parameter	Description
ware	The courseware pre-download configuration. See AgoraEduCourseware.

_5

public class AgoraClassSdkConfig {

_5

@NotNull

_5

private String appId;

_5

private int eyeCare;

_5

}

The SDK global configuration. Used in setConfig.

Attributes	Description
appId	The Agora App ID. See Get the Agora App ID.
eyeCare	Whether to enable eye care mode: 0: (Default) Disable eye care mode. 1: Enable eye care mode.

_17

class AgoraEduLaunchConfig(val userName: String,

_17

val userUuid: String,

_17

val roomName: String,

_17

val roomUuid: String,

_17

val roleType: Int = AgoraEduRoleType.AgoraEduRoleTypeStudent.value,

_17

val roomType: Int,

_17

val rtmToken: String,

_17

val startTime: Long?,

_17

val duration: Long?,

_17

val region: String,

_17

var videoEncoderConfig: EduVideoEncoderConfig? = null,

_17

val mediaOptions: AgoraEduMediaOptions?,

_17

val boardFitMode: AgoraBoardFitMode,

_17

val streamState: StreamState?,

_17

val latencyLevel: AgoraEduLatencyLevel? = AgoraEduLatencyLevel.AgoraEduLatencyLevelUltraLow,

_17

val userProperties: MutableMap<String, String>? = null,

_17

val widgetConfigs: MutableList<UiWidgetConfig>? = null) : Parcelable

The classroom launching configuration. Used in launch.

Attributes	Description
userName	The user name for display in the classroom. The string length must be less than 64 bytes.
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. "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ","
roomName	The room name for display in the classroom. The string length must be less than 64 bytes.
roomUuid	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. "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ","
roleType	The role of the user in the classroom. See AgoraEduRoleType.
roomType	The classroom type. See AgoraEduRoomType.
rtmToken	The Signaling token used for authentication. For details, see Generate an Signaling Token.
startTime	The start time (ms) of the class, determined by the first user joining the classroom.
duration	The duration (ms) of the class, determined by the first user joining the classroom.
region	The region where the classrooms is located. All clients must use the same region, otherwise, they may fail to communicate with each other. See AgoraEduRegionStr.
videoEncoderConfig	Video encoding configurations, including the width and height, frame rate, and bitrate. See EduVideoEncoderConfig
mediaOptions	The media options, including media encryption configurations. See AgoraEduMediaOptions.
boardFitMode	The PPT display mode. See AgoraBoardFitMode.
streamState	Controls whether students automatically send audio or video streams after they go onto the stage. See StreamState.
latencyLevel	The latency level of an audience member. See AgoraEduLatencyLevel.
userProperties	User properties customized by the developer. For details, see How can I set user properties?

_6

public enum AgoraEduEvent {

_6

AgoraEduEventFailed(0),

_6

AgoraEduEventReady(1),

_6

AgoraEduEventDestroyed(2),

_6

AgoraEduEventForbidden(3);

_6

}

Classroom events. Reported in onCallback.

Attributes	Description
AgoraEduEventFailed	0: The user fails to enter the classroom.
AgoraEduEventReady	1: The classroom is ready.
AgoraEduEventDestroyed	2: The classroom has been destroyed.
AgoraEduEventForbidden	3: The user is forbidden by the Flexible Classroom cloud service and not allowed to enter the classroom.

_3

public enum AgoraEduRoleType {

_3

AgoraEduRoleTypeStudent(2);

_3

}

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

Attributes	Description
AgoraEduRoleTypeStudent	2: A student.

_5

public enum AgoraEduRoomType {

_5

AgoraEduRoomType1V1(0),

_5

AgoraEduRoomTypeSmall(4),

_5

AgoraEduRoomTypeBig(2);

_5

}

The classroom type. Set in AgoraEduLaunchConfig.

Attributes	Description
AgoraEduRoomType1V1	0: One-to-one Classroom. An online teacher gives an exclusive lesson to only one student.
AgoraEduRoomTypeBig	2: Lecture Hall. 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 5,000. 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.
AgoraEduRoomTypeSmall	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 200. During the class, the teacher can invite students to speak up and have real-time audio and video interactions with the teacher.

_4

public enum AgoraBoardFitMode {

_4

Auto,

_4

Retain;

_4

}

The PPT display mode on the whiteboard. Set in AgoraEduLaunchConfig.

Parameter	Description
Auto	(Default) The PPT display mode is fit, which means uniformly scaling the PPT until one of its dimensions fits the boundary.
Retain	In this mode, if the student manually adjusts the PPT size, the client maintains this size no matter what class the student joins.

_4

data class StreamState (

_4

var videoState:Int,

_4

var audioState:Int

_4

)

Controls whether students automatically send audio or video streams after they go onto the stage. Set in AgoraEduLaunchConfig.

Parameter	Description
videoState	Whether to send the video stream: 0: (Default) Do not send the video stream. 1: Send the video stream.
audioState	Whether to send the audio stream: 0: (Default) Do not send the audio stream. 1: Send the audio stream.

_4

enum class AgoraEduLatencyLevel(val value: Int) {

_4

AgoraEduLatencyLevelLow(1),

_4

AgoraEduLatencyLevelUltraLow(2);

_4

}

The latency level of an audience member. Set in AgoraEduLaunchConfig.

Parameter	Description
AgoraEduLatencyLevelLow	Low latency. The latency from the sender to the receiver is 1500 ms to 2000 ms.
AgoraEduLatencyLevelUltraLow	(Default) Ultra-low latency. The latency from the sender to the receiver is 400 ms to 800 ms.

_1

class AgoraEduMediaOptions(val encryptionConfigs: AgoraEduMediaEncryptionConfigs?)

Media options. Set in AgoraEduLaunchConfig.

Parameter	Description
encryptionConfig	The media stream encryption configuration. See AgoraEduMediaEncryptionConfig for details.

_4

data class AgoraEduMediaEncryptionConfigs(

_4

val encryptionKey: String?,

_4

val encryptionMode: Int

_4

)

The media stream encryption configuration. Used in AgoraEduMediaOptions.

Parameter	Description
mode	The encryption mode. See AgoraEduEncryptMode.
key	The encryption key.

_9

enum class AgoraEduEncryptMode(val value: Int) {

_9

NONE(0),

_9

AES_128_XTS(1),

_9

AES_128_ECB(2),

_9

AES_256_XTS(3),

_9

SM4_128_ECB(4),

_9

AES_128_GCM(5),

_9

AES_256_GCM(6);

_9

}

The media stream encryption configuration. See AgoraEduMediaEncryptionConfig for details.

Parameter	Description
NONE	No encryption.
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.
SM4_128_ECB	128-bit ECB encryption, SM4 mode.
AES_128_GCM	128-bit AES encryption, GCM mode.
AES_256_GCM	256-bit AES encryption, GCM mode.

_7

data class AgoraEduCourseware(

_7

val resourceName: String?,

_7

val scenePath: String?,

_7

val scenes: List<SceneInfo>?,

_7

val resourceUrl: String?

_7

) {

_7

}

The courseware pre-download configuration. Used in configCoursewares.

Attributes	Description
resourceName	The file name.
scenePath	The local path for storing the file. Agora recommends setting this parameter as the combination of resourceName and name of the first SceneInfo object in scenes, such as, resourceName + "/" + sceneInfos.get(0).name.
scenes	A list of converted file pages, an array of SceneInfo objects. Flexible Classroom automatically converts files with the suffixes of "ppt", "pptx", "doc", "docx", and "pdf" to formats that can be displayed on the whiteboard in the classroom and then display the file on the whiteboard in pages. Each SceneInfo object represents one page.
resourceUrl	The URL address of the file, such as "https://convertcdn.netless.link/dynamicConvert/{taskUuid}.zip".

_5

public class SceneInfo {

_5

private int componentCount;

_5

private Ppt ppt;

_5

private String name;

_5

}

The detailed information of a page. Set in AgoraEduCourseware.

Attributes	Description
componentCount	The number of pages.
ppt	The detailed information of a converted page. See Ppt.
name	The page name.

_5

public class Ppt {

_5

private String src;

_5

private double width;

_5

private double height;

_5

}

The detailed information of a page displayed on the whiteboard. Set in SceneInfo.

Attributes	Description
src	The URL address of the converted page.
width	The width (pixel) of the page.
height	The height (pixel) of the page.

_7

object AgoraEduRegion {

_7

const val default = "CN"

_7

const val cn = "CN"

_7

const val na = "NA"

_7

const val eu = "EU"

_7

const val ap = "AP"

_7

}

Regions.

Attributes	Description
CN	Mainland China.
NA	North America.
EU	Europe.
AP	Asia Pacific.

_7

data class EduVideoEncoderConfig(

_7

var videoDimensionWidth: Int = 320,

_7

var videoDimensionHeight: Int = 240,

_7

var frameRate: Int = 15,

_7

var bitrate: Int = 200,

_7

var mirrorMode: Int = EduMirrorMode.AUTO.value

_7

)

The video encoder configuration. Used in AgoraEduLaunchConfig.

• In the Small Classroom scenario, the default resolution is 120p (160*120).

• In the One-to-one Classroom and Lecture Hall scenarios, the default resolution is 240p (320*240).

Parameter	Description
width	Width (pixel) of the video frame.
height	Height (pixel) of the video frame.
frameRate	The frame rate (fps) of the video. The default value is 15.
bitrate	The bitrate (Kbps) of the video. The default value is 200.
mirrorMode	Video mirror modes. See EduMirrorMode.

_5

enum class EduMirrorMode(val value: Int) {

_5

AUTO(0),

_5

ENABLED(1),

_5

DISABLED(2)

_5

}

Whether to enable mirror mode. Used in EduVideoEncoderConfig.

Parameter	Description
AUTO	The SDK disables mirror mode by default.
ENABLED	Enable mirror mode.
DISABLED	Disable mirror mode.