diff --git a/docs/android/v2/how-to-guides/extend-capabilities/whiteboard.mdx b/docs/android/v2/how-to-guides/extend-capabilities/whiteboard.mdx new file mode 100644 index 0000000000..8ddbf12091 --- /dev/null +++ b/docs/android/v2/how-to-guides/extend-capabilities/whiteboard.mdx @@ -0,0 +1,131 @@ +--- +title: Whiteboard +nav: 4.7 +--- + +## Introduction + +The Android SDK provided by 100ms offers support for starting and stopping a whiteboard feature using a `WebView`. +This feature allows users to collaborate on a shared digital whiteboard in real-time. However, it's important to note that for a user to be able to start or view the whiteboard, +their role must have the whiteboard functionality enabled in the 100ms dashboard. + +## Supported Versions + +- Minimum 100ms SDK version it can work with is `2.9.53` + +## WebView configuration for whiteboard + +To make sure whiteboard work correctly with android's `WebView` the follwing configuration needs to be added. + +```kotlin + +webview.apply { + settings?.javaScriptEnabled = true + settings?.domStorageEnabled = true +} + +``` + + + +# Listen for whiteboard updates + +When the `HMSWhiteboardUpdateListener` is triggered, it will receive an instance of `HMSWhiteboardUpdate`, which can be one of two types: + +- `HMSWhiteboardUpdate.Start`: Indicates that the whiteboard has been started. +- `HMSWhiteboardUpdate.Stop`: Indicates that the whiteboard has been stopped. + +```kotlin + +val hmsSDK = HMSSDK + .Builder(application) //application context + .build() + +//setting up whiteboard listener. +hmsSDK.getHmsInteractivityCenter().setWhiteboardUpdateListener(object : HMSWhiteboardUpdateListener { + override fun onUpdate(hmsWhiteboardUpdate: HMSWhiteboardUpdate) { + when(hmsWhiteboardUpdate) { + is HMSWhiteboardUpdate.Start -> //handle start + is HMSWhiteboardUpdate.Stop -> //handle stop + } + } +}) + +``` + +## Start whiteboard update + +When the `HMSWhiteboardUpdateListener` receives an instance of `HMSWhiteboardUpdate.Start`, it indicates that the whiteboard has been started. +In this case, you can load the `url` from `HMSWhiteboard` class into a Webview. This will render the whiteboard on the webview. + +## Stop whiteboard update + +When the `HMSWhiteboardUpdateListener` receives an instance of `HMSWhiteboardUpdate.Stop`, it indicates that the whiteboard has been stopped. +In this case, you can implement the necessary logic to handle the stop of the whiteboard, such as hiding the webview visibility. + +## HMSWhiteboard model + +`HMSWhiteboard` model is returned on both start/stop of the `HMSWhiteboardUpdate`. The model contains information releated to the current whiteboard in the session. + +### Properties +- `id`: A unique identifier for the whiteboard session. +- `title`: The title or name of the whiteboard session +- `owner`: The HMSPeer object representing the owner of the whiteboard session. This property can be null if the owner information is not available. +- `isOwner`: A boolean flag indicating whether the current user has started the whiteboard session. +- `isAdmin`: A boolean flag indicating whether the current user can start/stop the whiteboard session. +- `url`: The link to the whiteboard session. +- `isOpen`: A boolean flag indicating whether the whiteboard session is currently open and active. + + +# Starting/Stopping whiteboard + +## Starting whiteboard +To start a whiteboard, ensure that the role has the appropriate permission and the current whiteboard is not already open. +The callback will be sent as `HMSWhiteboardUpdate.Start` in `setWhiteboardUpdateListener()`. + +> Note: Remember to check if the peer starting whiteboard has owner permission + +```kotlin +val currentWhiteBoardModel : HMSWhiteboard? = //you can get HMSWhiteboard model from HMSWhiteboardUpdate + + +if (currentWhiteBoardModel == null || currentWhiteBoardModel?.isOpen == false) { + localHmsInteractivityCenter.startWhiteboard( + title = , + object : HMSActionResultListener { + override fun onError(error: HMSException) {} + override fun onSuccess() {} + }) +} +``` + +## Stopping whiteboard + +To stop currently opened whiteboard make sure the role has appropriate permission and the current whiteboard session is opened by the user. +The callback will be sent as `HMSWhiteboardUpdate.Stop` in `setWhiteboardUpdateListener()`. + + +```kotlin + +val currentWhiteBoardModel : HMSWhiteboard? = //you can get HMSWhiteboard model from HMSWhiteboardUpdate + +//early exit if the whiteboard is already closed and the peer didn't start the whiteboard +if (currentWhiteBoardModel?.isOpen == true && currentWhiteBoardModel.isOwner.not()) +return + +if (currentWhiteBoardModel?.isOpen == true) { + localHmsInteractivityCenter.stopWhiteboard(object : HMSActionResultListener{ + override fun onError(error: HMSException) {} + override fun onSuccess() {} + }) +} + +``` + +If the `isOwner` is true in `HMSWhiteboard` model then user has to refresh and close the `WebView` to make the whiteboard session stop. + +> Note: Only owner can close the currently opened whiteboard session + +```kotlin + webview?.loadUrl(") +``` \ No newline at end of file