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：

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

Prerequisites

Android Studio
Android API level 19 or higher
A valid Agora account
An Agora project with the Interactive Whiteboard enabled. Get the app identifier and SDK token from the Agora Console. See Enable and configure Interactive Whiteboard

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:

<?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>

Get Interactive Whiteboard SDK

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

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

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

Prevent code obfuscation

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

# SDK model
-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.

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 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

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

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:

Use code. See Generate a Token from your app server. (Recommended)
Call the Interactive Whiteboard RESTful API. See Generate a Room Token (POST).

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.

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

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.

<?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>

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.

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