Agora Interactive Whiteboard rooms enable users to present ideas, share multi-media content, and collaborate on projects on a shared whiteboard from multiple devices simultaneously.
This article describes how to create a basic project and use the Agora Interactive Whiteboard SDK to implement basic whiteboard features.
The following figure shows the workflow to join an Agora Interactive Whiteboard room.
When an app client requests to join an interactive whiteboard room, the app client and your app server interact with the Agora Interactive Whiteboard server in the following steps:
Create a project in Android Studio.
WhiteBoard
.com.example.whiteboard
.Refer to the following code to add Internet access permission in the AndroidManifest.xml
file:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.whiteboard">
<uses-permission android:name="android.permission.INTERNET" />
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:theme="@style/Theme.WhiteBoard">
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>
Open the build.gradle
file under the root directory of the Android project and perform the following:
allprojects {
repositories {
jcenter()
// Add the following line
maven { url 'https://jitpack.io' }
}
}
Open the build.gradle
file in the app folder of the Android project, and add the following lines:
dependencies {
// Take SDK version 2.15.24 for example
implementation 'com.github.duty-os:white-sdk-android:2.15.24'
}
You can find the latest SDK version number in Release Notes.
Add the following lines to the proguard-rules.pro
file:
# SDK model
-keep class com.herewhite.** { *; }
The Agora Interactive Whiteboard SDK has now been integrated into the Android project. Next, call the core APIs in the SDK to implement basic whiteboard features.
Before an app client requests to join a room, you need to call the Interactive Whiteboard RESTful API on your app server to create a room. See Create a room (POST).
Request example
Refer to the following Node.js script to send an HTTP request:
request
module. You can run the command line npm install request
to install the module.var request = require("request");
var options = {
"method": "POST",
"url": "https://api.netless.link/v5/rooms",
"headers": {
"token": "Your SDK Token",
"Content-Type": "application/json",
"region": "us-sv"
}
body: JSON.stringify({
"isRecord": false
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
If the request is successful, Agora's server for the whiteboard service returns information about the created room, including the uuid
, which is the unique identifier of the room. You need to pass in this parameter when an app client joins the room.
Response example
{
"uuid": "4a50xxxxxx796b", // The Room UUID
"teamUUID": "RMmLxxxxxx15aw",
"appUUID": "i54xxxxxx1AQ",
"isRecord": false,
"isBan": false,
"createdAt": "2021-01-18T06:56:29.432Z",
"limit": 0
}
After creating a room and getting the uuid
of the room, you need to generate a Room Token on your app server and send it to the app client. When an app client joins a room, Agora's server uses the Room Token for authentication.
To generate a Room Token on your app server, you can:
The following examples describe how to use the Interactive Whiteboard RESTful API to generate a Room Token.
Request example
Refer to the following Node.js script to send an HTTP request:
request
module. You can run the command line npm install request
to install the module.var request = require('request');
var options = {
"method": "POST",
// Replace <Room UUID> with your Room UUID
"url": "https://api.netless.link/v5/tokens/rooms/<Room UUID>",
"headers": {
"token": "Your SDK Token",
"Content-Type": "application/json",
"region": "us-sv"
},
body: JSON.stringify({"lifespan":3600000,"role":"admin"})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
If the request is successful, Agora's server returns a Room Token.
Response example
"NETLESSROOM_YWs9XXXXXXXXXXXZWNhNjk" // Room Token
Refer to the following code sample to modify the activity_main.xml
file. After modification, you should see a whiteboard page named com.herewhite.sdk.WhiteboardView
, which is implemented by the whiteboard SDK.
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:id="@+id/activity_main"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical"
tools:context=".MainActivity">
<com.herewhite.sdk.WhiteboardView
android:id="@+id/white"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:visibility="visible" />
</LinearLayout>
Edit the MainActivity.java
file to implement the steps from initializing the SDK to joining a room. You need to pass in the following parameters:
appId
: The App Identifier of the whiteboard project in Agora Console. See Get security credentials for your whiteboard project.uuid
: The Room UUID, the unique identifier of a whiteboard room. See Create a room.uid
: The unique identifier of a user in the string format. The maximum length is 1024 bytes. If you use v2.15.0 and later versions, you must pass in this parameter; if you use versions earlier than v2.15.0, do not pass in this parameter.roomToken
: The Room Token used for authentication. The Room Token must be generated using the Room UUID above. See Generate a Room Token.region
: The data center, which must be the same as the data center you chose when creating the room.package com.example.whiteboard;
import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;
import android.widget.Toast;
import com.herewhite.sdk.RoomParams;
import com.herewhite.sdk.WhiteboardView;
import com.herewhite.sdk.WhiteSdk;
import com.herewhite.sdk.WhiteSdkConfiguration;
import com.herewhite.sdk.Room;
import com.herewhite.sdk.domain.Promise;
import com.herewhite.sdk.domain.SDKError;
import com.herewhite.sdk.domain.MemberState;
public class MainActivity extends AppCompatActivity {
// Pass in the App Identifier
final String appId = "Your App Identifier";
// Pass in the Room UUID
final String uuid = "Room UUID";
// Pass in the Room Token
final String roomToken = "Room Token";
// The unique identifier of a user.
// If you use versions earlier than v2.15.0, do not add this line.
final String uid = "用户 uid";
// Create a WhiteboardView object to implement the whiteboard view
WhiteboardView whiteboardView;
// Create a WhiteSdkConfiguration object to configure the App Identifier and log settings
WhiteSdkConfiguration sdkConfiguration = new WhiteSdkConfiguration(appId, true);
// Set the data center as Silicon Valley, US
sdkConfiguration.setRegion(Region.us);
// Create a RoomParams object to set room parameters used in joining a room.
// If you use versions earlier than v2.15.0, do not pass in uid.
RoomParams roomParams = new RoomParams(uuid, roomToken, uid);
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Assign the whiteboard view in layout to the WhiteboardView object
whiteboardView = findViewById(R.id.white);
// Create a WhiteSdk object to initialize the whiteboard SDK
WhiteSdk whiteSdk = new WhiteSdk(whiteboardView, MainActivity.this, sdkConfiguration);
// Join a room
whiteSdk.joinRoom(roomParams, new Promise<Room>() {
@Override
public void then(Room wRoom) {
MemberState memberState = new MemberState();
// Set the tool to pencil
memberState.setCurrentApplianceName("pencil");
// Set the color tor red
memberState.setStrokeColor(new int[]{255, 0, 0});
// Assign the set-up tool to the current user
wRoom.setMemberState(memberState);
}
@Override
public void catchEx(SDKError t) {
Object o = t.getMessage();
Log.i("showToast", o.toString());
Toast.makeText(MainActivity.this, o.toString(), Toast.LENGTH_SHORT).show();
}
});
}
@Override
protected void onDestroy() {
super.onDestroy();
whiteboardView.removeAllViews();
whiteboardView.destroy();
}
}
Build the project in Android Studio, and run it on a simulator or a physical mobile device. If the project runs successfully, you can see a new page and use your mouse to write and draw on the page.
We provide an open-source sample project Whiteboard-Android that implements the whiteboard room on GitHub. You can download the sample project and refer to the source code.