iframe on Web, a WebView on native platforms) and it’s ready to use. Stroke sync goes through the whiteboard’s own signaling channel, so it doesn’t use any of the channel’s tracks and doesn’t affect audio or video.
So integrating the whiteboard really comes down to two things: getting a page URL with an auth code, and deciding when to show it.
Boards and channels
A whiteboard is identified byboard (the board ID), which has the same character set restrictions as channel names. Everyone using the same board is on the same board.
board isn’t strictly bound to a channel; both usages work:
A whiteboard is created automatically the first time access is granted; you don’t need to create it in advance.
Two ways to open it
Both paths open the same page; the only difference is where the auth code comes from. Users in the channel only need path A and don’t have to call the server API.
Path A: Users in the channel use it directly (recommended)
The join channel response already includes a ready-made whiteboard URL. The auth code is that user’ssid for this session, and board is the channel name. Embed it as is—no extra calls.
How to get it on each platform:
The join channel responses of iOS (RTCEngineKit), Windows, and the C SDK don’t expose this field; use path B on those platforms.
Path B: Your backend issues an auth code
Use this when people who aren’t in the channel also need the whiteboard, or for a standalone whiteboard whoseboard differs from the channel name.
The uid / name in the request determine the collaborator cursor and author name shown on the whiteboard. For endpoint details, see Server API · Whiteboard.
URL parameters
You can append these query parameters to the page URL. The URL from path A already includes the first four:no_menu / no_tool / readonly only set the initial state when the page opens. To change them during the call (for example, temporarily taking away someone’s pen and giving it back later), call the corresponding window method in the host APIs; changing the URL has no effect.Overlay annotation mode
overlay=1 makes the whiteboard semi-transparent over the shared desktop video for annotation. The canvas is fixed at 1920×1080 and zooming is disabled—all clients must share the same coordinate system so strokes land on the same spot of the desktop content. The host needs to call window.setReceiverScreenSize(w, h) to tell the whiteboard the local screen size.
Don’t add this parameter for a regular interactive whiteboard: it hides the main menu and makes the background nearly fully transparent.
Permissions: a single switch
Whether someone can draw is controlled in one place only:readonly=1 in the URL is only the initial value).
Multi-page whiteboards and page following
The whiteboard supports multiple pages, and the page list syncs automatically across clients—when anyone creates, deletes, or renames a page, everyone else sees it. If you use 移动到页面 (Move to page) in the context menu to move a shape to another page, others can see it on that page too. The page-following rule is simple: when someone who can draw turns the page, everyone else follows.
There’s no concept of host or roles—control over page turning follows who can draw, so you only need to manage
setReadonly. People who join midway automatically align to the page everyone is currently on; you don’t need to do anything extra.
When several people can draw at once, whoever turned the page last wins. This is intentional: a shared whiteboard should keep everyone on the same page. If you really want one client to browse freely without disturbing others, set it to readonly.
“Which page we’re on” is session state and isn’t persisted—a new call doesn’t inherit the page the previous call stopped on. The pages themselves and their strokes stay on the board until the whiteboard is destroyed.
Bringing the whole channel into the whiteboard
Recommended approach (this is what the Web Demo does): record the state in custom channel properties + notify with a custom message. You need both—the message notifies the people already there, and the property lets people who join midway restore the current state. The message body broadcast by your backend:status:
white-board/destroy, set props.white_board back to false, and broadcast status: 0.
You define the value of
action; white_board here is just the Demo’s convention. For events and data structures, see Events (Chinese); for the broadcast endpoint, see Server API · Channel.Embedding in a native WebView
The whiteboard page is a standard web app, and the WebView must allow JavaScript. Beyond that, there are two sets of host APIs: H5 calls the host (you need to inject implementations in the WebView):
The host calls H5 (call via
evaluateJavascript / evaluateJavaScript; available only after the page finishes loading):
These methods are attached only after the page finishes loading (
onPageFinished / didFinish navigation); calling them earlier gives undefined. We recommend calling setReadonly once in the load-finished callback to initialize according to the user’s business role, then calling it again whenever permissions change—no page reload needed.The name
AndroidInterface is historical; iOS and Windows mount under the same name.iframe, so use the <web-view> component to host the page. It fills the whole page, and the whiteboard domain must first be configured as a business domain in the Mini Program admin console.
For a full Android example (WebView configuration, JS Bridge implementation, and handling onShowFileChooser when inserting images), see Android · Whiteboard integration (Chinese).
Lifecycle and destruction
Use
white-board/exist to check whether a board still exists—for example, to decide whether to show an “Open whiteboard” entry, or to confirm a destroy took effect.
FAQ
It opens a blank page / says unauthorized Usually an auth code problem: expired (more than 1 hour old), already used (a code can only connect once), or shared by multiple clients. Get a new one every time you open the whiteboard. Two people are drawing on different boards Check that both use the sameboard. With path A, board always equals the channel name, so it can’t go wrong; with path B, your backend passes it in, and it’s easy to pass the wrong one in multi-channel scenarios.
The whiteboard content is gone after the call ends
board was the channel name, so destroying the channel also destroyed the board. To keep the content, use a standalone board and manage when to destroy it yourself.
What image formats can the whiteboard insert?
JPEG / PNG / GIF / WebP / SVG, up to 3 MB each; video isn’t supported. SVG is vector, so it stays sharp when zoomed, and works better than bitmaps for icons and drawings. On native platforms, to let users pick images you also need to handle onShowFileChooser in the WebView (see Android · Whiteboard integration (Chinese)); we recommend compressing images to under 1 MB before returning them.
Can I stream the whiteboard to clients that can’t embed a WebView?
The whiteboard itself doesn’t produce a media stream. If the other side can’t host H5, capture the whiteboard on a client that can and publish it as a custom video track; see Custom tracks (Chinese).
Related
- Server API · Whiteboard—the three endpoints for grant, existence check, and destroy
- Server API · Channel—channel properties and custom message broadcasts
- Key concepts—channels, users, and tracks