Embed a custom plugin

In online classroom applications, some customization is often necessary to meet the needs of a particular use-case. Agora provides Widgets to help users develop plug-ins according to their specific needs and embed them into Flexible Classroom.

Widgets are stand-alone plugins that contain interface and functionality. Developers can implement a widget based on customization of the base class, and then register the widget in the Agora Classroom SDK. Agora Classroom SDK supports registering multiple widgets. Widgets can communicate with other widgets, as well as with other plugins in the UI layer.

Implement a custom plugin

This section uses the cloud disk plug-in as an example to introduce the basic steps of implementing a custom plug-in through Widget, and embedding the plug-in in Flexible Classroom. The complete code can be viewed in the CloudClass-Android repository.

Define the class

_29class FCRCloudDiskWidget : AgoraBaseWidget() { _29 override val tag = "AgoraEduNetworkDiskWidget" _29 _29 private var cloudDiskContent: AgoraEduCloudDiskWidgetContent? = null _29 _29 // Initialize Widget _29 // Add your custom UI layout to the container here _29 override fun init(container: ViewGroup) { _29 super.init(container) _29 container.post { _29 widgetInfo?.let { _29 // Instantiate content and add CloudDisk view to container _29 cloudDiskContent = AgoraEduCloudDiskWidgetContent(container, it) _29 } _29 } _29 } _29 _29 // Release used resources _29 override fun release() { _29 cloudDiskContent?.dispose() _29 super.release() _29 } _29 _29 // The content class is only for encapsulation of the code. _29 // Functional details are placed in the content. _29 private inner class AgoraEduCloudDiskWidgetContent(val container: ViewGroup, val widgetInfo: AgoraWidgetInfo) { _29 ...... _29 } _29}

The complete code can be viewed in the CloudClass-Android repository.
Configure the plugin in to register it with the Agora Classroom SDK

_21private fun configPublicCourseware(launchConfig: AgoraEduLaunchConfig) { _21 val courseware0 = CoursewareUtil.transfer(DefaultPublicCoursewareJson.data0) _21 val courseware1 = CoursewareUtil.transfer(DefaultPublicCoursewareJson.data1) _21 val publicCoursewares = ArrayList<AgoraEduCourseware>(2) _21 publicCoursewares.add(courseware0) _21 publicCoursewares.add(courseware1) _21 _21 // custom data for map structure _21 val cloudDiskExtra = mutableMapOf<String, Any>() _21 cloudDiskExtra[publicResourceKey] = publicCoursewares _21 cloudDiskExtra[configKey] = Pair(launchConfig.appId, launchConfig.userUuid) _21 val widgetConfigs = mutableListOf<AgoraWidgetConfig>() _21 widgetConfigs.add( _21 // Instantiate widgetConfig and add it to widgetConfig collection _21 AgoraWidgetConfig(widgetClass = FCRCloudDiskWidget::class.java, widgetId = AgoraWidgetDefaultId.AgoraCloudDisk.id, _21 extraInfo = cloudDiskExtra) _21 ) _21 // Copy widgetConfigs into the SDK's startup parameters. _21 // After calling launch, Smart Class will pass widgetConfigs to internal to complete the registration. _21 launchConfig.widgetConfigs = widgetConfigs _21}
Instantiate and initialize the widget

_90// Add an AgoraWidgetActiveObserver through widgetContext.addWidgetActiveObserver _90// to monitor the activation and deregistration of the Widget _90private val widgetActiveObserver = object : AgoraWidgetActiveObserver { _90 override fun onWidgetActive(widgetId: String) { _90 createWidget(widgetId) _90 } _90 _90 override fun onWidgetInActive(widgetId: String) { _90 destroyWidget(widgetId) _90 } _90} _90 _90private fun createWidget(widgetId: String) { _90 if (teachAidWidgets.contains(widgetId)) { _90 AgoraLog?.w("$tag->'$widgetId' is already created, can not repeat create!") _90 return _90 } _90 AgoraLog?.w("$tag->create teachAid that of '$widgetId'") _90 // Here, the previously registered widgetConfigs are searched by widgetId _90 val widgetConfig = eduContext?.widgetContext()?.getWidgetConfig(widgetId) _90 widgetConfig?.let { config -> _90 _90 // Take widgetClass from widgetConfig and instantiate a Widget object instance through reflection _90 val widget = eduContext?.widgetContext()?.create(config) _90 widget?.let { _90 AgoraLog?.w("$tag->successfully created '$widgetId'") _90 when (widgetId) { _90 CountDown.id -> { _90 (it as? AgoraCountDownWidget)?.getWidgetMsgObserver()?.let { observer -> _90 eduContext?.widgetContext()?.addWidgetMessageObserver(observer, widgetId) _90 } _90 } _90 Selector.id -> { _90 (it as? AgoraIClickerWidget)?.getWidgetMsgObserver()?.let { observer -> _90 eduContext?.widgetContext()?.addWidgetMessageObserver(observer, widgetId) _90 } _90 } _90 Polling.id -> { _90 (it as? AgoraVoteWidget)?.getWidgetMsgObserver()?.let { observer -> _90 eduContext?.widgetContext()?.addWidgetMessageObserver(observer, widgetId) _90 } _90 } _90 } _90 // record widget _90 teachAidWidgets[widgetId] = widget _90 // Create widgetContainer and bind to root Container _90 val widgetContainer = managerWidgetsContainer(allWidgetsContainer = binding.root, widgetId = widgetId) _90 AgoraLog?.i("$tag->successfully created '$widgetId' container") _90 widgetContainer?.let { group -> _90 AgoraLog?.w("$tag->initialize '$widgetId'") _90 // Initialize the Widget _90 widget.init(group) _90 } _90 } _90 } _90} _90 _90private fun destroyWidget(widgetId: String) { _90 // remove from map _90 val widget = teachAidWidgets.remove(widgetId) _90 // remove UIDataProviderListener _90 when (widgetId) { _90 CountDown.id -> { _90 (widget as? AgoraTeachAidCountDownWidget)?.getWidgetMsgObserver()?.let { observer -> _90 eduContext?.widgetContext()?.removeWidgetMessageObserver(observer, widgetId) _90 } _90 } _90 Selector.id -> { _90 (widget as? AgoraTeachAidIClickerWidget)?.getWidgetMsgObserver()?.let { observer -> _90 eduContext?.widgetContext()?.removeWidgetMessageObserver(observer, widgetId) _90 } _90 } _90 Polling.id -> { _90 (widget as? AgoraTeachAidVoteWidget)?.getWidgetMsgObserver()?.let { observer -> _90 eduContext?.widgetContext()?.removeWidgetMessageObserver(observer, widgetId) _90 } _90 } _90 AgoraCloudDisk.id -> { _90 (widget as? AgoraTeachAidVoteWidget)?.getWidgetMsgObserver()?.let { observer -> _90 eduContext?.widgetContext()?.removeWidgetMessageObserver(observer, widgetId) _90 } _90 } _90 } _90 widget?.let { _90 handler.post { it.release() } _90 it.container?.let { group -> _90 managerWidgetsContainer(binding.root, widgetId, group) _90 } _90 } _90}

API Reference

`AgoraBaseWidget` class

// Widget base class
abstract class AgoraBaseWidget {
    // The parent layout of the current Widget
    var container: ViewGroup? = null
    // Information about the current widget
    var widgetInfo: AgoraWidgetInfo? = null
    // Initialize the current widget
    // @param container The parent layout of the current Widget
    open fun init(container: ViewGroup) {
        this.container = container
    }
    // position and size ratio information of the current Widget to the remote
    // @param frame The position and size ratio information of the current Widget
    // @param contextCallback callback listener for synchronous operations
    protected fun updateSyncFrame(frame: AgoraWidgetFrame, contextCallback: EduContextCallback<Unit>? = null) {
        ......
    }
    // @param properties Map of custom room properties in the Widget to be updated. 
    // Need to pass the full path: "a.b.c.d": value
    // @param cause custom update reason
    // @param contextCallback callback listener for update operations
    
    protected fun updateRoomProperties(
            properties: MutableMap<String, Any>,
            cause: MutableMap<String, Any>,
            contextCallback: EduContextCallback<Unit>? = null
    ) {
        ......
    }
    // @param keys The set of key values ​​for custom user properties in the widget that needs to be deleted. 
    // Need to pass the full path: a.b.c.d
    // @param cause custom delete reason
    // @param contextCallback callback listener for delete operation
    protected fun deleteRoomProperties(
            keys: MutableList<String>,
            cause: MutableMap<String, Any>,
            contextCallback: EduContextCallback<Unit>? = null
    ) {
        ......
    }
    // @param properties Map of custom user properties within the Widget to be updated. Need to pass the full path: "a.b.c.d": value
    // @param cause custom update reason
    // @param contextCallback callback listener for update operations
    protected fun updateUserProperties(
        properties: MutableMap<String, Any>,
        cause: MutableMap<String, Any>,
        contextCallback: EduContextCallback<Unit>? = null
    ) {
        ......
    }
    // @param keys The set of key values ​​for custom user properties in the widget that needs to be deleted. Need to pass the full path: a.b.c.d
    // @param cause custom delete reason
    // @param contextCallback callback listener for delete operation
    protected fun deleteUserProperties(
        keys: MutableList<String>,
        cause: MutableMap<String, Any>,
        contextCallback: EduContextCallback<Unit>? = null
    ) {
        ......
    }
    // Send messages from inside the Widget to the outside
    protected fun sendMessage(message: String) {
        ......
    }
    // Widget's position and size changed
    // @params frame Widget position and size scale information
    open fun onSyncFrameUpdated(frame: AgoraWidgetFrame) {
    }
    // Receive messages from outside the widget. The message comes from sendMessageToWidget in widgetContext
    open fun onMessageReceived(message: String) {
    }
    // Callback for the update of local user information
    open fun onLocalUserInfoUpdated(info: AgoraWidgetUserInfo) {
        widgetInfo?.let {
            ......
        }
    }
    // Callback when room information is updated
    open fun onRoomInfoUpdated(info: AgoraWidgetRoomInfo) {
        widgetInfo?.let {
            ......
        }
    }
    // Callback for when the custom room property in the widget is updated
    open fun onWidgetRoomPropertiesUpdated(properties: MutableMap<String, Any>, cause: MutableMap<String, Any>?, keys: MutableList<String>) {
        ......
    }
    // Callback when custom room property in Widget is deleted
    open fun onWidgetRoomPropertiesDeleted(properties: MutableMap<String, Any>, cause: MutableMap<String, Any>?, keys: MutableList<String>) {
        ......
    }
    // Callback for when custom local user properties in Widget are updated
    open fun onWidgetUserPropertiesUpdated(properties: MutableMap<String, Any>,
        cause: MutableMap<String, Any>?,
        keys: MutableList<String>) {
        ......
    }
    // The callback for the deletion of the custom local user attribute in the Widget
    open fun onWidgetUserPropertiesDeleted(properties: MutableMap<String, Any>,
        cause: MutableMap<String, Any>?,
        keys: MutableList<String>) {
        ......
    }
    // Release resources
    open fun release() {
        ......
    }
}

`AgoraWidgetContext` interface

// WidgetContext capability interface
interface AgoraWidgetContext {
    // Create a Widget object instance
    // @param config The configuration information of this Widget object
    // @return Widget instance, if it is empty, it means the creation failed
    fun create(config: AgoraWidgetConfig): AgoraBaseWidget?
    // Get the current position and size ratio information of the Widget
    // @param widgetId Widget's unique identifier
    // @return widget's current position and scale information. The benchmark of the ratio needs to be unified by the developers themselves.
    fun getWidgetSyncFrame(widgetId: String): AgoraWidgetFrame?
    // Get the configuration information of all registered widgets
    fun getWidgetConfigs(): MutableList<AgoraWidgetConfig>
    // Get the configuration information of a registered widget
    // @param widgetId Widget's unique identifier
    fun getWidgetConfig(widgetId: String): AgoraWidgetConfig?
    // Activate a widget.
    // After the operation is successful, you will receive a callback from AgoraWidgetActiveObserver.onWidgetActive
    // @param widgetId Widget's unique identifier
    // @param ownerUserUuid The userUuid of the user who owns the currently activated Widget
    // @param roomProperties initialized room properties
    // @param callback The callback listener for the activation operation
    fun setWidgetActive(widgetId: String, ownerUserUuid: String? = null,
                        roomProperties: Map<String, Any>? = null,
                        callback: EduContextCallback<Unit>? = null)
    // Log out the specified Widget
    // @param widgetId Widget's unique identifier
    // @param isRemove Whether to completely delete all the information of this Widget in the current classroom:
    // - true: delete completely. All information under roomProperties.widgets.'widgetId' and userProperties.widgets.'widgetId' will be deleted
    // - false: Only set roomProperties.widgets.'widgetId'.state to '0', that is, set the current Widget to inactive state. 
    // No matter what value is passed, you will receive the AgoraWidgetActiveObserver.onWidgetInActive callback.
    // @param callback callback listener for logout operation
    fun setWidgetInActive(widgetId: String, isRemove: Boolean = false, callback: EduContextCallback<Unit>? = null)
    // Get the activation state of a widget
    // @param widgetId Widget's unique identifier
    fun getWidgetActive(widgetId: String): Boolean
    // Get the activation status of all registered widgets
    // @param widgetId Widget's unique identifier
    fun getAllWidgetActive(): Map<String, Boolean>
    // Add an AgoraWidgetActiveObserver listener to monitor whether the Widget is active
    fun addWidgetActiveObserver(observer: AgoraWidgetActiveObserver, widgetId: String)
    // Remove an AgoraWidgetActiveObserver listener
    fun removeWidgetActiveObserver(observer: AgoraWidgetActiveObserver, widgetId: String)
    // Add an AgoraWidgetMessageObserver listener to listen for all messages sent by this Widget
    fun addWidgetMessageObserver(observer: AgoraWidgetMessageObserver, widgetId: String)
    // Remove an AgoraWidgetMessageObserver listener
    fun removeWidgetMessageObserver(observer: AgoraWidgetMessageObserver, widgetId: String)
    // Send a message to a widget
    fun sendMessageToWidget(msg: String, widgetId: String)
}

Type definition

// Widget configuration class
data class AgoraWidgetConfig(
    // The custom Widget class corresponding to this WidgetId
    var widgetClass: Class<out AgoraBaseWidget>,
    // Unique identifier for the current Widget
    var widgetId: String,
    // The icon in the unselected (default or inactive) state
    val image: Int? = null,
    // The icon in the selected or activated state
    val selectedImage: Int? = null,
    // Custom data, which is passed to AgoraWidgetInfo.extraInfo after Widget is instantiated
    var extraInfo: Any? = null
)
// Widget information class
data class AgoraWidgetInfo(
    var roomInfo: AgoraWidgetRoomInfo,
    var localUserInfo: AgoraWidgetUserInfo,
    // Unique identifier for the current Widget
    val widgetId: String,
    // Custom data passed in externally
    val extraInfo: Any?,
    // custom room properties in the current widget
    var roomProperties: MutableMap<String, Any>?,
    // Custom local user properties in the current Widget
    var localUserProperties: MutableMap<String, Any>?
)
// Widget's position and size ratio information class
data class AgoraWidgetFrame(
    val x: Float? = null,
    val y: Float? = null,
    val width: Float? = null,
    val height: Float? = null
)
// User information class in Widget
data class AgoraWidgetUserInfo(
        val userUuid: String,
        val userName: String,
        val userRole: Int
)
// Room information class in Widget
data class AgoraWidgetRoomInfo(
        val roomUuid: String,
        val roomName: String,
        val roomType: Int
)

Implement a custom plugin​

API Reference​

AgoraBaseWidget class​

AgoraWidgetContext interface​

Type definition​

Implement a custom plugin

API Reference

`AgoraBaseWidget` class

`AgoraWidgetContext` interface

Type definition