Use Whiteboard Beta

Introduction

The Agora Whiteboard SDK is a JavaScript library loaded by an HTML web page. It also provides a set of simple high-level JavaScript APIs for establishing whiteboard communications with users across the Agora Global Network.

The Agora Whiteboard SDK allows your JavaScript code to:

  • Establish Session – Join and leave the shared Agora sessions (identified by unique channel names), where there may be many global users on a conference together.
  • Set user roles in the shared sessions – host or attendee. Host can draw and annotate on the whiteboard, while attendees have view-only permission.

The application developers can access the Agora Whiteboard service in two ways:

Compatibility

Agora Whiteboard SDK is compatible with all platform SDK versions.

Supported Web Browser

The Agora Whiteboard SDK requires a HTML5-compliant web browser and has been tested and verified on all the following browser types and versions, which are available across a wide range of platforms.

  IE Chrome Safari Firefox Opera
  v10-11 v49-51 v9.1 v46-47 v38
HTTP/ Y Y Y Y Y
HTTPS          

Note

All the browser versions listed have been tested and verified. Earlier versions of these browsers that support HTML5 may work, but have not been verified by Agora.io.

Supported File Formats

You can upload PDFs, office files and pictures in any of the following formats to the whiteboard:

File Format
PDF .pdf
Excel .xls, .xlsx
Word .doc, .docx
PowerPoint .ppt, .pptx
Picture .png, .jpg, .jpeg

Note

When uploading pictures, the format JPEG2000 is not supported.

Known Issue and Limitations

  • Each conference can have no more than one whiteboard instance.
  • The users can use the whiteboard function on the Agora supported platforms including Web, Mac and Windows. On iOS and Android, the users have view-only permission.
  • If your application is on Mac, the file upload function is not supported.This issue is caused by OS X unable to open the panel in WKWebView, and the file upload window cannot popup. Wait for OS X to update.

Get Started

Obtaining SDK

The Agora Native SDK for Android is available from downloads , or contact sales-us@agora.io.

Component Description
./doc Agora Whiteboard SDK Documentation
./client Agora Whiteboard JavaScript library and web demo application
./server Web server-side sample code for Channel Key generation

About keys

This section describes the concepts and use of App ID, App Certificate, Dynamic Key and Channel Key.

Static Key

Each Agora account can create multiple projects, and each project has a unique App ID. Be sure to obtain an App ID, required when you use APIs to access the Agora Global Network. In our network, the App ID sets you apart from others. There is no overlap, even when channels have the same name. However an App ID is a static key, and if someone else illicitly obtains your static App ID, then they can use it for their own Agora Native SDK client applications. If they find out the channel names of your organization, they can even interfere with your communication sessions.

Dynamic Key

Dynamic Key is a more secure user authentication schema for the Agora Native SDK. Dynamic Key is a general name compared with Static Key, and it has different and specific names for different services. The Dynamic Key that the Agora Whiteboard SDK requires is called Channel Key:

Whenever a user tries to enter a channel to access the Agora service, the back-end services use an App ID and an App Certificate to generate a new Channel Key based on the HMAC encryption algorithm. The Channel Key is then passed to the client application. The client application calls the Agora.Whiteboard.join(for web application) or use WebView to access the Agora Whiteboard URL(for non-web application) and passes the encoded Channel Key to the Agora server for the user authentication.

Note

Agora Whiteboard SDK does not support the recording function currently.

Obtaining and Using an App ID

Obtaining an App ID

Each Agora account can create multiple projects, and each project has a unique App ID.

  1. Sign up for a new account at https://dashboard.agora.io/.
  2. Click Add New Project on the Projects page of the dashboard.
  3. Fill in the Project Name and click Submit.
../../_images/create_project.png
  1. Find your App ID under the project that you have created.
Using an App ID

Access the Agora services by using your unique App ID:

Enter the App ID in the web demo application (only for web-application).

Set the key parameter to the value of the App ID when joining a session.

Obtaining and Using a Channel Key

Obtaining an App ID and an App Certificate

Each Agora account can create multiple projects, and each project has a unique App Certificate and App ID.

  1. Log in to https://dashboard.agora.io.

  2. Click Add New Project on the Projects page of the dashboard.

  3. Fill in the Project Name and click Submit. Find the App ID under the project you’ve created.

    ../../_images/create_project.png
  4. Enable the App Certificate for the project.

  1. Click Edit on the top right of the project.

  2. Click Enable to the right of App Certificate. Read the description About App Certificate carefully before you confirm the operation.

    ../../_images/enable_app_cert.png
  3. Click the ‘eye’ icon to view the App Certificate. You can re-click this icon to hide the App Certificate.

    ../../_images/view_app_certificate.png

Note

  • If you want to renew an App Certificate, contact support@agora.io.
  • Keep your App ID on the server and never on any client machine.
  • See the table in Channel Key Structure for App ID use.
Implementing the Channel Key Schema

Integrate the Channel Key scheme into your organization’s signaling service. Agora.io provides sample server-side code covering the following languages: Java, C++, Python, node.js, and so on, which you can use this code directly in your application.

For the sample code, refer to https://github.com/AgoraLab/AgoraDynamicKey.

Using a Channel Key

When a user requests to access the Agora service:

  1. The client application requests authentication from your organization’s signaling server.
  2. The server, upon receiving the request, uses the algorithm provided by Agora.io to generate a Channel Key and then passes the Channel Key back down to the client application.
  3. The Channel Key is based on the App ID, App Certificate, Channel Name, Current Timestamp, Client User ID, Lifespan Timestamp, and so on.
  4. Set the Key parameter to the value of the Channel Key when the client application joins a session.
  5. The Agora server receives the Channel Key and confirms that the call comes from a legal user, and then allows it to access the Agora Global Network.
Increased Security with Channel Key

Whenever a user joins a whiteboard session, the client application must provide a new Channel Key. The signaling server verifies each user identity. The Channel Key uses the HMAC/SHA1 signature schema to increase security for communications within your organization.

Channel Key Structure

The table below outlines the structure of the Channel Key. Connect all fields in the sequence shown.

Field Type Length Description
Version String 3 Channel Key version information
Sign String 40 Hex code for the signature. A 40-byte string calculated by the HMAC algorithm based on inputs including the App Certificate and the following fields:
· Service Type: Visible ASCII string provided by Agora.io. See Service Type.
· App ID: 32-character App ID string.
· Timestamp: The timestamp created when the Channel Key is generated.
· Random Number: A 32-bit integer in hex code; generated upon each query.
· Channel: The channel name specified by the user, maximum length: 64-bytes.
· User ID: The User ID defined by the client.
· Call Expiration Timestamp: The timestamp indicates that from the specific moment the user cannot communicate in the channel any more.
App ID String 32 App ID
Authorized Timestamp Number 10 The timestamp, represented by the number of seconds elapsed since 1-1-1970. The user can use the Channel Key to join a channel within 5 minutes after the Channel Key is generated. If the user does not join a channel after 5 minutes, this Channel Key is no longer valid.
Random Number Integer 8 A 32-bit integer in hex code; generated upon each query.
Call Expiration Timestamp Number 10 Set the value to 0 for no limitation to the time of termination.
Indicates the exact time when a party can no longer use the Agora service (for example, when someone is forced to leave an ongoing call). [1]

Footnotes

[1]When the value is set for Call Expiration Timestamp, it does not mean Channel Key will be expired, but only means the user will be kicked out from the channel. For example, if a conference call is around 1 hour, but if after the call is closed, someone is still in the channel, you will still be charged. By setting this timestamp, the users who have not left the channel after a call is closed will automatically be kicked out.
Service Type
Service Value Description
Session ACS The Whiteboard service provided by Agora.io. For example, when you call the Agora.Whiteboard.join API, use this service type to generate the Channel Key.
Signature Algorithm

The Channel Key encoding uses the industry-standard HMAC/SHA1 approach; libraries are available on most common server-side development platforms, such as node.js, PHP, Python, Ruby and others.

For more information, refer to:

http://en.wikipedia.org/wiki/Hash-based_message_authentication_code

Realizing Whiteboard Function – Web application

Deploying Your Web application

applications using the Agora Whiteboard SDK are standard JavaScript applications. To deploy the application, you need to load the Agora JS library and also need access to the JS extension libraries provided with the SDK. Follow your normal JavaScript hosting procedures when deploying the JavaScript libraries:

  1. Load the Agora JS library:
AgoraWBSDK-1.0.0.js
  1. JS extension libraries are also needed:
vendor-bundle.js

Running the Demo Application

Client

The default sample code only requires your static App ID (which is entered into the demo application web page).

To run the provided demo application:

  1. Ensure that you have a local web server installed, such as Apache, NginX, or Node.js.
  2. Deploy the files under ./client/ to your web server, set the Key value in the file script-host.js and script-guest.js to your App ID, and then launch your http/https service.
  3. Access the demo application page on your web server using one of the browsers listed in Supported Web Browser.

Do the following if you want to run the demo application with a Channel Key:

Note

For more information, see Obtaining and Using a Channel Key.

  1. Set up and launch the key-generation server.
  2. Make an http or https client request for the key-generation server to get a new Channel Key.
  3. In script-host.js and script-guest.js (both under client/js/), replace the Key with the newly generated Channel Key before calling Agora.Whiteboard.join.
Server

This code is only needed if you want to experiment with using the more secure Channel Key. In production environment, you integrate this logic into your own server-side applications and (re)code this in the programming languages you are already using for your server-based functionality.

The sample code is in JavaScript and requires a standard Node.js server:

  1. Install a standard Node.js server within your server or cloud infrastructure.
  2. Run ‘npm install’ under ../server/nodejs/.
  3. Fill in the values of your VENDOR_KEY and SIGN_KEY in ../server/nodejs/DemoServer.js.
  4. Launch the server with ‘node DemoServer.js’.

Realizing the Whiteboard Function – Non-Web application

Non-Web application (on any of the following platforms, iOS, Android, Mac or Windows) developers can use WebView to access the Agora Whiteboard URL service:

Parameter Description Required?
key

Key can be one of the following:

  • App ID: provided by Agora on the Dashboard.
  • Channel Key: the token generated with App ID and App Certificate.

A NodeJS implementation of token-gen algorithm is provided. This is the safest and recommended way to access the Agora Global Network.

Yes
cname

The unique channel name for the Agora whiteboard session.

The following is the supported scope:

a-z,A-Z,0-9,space,! #$%&,()+, -,:;<=.,>? @[],^_,{|},~

Yes
role

User Role

  • host: the organizer
  • guest: the participant

The organizer can control the whiteboard for all the activities, but the participant has view-only rights.

Yes
uinfo

The username to identify the user.

If not specified, the server will generate a random user name.

No
expire If the expiration date not specified, the validity period is 24 hours starting from the moment the channel is created. No
width The width of the whiteboard, and it is 1024 by default. No
height The height of the whiteboard, and it is 768 by default. No