Skip to main content

SDK quickstart

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 Interactive Whiteboard SDK to implement basic whiteboard features.

Understand the tech

The following figure shows the workflow to join an Interactive Whiteboard room.

When an app client requests to join an Interactive Whiteboard room, the app client and your app server interact with the Interactive Whiteboard server in the following steps:

  1. The app server sends a request with the SDK token to the Interactive Whiteboard server to create a whiteboard room.
  2. The Interactive Whiteboard server returns the room UUID to the app server when a room is created successfully.
  3. The app server generates a room token using the returned room UUID and sends the room token and UUID to the app client.
  4. The app client initializes a Interactive Whiteboard SDK instance with the App Identifier received from the Agora Console.
  5. The app client calls a method to join the Interactive Whiteboard room using the room UUID and room token.

Prerequisites

Create an Android project

Create a project in Android Studio.

  • Set the project name as WhiteBoard.
  • Set the package name as com.example.whiteboard.
  • Select Empty Activity.
  • Select API 19 for Minimum SDK.

Add Android device permission

Refer to the following code to add Internet access permission in the AndroidManifest.xml file:


_22
<?xml version="1.0" encoding="utf-8"?>
_22
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
_22
package="com.example.whiteboard">
_22
_22
<uses-permission android:name="android.permission.INTERNET" />
_22
_22
<application
_22
android:allowBackup="true"
_22
android:icon="@mipmap/ic_launcher"
_22
android:label="@string/app_name"
_22
android:roundIcon="@mipmap/ic_launcher_round"
_22
android:supportsRtl="true"
_22
android:theme="@style/Theme.WhiteBoard">
_22
<activity android:name=".MainActivity">
_22
<intent-filter>
_22
<action android:name="android.intent.action.MAIN" />
_22
<category android:name="android.intent.category.LAUNCHER" />
_22
</intent-filter>
_22
</activity>
_22
</application>
_22
_22
</manifest>

Get Interactive Whiteboard SDK

Open the build.gradle file in the app folder of the Android project, and add the following lines:


_4
dependencies {
_4
// Replace <version> appropriate values for the latest release. For example, 2.16.21
_4
dependencies { implementation 'com.github.netless-io:whiteboard-android:<version>' }
_4
}

You can find the latest SDK version number in Release Notes.

Prevent code obfuscation

Add the following lines to the proguard-rules.pro file:


_2
# SDK model
_2
-keep class com.herewhite.** { *; }

Implement whiteboard features

Interactive Whiteboard SDK has now been integrated into the Android project. Next, call the core APIs in the SDK to implement basic whiteboard features.

1. Create a room

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:

Before sending an HTTP request using Node.js, make sure that you have installed the request module. You can run the command line npm install request to install the module.

_17
var request = require("request");
_17
var options = {
_17
"method": "POST",
_17
"url": "https://api.netless.link/v5/rooms",
_17
"headers": {
_17
"token": "Your SDK Token",
_17
"Content-Type": "application/json",
_17
"region": "us-sv"
_17
}
_17
body: JSON.stringify({
_17
"isRecord": false
_17
})
_17
};
_17
request(options, function (error, response) {
_17
if (error) throw new Error(error);
_17
console.log(response.body);
_17
});

If the request is successful, Agora's server for the Interactive Whiteboard 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


_9
{
_9
"uuid": "4a50xxxxxx796b", // The Room UUID
_9
"teamUUID": "RMmLxxxxxx15aw",
_9
"appUUID": "i54xxxxxx1AQ",
_9
"isRecord": false,
_9
"isBan": false,
_9
"createdAt": "2021-01-18T06:56:29.432Z",
_9
"limit": 0
_9
}

2. Generate a Room Token

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:

Before sending an HTTP request using Node.js, make sure that you have installed the request module. You can run the command line npm install request to install the module.

_17
var request = require('request');
_17
var options = {
_17
"method": "POST",
_17
// Replace <Room UUID> with your Room UUID
_17
"url": "https://api.netless.link/v5/tokens/rooms/<Room UUID>",
_17
"headers": {
_17
"token": "Your SDK Token",
_17
"Content-Type": "application/json",
_17
"region": "us-sv"
_17
},
_17
body: JSON.stringify({"lifespan":3600000,"role":"admin"})
_17
_17
};
_17
request(options, function (error, response) {
_17
if (error) throw new Error(error);
_17
console.log(response.body);
_17
});

If the request is successful, Agora's server returns a Room Token.

Response example


_1
"NETLESSROOM_YWs9XXXXXXXXXXXZWNhNjk" // Room Token

3. Create user interface

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 Interactive Whiteboard SDK.


_16
<?xml version="1.0" encoding="utf-8"?>
_16
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
_16
xmlns:tools="http://schemas.android.com/tools"
_16
android:id="@+id/activity_main"
_16
android:layout_width="match_parent"
_16
android:layout_height="match_parent"
_16
android:orientation="vertical"
_16
tools:context=".MainActivity">
_16
_16
<com.herewhite.sdk.WhiteboardView
_16
android:id="@+id/white"
_16
android:layout_width="match_parent"
_16
android:layout_height="match_parent"
_16
android:visibility="visible" />
_16
_16
</LinearLayout>

4. Initialize the Interactive Whiteboard SDK and join a room

Edit the MainActivity.java file to implement the steps from initializing the Interactive Whiteboard SDK to joining a room. You need to pass in the following parameters:

  • appId: The App Identifier of the Interactive Whiteboard project in Agora Console. See Get security credentials for your Interactive 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.

_77
package com.example.whiteboard;
_77
import androidx.appcompat.app.AppCompatActivity;
_77
_77
import android.os.Bundle;
_77
import android.util.Log;
_77
import android.widget.Toast;
_77
_77
import com.herewhite.sdk.RoomParams;
_77
import com.herewhite.sdk.WhiteboardView;
_77
import com.herewhite.sdk.WhiteSdk;
_77
import com.herewhite.sdk.WhiteSdkConfiguration;
_77
import com.herewhite.sdk.Room;
_77
import com.herewhite.sdk.domain.Promise;
_77
_77
import com.herewhite.sdk.domain.SDKError;
_77
import com.herewhite.sdk.domain.MemberState;
_77
_77
public class MainActivity extends AppCompatActivity {
_77
_77
// Pass in the App Identifier
_77
final String appId = "Your App Identifier";
_77
// Pass in the Room UUID
_77
final String uuid = "Room UUID";
_77
// Pass in the Room Token
_77
final String roomToken = "Room Token";
_77
// The unique identifier of a user.
_77
// If you use versions earlier than v2.15.0, do not add this line.
_77
final String uid = "用户 uid";
_77
_77
_77
// Create a WhiteboardView object to implement the whiteboard view
_77
WhiteboardView whiteboardView;
_77
// Create a WhiteSdkConfiguration object to configure the App Identifier and log settings
_77
WhiteSdkConfiguration sdkConfiguration = new WhiteSdkConfiguration(appId, true);
_77
// Set the data center as Silicon Valley, US
_77
sdkConfiguration.setRegion(Region.us);
_77
// Create a RoomParams object to set room parameters used in joining a room.
_77
// If you use versions earlier than v2.15.0, do not pass in uid.
_77
RoomParams roomParams = new RoomParams(uuid, roomToken, uid);
_77
_77
@Override
_77
protected void onCreate(Bundle savedInstanceState) {
_77
super.onCreate(savedInstanceState);
_77
setContentView(R.layout.activity_main);
_77
// Assign the whiteboard view in layout to the WhiteboardView object
_77
whiteboardView = findViewById(R.id.white);
_77
// Create a WhiteSdk object to initialize the whiteboard SDK
_77
WhiteSdk whiteSdk = new WhiteSdk(whiteboardView, MainActivity.this, sdkConfiguration);
_77
// Join a room
_77
whiteSdk.joinRoom(roomParams, new Promise<Room>() {
_77
@Override
_77
public void then(Room wRoom) {
_77
MemberState memberState = new MemberState();
_77
// Set the tool to pencil
_77
memberState.setCurrentApplianceName("pencil");
_77
// Set the color tor red
_77
memberState.setStrokeColor(new int[]{255, 0, 0});
_77
// Assign the set-up tool to the current user
_77
wRoom.setMemberState(memberState);
_77
}
_77
_77
@Override
_77
public void catchEx(SDKError t) {
_77
Object o = t.getMessage();
_77
Log.i("showToast", o.toString());
_77
Toast.makeText(MainActivity.this, o.toString(), Toast.LENGTH_SHORT).show();
_77
}
_77
});
_77
}
_77
_77
@Override
_77
protected void onDestroy() {
_77
super.onDestroy();
_77
whiteboardView.removeAllViews();
_77
whiteboardView.destroy();
_77
}
_77
}

Build and run the project

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.

Reference

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.