Fastboard quickstart

The Fastboard SDK is the latest generation of the Interactive Whiteboard SDK launched by Agora to help developers quickly build whiteboard applications. The Fastboard SDK simplifies the APIs of the Interactive Whiteboard SDK and adds UI implementations. These improvements enable you to join a room with just a few lines of code and instantly experience real-time interactive collaboration using a variety of rich editing tools. In addition, the Fastboard SDK integrates window-manager and extensions from netless-app, which allows developers to easily extend the functionality of their whiteboard applications and enrich their users' collaboration experience.

This page explains how to quickly join a whiteboard room and experience the interactive whiteboard features using the Fastboard SDK.

Understand the tech

The following figure shows the workflow to join a whiteboard room:

When an app client requests to join a 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 calls createFastRoom and join of the Fastboard SDK to create a FastRoom instance and join the interactive whiteboard room.

Prerequisites

Before proceeding, make sure you meet the following requirements:

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 Agora Console. See Enable and configure Interactive Whiteboard.

Implementations on your app server

Before an app client can join an interactive whiteboard room, your app server needs to call the Agora Restful APIs to create a room, get the room UUID, generate a room token, and pass the room UUID and room token to the app client.

Create a whiteboard room

Call /v5/rooms (POST) on your app server to create a room.

You can use the following Node.js script as a request example:

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 Interactive Whiteboard server returns information about the created room, including uuid, which is the unique identifier of the room. You need to pass in this parameter when an app client joins the room.

The following is a response example:

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

Generate a room token

After creating a room and getting the uuid of the room, your app server needs to generate a room token 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 one of the following methods:

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

You can use the following Node.js script as a request example:

 var request = require('request');
 var options = {
     "method": "POST",
     // Replace <Room UUID> with the uuid of your room
     "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. The following is a response example:

 "NETLESSROOM_YWs9XXXXXXXXXXXZWNhNjk" // Room token

Implementations on the app client

The following sections show how to use the Fastboard SDK to join a whiteboard room from your Android app.

Create an Android project

Follow these steps to create the environment necessary to add whiteboard functionality into your app.

For new projects, in Android Studio, create a Phone and Tablet Android project with an Empty Activity. After creating the project, Android Studio automatically starts gradle sync. Ensure that the sync succeeds before you continue.
In the /Gradle Scripts/build.gradle(Module: <projectname>.app) file, add the following line to the dependencies field to integrate the Fastboard SDK:

_4 dependencies { _4 ... _4 implementation 'com.github.netless-io:fastboard-android:1.2.0' _4 }

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

Create the user interface (UI)

The Fastboard SDK provides FastboardView, which is a whiteboard view with a default UI. Adding it to your project's layout enables users to see the whiteboard view when the app runs.

In /app/res/layout/activity_main.xml, replace the content with the following:

 <?xml version="1.0" encoding="utf-8"?>
 <androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:tools="http://schemas.android.com/tools"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     xmlns:app="http://schemas.android.com/apk/res-auto"
     tools:context=".MainActivity">
     <io.agora.board.fast.FastboardView
         android:id="@+id/fastboard_view"
         android:layout_width="match_parent"
         android:layout_height="match_parent" />
 </androidx.constraintlayout.widget.ConstraintLayout>

Join the whiteboard room

To join the Interactive Whiteboard room, do the following:

Call getFastboard of the FastboardView class to get the Fastboard instance.
Call createFastRoom of the Fastboard class to create the FastRoom instance. When calling createFastRoom, you must pass the following properties in the roomOptions parameter:
- appIdentifier: 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.
- token: The room token used for authentication. The room token must be generated using the room UUID above. See Generate a room token.
- uid: The unique identifier of a user in string format. The maximum length is 1,024 bytes.
- fastRegion: The data center, which must be the same as the data center you chose when creating the room.

In /app/java/com.example.<projectname>/MainActivity, add the following lines:

 package com.example.fastboardquickstart
 import android.content.pm.ActivityInfo
 import androidx.appcompat.app.AppCompatActivity
 import android.os.Bundle
 import android.os.Handler
 import android.widget.Button
 import io.agora.board.fast.FastboardView
 import io.agora.board.fast.model.FastRegion
 import io.agora.board.fast.model.FastRoomOptions
 import java.lang.Exception
 class MainActivity : AppCompatActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         setContentView(R.layout.activity_main)
         // Sets the screen orientation as landscape
         supportActionBar?.hide()
         requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE
          setupFastboard()
     }
         private fun setupFastboard() {
         // Gets the fastboard instance
         val fastboardView = findViewById<FastboardView>(R.id.fastboard_view)
         val fastboard = fastboardView.fastboard
         // Sets room configuration parameters
         val roomOptions = FastRoomOptions(
             "The App Identifier of your whiteboard project",
             "The room UUID",
             "The room Token",
             "The unique identifier of a user",
            FastRegion.US_SV
         )
         // Creates the FastRoom instance
         val fastRoom = fastboard.createFastRoom(roomOptions)
         // Joins the whiteboard room
         fastRoom.join()
     }
 }

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 the following page:

You can select the pencil, text, or shape tools on the left toolbar to write and draw on the whiteboard. When the current page is full, you can click the icon at the bottom to add a new page, and use the arrows to switch pages.

Next steps

After experiencing the basic whiteboard functionality, you can call APIs of the Fastboard SDK to add images, audio, video, and documents to the whiteboard.