Skip to main content
Android
iOS
Web
Electron

Classroom client SDK

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

AgoraClassSdk

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

version

public static String version();
Copy

Gets the SDK version.

Returns

The SDK version.

setConfig

public static void setConfig(AgoraEduSDKConfig agoraEduSDKConfig);
Copy

Globally configures the SDK.

Sample code

/** Global Configuration */
// Agora App ID
String appId = "XXX";
// Whether to enable eye care mode
boolean eyeCare = false;
AgoraClassSdk.setConfig(new AgoraClassSdkConfig(appId, eyeCare));
Copy

Parameter

ParameterDescription
agoraEduSDKConfigThe SDK global configuration. See AgoraClassSdkConfig.

launch

public static AgoraEduClassRoom launch(@NotNull Context context,
@NotNull AgoraEduLaunchConfig config,
@NotNull AgoraEduLaunchCallback callback);
Copy

Launches a flexible classroom.

Sample code

/** Classroom launching configuration */
// The user name
String userName = "XXX";
// The user ID. Must be the same as the user ID that you use for generating an <Vg k="MESS" /> token.
String userUuid = "XXX";
// The classroom name
String roomName = "XXX";
// The classroom ID
String roomUuid = "XXX";
// The user role
int roleType = AgoraEduRoleType.AgoraEduRoleTypeStudent.getValue();
// The classroom type
int roomType = AgoraEduRoomType.AgoraEduRoomType1V1.getValue()/AgoraEduRoomType.AgoraEduRoomTypeSmall.getValue()/AgoraEduRoomType.AgoraEduRoomTypeBig.getValue();
// The <Vg k="MESS" /> token
String rtmToken = "";
// The start time (ms) of the class, determined by the first user joining the classroom.
long startTime = System.currentTimeMillis() + 100;
// The duration (ms) of the class, determined by the first user joining the classroom.
long duration = 310L;
// The region where the classroom is located. All clients must set the same region, otherwise, they may fail to communicate with each other.
String region = AgoraEduRegion.cn;

AgoraEduLaunchConfig agoraEduLaunchConfig = new AgoraEduLaunchConfignew AgoraEduLaunchConfig(
userName, userUuid, roomName, roomUuid, roleType,
roomType, rtmToken, startTime, duration, region, null, null,
AgoraBoardFitMode.Retain, streamState, AgoraEduLatencyLevel.AgoraEduLatencyLevelUltraLow,
null, null);
AgoraClassSdk.launch(MainActivity2.this, agoraEduLaunchConfig, (state) -> {
Log.e(TAG, "launch-classroom-state:" + state.name());
});
Copy

Parameter

ParameterDescription
contextThe context of the app.
configThe classroom launching configuration. See AgoraEduLaunchConfig.
callbackThe SDK uses the AgoraEduLaunchCallback class to report events related to classroom launching to the app.

Returns

The AgoraEduClassRoom class.

configCourseWare

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

Configures courseware downloading.

Sample code

/** Construct and configure courseware */
// Configure the courseware
String taskUuid = "xxxxx";
// The courseware download address
String resourceUrl = String.formate("https://convertcdn.netless.link/dynamicConvert/{taskUuid}.zip", taskUuid);
// The courseware name
String resourceName = "xxxxxxx"
// The list of courseware pages
List<SceneInfo> sceneInfos = new ArrayList();
// The link of a converted page
String src = "http://xxxxxxx";
Ppt ppt = new Ppt(src, 360, 640);
SceneInfo sceneInfo = new SceneInfo(1, ppt, "ppt-file-name");
List<SceneInfo> sceneInfos = new ArrayList();
sceneInfos.add(sceneInfo);
// The path for storing the courseware
String scenePath = resourceName + "/" + sceneInfos.get(0).name;
AgoraEduCourseware courseware = new AgoraEduCourseware(resourceName, scenePath, sceneInfos, resourceUrl);
List<AgoraEduCourseware> wares = new ArrayList();
wares.add(courseware);
// Configure the courseware pre-downloading
configCoursewares(wares);
Copy

Parameter

ParameterDescription
waresThe courseware pre-download configuration. See AgoraEduCourseware.

downloadCourseWare

public static void downloadCourseWare(@NotNull Context context, @Nullable AgoraEduCoursewarePreloadListener listener)
throws Exception;
Copy

Pre-downloads the courseware.

Sample code

// Download the configured courseware
downloadCoursewares(activityContext, new AgoraEduCoursewarePreloadListener() {
@Override
public void onStartDownload(@NotNull AgoraEduCourseware ware) {
}
@Override
public void onProgress(@NotNull AgoraEduCourseware ware, double progress) {
}
@Override
public void onComplete(@NotNull AgoraEduCourseware ware) {
}
@Override
public void onFailed(@NotNull AgoraEduCourseware ware) {
}
});
Copy

Parameter

ParameterDescription
contextThe context of the app.
listenerThe SDK reports events related to courseware preloading to the app through the AgoraEduCoursewarePreloadListener class.

registerExtensionApp

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

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.

AgoraEduLaunchCallback

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

onCallback

void onCallback(AgoraEduEvent state);
Copy

Reports classroom events.

ParameterDescription
stateThe classroom events. See AgoraEduEvent.

AgoraEduCoursewarePreloadListener

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

onStartDownload

void onStartDownload(@NotNull AgoraEduCourseware ware);
Copy

Indicates that the SDK starts downloading the courseware.

ParameterDescription
wareThe courseware pre-download configuration. See AgoraEduCourseware.

onProgress

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

Indicates the progress of courseware pre-downloading.

ParameterDescription
wareThe courseware pre-download configuration. See AgoraEduCourseware.
progressIndicates the progress of courseware pre-downloading.

onComplete

void onComplete(@NotNull AgoraEduCourseware ware);
Copy

Indicates that the courseware pre-downloading completes.

ParameterDescription
wareThe courseware pre-download configuration. See AgoraEduCourseware.

onFailed

void onFailed(@NotNull AgoraEduCourseware ware);
Copy

The courseware pre-downloading fails.

ParameterDescription
wareThe courseware pre-download configuration. See AgoraEduCourseware.

Type definition

AgoraClassSdkConfig

public class AgoraClassSdkConfig {
@NotNull
private String appId;
private int eyeCare;
}
Copy

The SDK global configuration. Used in setConfig.

AttributesDescription
appIdThe Agora App ID. See Get the Agora App ID.
eyeCareWhether to enable eye care mode:
  • 0: (Default) Disable eye care mode.
  • 1: Enable eye care mode.
  • AgoraEduLaunchConfig

    class AgoraEduLaunchConfig(val userName: String,
    val userUuid: String,
    val roomName: String,
    val roomUuid: String,
    val roleType: Int = AgoraEduRoleType.AgoraEduRoleTypeStudent.value,
    val roomType: Int,
    val rtmToken: String,
    val startTime: Long?,
    val duration: Long?,
    val region: String,
    var videoEncoderConfig: EduVideoEncoderConfig? = null,
    val mediaOptions: AgoraEduMediaOptions?,
    val boardFitMode: AgoraBoardFitMode,
    val streamState: StreamState?,
    val latencyLevel: AgoraEduLatencyLevel? = AgoraEduLatencyLevel.AgoraEduLatencyLevelUltraLow,
    val userProperties: MutableMap<String, String>? = null,
    val widgetConfigs: MutableList<UiWidgetConfig>? = null) : Parcelable
    Copy

    The classroom launching configuration. Used in launch.

    AttributesDescription
    userNameThe user name for display in the classroom. The string length must be less than 64 bytes.
    userUuidThe 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.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ","
  • roomNameThe room name for display in the classroom. The string length must be less than 64 bytes.
    roomUuidThe 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.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ","
  • roleTypeThe role of the user in the classroom. See AgoraEduRoleType.
    roomTypeThe classroom type. See AgoraEduRoomType.
    rtmTokenThe Signaling token used for authentication. For details, see Generate an Signaling Token.
    startTimeThe start time (ms) of the class, determined by the first user joining the classroom.
    durationThe duration (ms) of the class, determined by the first user joining the classroom.
    regionThe region where the classrooms is located. All clients must use the same region, otherwise, they may fail to communicate with each other. See AgoraEduRegionStr.
    videoEncoderConfigVideo encoding configurations, including the width and height, frame rate, and bitrate. See EduVideoEncoderConfig
    mediaOptionsThe media options, including media encryption configurations. See AgoraEduMediaOptions.
    boardFitModeThe PPT display mode. See AgoraBoardFitMode.
    streamStateControls whether students automatically send audio or video streams after they go onto the stage. See StreamState.
    latencyLevelThe latency level of an audience member. See AgoraEduLatencyLevel.
    userPropertiesUser properties customized by the developer. For details, see How can I set user properties?

    AgoraEduEvent

    public enum AgoraEduEvent {
    AgoraEduEventFailed(0),
    AgoraEduEventReady(1),
    AgoraEduEventDestroyed(2),
    AgoraEduEventForbidden(3);
    }
    Copy

    Classroom events. Reported in onCallback.

    AttributesDescription
    AgoraEduEventFailed0: The user fails to enter the classroom.
    AgoraEduEventReady1: The classroom is ready.
    AgoraEduEventDestroyed2: The classroom has been destroyed.
    AgoraEduEventForbidden3: The user is forbidden by the Flexible Classroom cloud service and not allowed to enter the classroom.

    AgoraEduRoleType

    public enum AgoraEduRoleType {
    AgoraEduRoleTypeStudent(2);
    }
    Copy

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

    AttributesDescription
    AgoraEduRoleTypeStudent2: A student.

    AgoraEduRoomType

    public enum AgoraEduRoomType {
    AgoraEduRoomType1V1(0),
    AgoraEduRoomTypeSmall(4),
    AgoraEduRoomTypeBig(2);
    }
    Copy

    The classroom type. Set in AgoraEduLaunchConfig.

    AttributesDescription
    AgoraEduRoomType1V10: One-to-one Classroom. An online teacher gives an exclusive lesson to only one student.
    AgoraEduRoomTypeBig2: 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.
    AgoraEduRoomTypeSmall4: 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.

    AgoraBoardFitMode

    public enum AgoraBoardFitMode {
    Auto,
    Retain;
    }
    Copy

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

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

    StreamState

    data class StreamState (
    var videoState:Int,
    var audioState:Int
    )
    Copy

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

    ParameterDescription
    videoStateWhether to send the video stream:
  • 0: (Default) Do not send the video stream.
  • 1: Send the video stream.
  • audioStateWhether to send the audio stream:
  • 0: (Default) Do not send the audio stream.
  • 1: Send the audio stream.
  • AgoraEduLatencyLevel

    enum class AgoraEduLatencyLevel(val value: Int) {
    AgoraEduLatencyLevelLow(1),
    AgoraEduLatencyLevelUltraLow(2);
    }
    Copy

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

    ParameterDescription
    AgoraEduLatencyLevelLowLow 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.

    AgoraEduMediaOptions

    class AgoraEduMediaOptions(val encryptionConfigs: AgoraEduMediaEncryptionConfigs?)
    Copy

    Media options. Set in AgoraEduLaunchConfig.

    ParameterDescription
    encryptionConfigThe media stream encryption configuration. See AgoraEduMediaEncryptionConfig for details.

    AgoraEduMediaEncryptionConfig

    data class AgoraEduMediaEncryptionConfigs(
    val encryptionKey: String?,
    val encryptionMode: Int
    )
    Copy

    The media stream encryption configuration. Used in AgoraEduMediaOptions.

    ParameterDescription
    modeThe encryption mode. See AgoraEduEncryptMode.
    keyThe encryption key.

    AgoraEduEncryptMode

    enum class AgoraEduEncryptMode(val value: Int) {
    NONE(0),
    AES_128_XTS(1),
    AES_128_ECB(2),
    AES_256_XTS(3),
    SM4_128_ECB(4),
    AES_128_GCM(5),
    AES_256_GCM(6);
    }
    Copy

    The media stream encryption configuration. See AgoraEduMediaEncryptionConfig for details.

    ParameterDescription
    NONENo encryption.
    AES_128_XTS128-bit AES encryption, XTS mode.
    AES_128_ECB128-bit AES encryption, ECB mode.
    AES_256_XTS256-bit AES encryption, XTS mode.
    SM4_128_ECB128-bit ECB encryption, SM4 mode.
    AES_128_GCM128-bit AES encryption, GCM mode.
    AES_256_GCM256-bit AES encryption, GCM mode.

    AgoraEduCourseware

    data class AgoraEduCourseware(
    val resourceName: String?,
    val scenePath: String?,
    val scenes: List<SceneInfo>?,
    val resourceUrl: String?
    ) {
    }
    Copy

    The courseware pre-download configuration. Used in configCoursewares.

    AttributesDescription
    resourceNameThe file name.
    scenePathThe 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.
    scenesA 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.
    resourceUrlThe URL address of the file, such as "https://convertcdn.netless.link/dynamicConvert/{taskUuid}.zip".

    SceneInfo

    public class SceneInfo {
    private int componentCount;
    private Ppt ppt;
    private String name;
    }
    Copy

    The detailed information of a page. Set in AgoraEduCourseware.

    AttributesDescription
    componentCountThe number of pages.
    pptThe detailed information of a converted page. See Ppt.
    nameThe page name.

    Ppt

    public class Ppt {
    private String src;
    private double width;
    private double height;
    }
    Copy

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

    AttributesDescription
    srcThe URL address of the converted page.
    widthThe width (pixel) of the page.
    heightThe height (pixel) of the page.

    AgoraEduRegion

    object AgoraEduRegion {
    const val default = "CN"
    const val cn = "CN"
    const val na = "NA"
    const val eu = "EU"
    const val ap = "AP"
    }
    Copy

    Regions.

    AttributesDescription
    CNMainland China.
    NANorth America.
    EUEurope.
    APAsia Pacific.

    EduVideoEncoderConfig

    data class EduVideoEncoderConfig(
    var videoDimensionWidth: Int = 320,
    var videoDimensionHeight: Int = 240,
    var frameRate: Int = 15,
    var bitrate: Int = 200,
    var mirrorMode: Int = EduMirrorMode.AUTO.value
    )
    Copy

    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).
    ParameterDescription
    widthWidth (pixel) of the video frame.
    heightHeight (pixel) of the video frame.
    frameRateThe frame rate (fps) of the video. The default value is 15.
    bitrateThe bitrate (Kbps) of the video. The default value is 200.
    mirrorModeVideo mirror modes. See EduMirrorMode.

    EduMirrorMode

    enum class EduMirrorMode(val value: Int) {
    AUTO(0),
    ENABLED(1),
    DISABLED(2)
    }
    Copy

    Whether to enable mirror mode. Used in EduVideoEncoderConfig.

    ParameterDescription
    AUTOThe SDK disables mirror mode by default.
    ENABLEDEnable mirror mode.
    DISABLEDDisable mirror mode.
    vundefined