Agora Interactive Whiteboard Web SDK API Reference

Index

Classes

Interfaces

Type aliases

Variables

Functions

Type aliases

BroadcastState

BroadcastState: { broadcasterId?: number; mode: ViewMode }

The view state of the local user, including the user information of the host (if any) in the room.

Type declaration

Optional broadcasterId?: number

The user ID of the host. This property is undefined if there is no host in the room.
mode: ViewMode

The view mode of the user.

Camera

Camera: { centerX: number; centerY: number; scale: number }

View description.

Type declaration

centerX: number

The X coordinate of the center of the view in the world coordinate system (taking the center of the initial whiteboard as the origin).
centerY: number

The Y coordinate of the center of the view in the world coordinate system (taking the center of the initial whiteboard as the origin).
scale: number

The scale factor of the view.

CameraBound

CameraBound: { centerX?: number; centerY?: number; damping?: number; height?: number; maxContentMode?: ContentMode; minContentMode?: ContentMode; width?: number }

The CameraBound type is used to set the viewable area.

Within the viewable area, the user can flexibly move or zoom the view. When the user tries to move the view beyond the viewable area, the SDK automatically drags the view back into the viewable area.

Type declaration

Optional centerX?: number

The X coordinate of the center of the viewable area in the world coordinate system (taking the center of the initial whiteboard as the origin). The default value is 0.0.
Optional centerY?: number

The Y coordinate of the center of the viewable area in the world coordinate system (taking the center of the initial whiteboard as the origin). The default value is 0.0.
Optional damping?: number
The resistance coefficient. The value range is [0.0,1.0], and the default is 0.75. The higher the value, the larger the resistance felt by the user when they move or scale up the view beyond the viewable area.
- 0.0: The user feels no resistance when moving or scaling up the view beyond the viewable area. Once the user stops moving or scaling up, the view returns to its original position.
- 1.0: The user cannot move or scale up the view beyond the viewable area.
Optional height?: number

The height (pixels) of the viewable area. The default value is Infinity, implying that the viewable area has no boundaries.
Optional maxContentMode?: ContentMode

The maximum scale factor of the viewable area. If you do not set this property, there is no upper limit on the scale factor.
Optional minContentMode?: ContentMode

The minimum scale factor of the viewable area. If you do not set this property, there is no lower limit on the scale factor.
Optional width?: number

The width (pixels) of the viewable area. The default value is Infinity, implying that the viewable area has no boundaries.

CameraState

CameraState: Camera & { height: number; width: number }

since

2.10.0

The state of the view. This type inherits Camera and adds the following properties:

width: number

The width of the view.
height: number

The height of the view.

Color

Color: number[]

Color in RGB format. For example, [0, 0, 255] represents blue.

ConstructRoomParams

ConstructRoomParams: { cameraBound?: CameraBound; cursorAdapter?: CursorAdapter; disableAutoResize?: boolean; disableCameraTransform?: boolean; disableOthersSelectingBox?: boolean; invisiblePlugins?: ReadonlyArray<InvisiblePluginClass<string, any, any>>; wrappedComponents?: WrappedComponents }

Basic configuration for Room objects.

Type declaration

Optional cameraBound?: CameraBound

Sets the viewable area, within which the user can flexibly move or zoom the view.

The default value is undefined, implying that the viewable area has no boundaries.
Optional cursorAdapter?: CursorAdapter

Sets the cursor adaptor.
Optional disableAutoResize?: boolean
Whether to disable the auto-resize function:
- true: Disable the auto-resize function. In this case, you need to call refreshViewSize every time the size of the view changes.
- false: (Default) Enable the auto-resize function.
Optional disableCameraTransform?: boolean
Whether to disable the user from adjusting (moving or zooming) the view through touch screen gestures or mouses:
- true: Disable the user from adjusting the view.
- false: (Default) Enable the user to adjust the view.
This property does not affect the use of the setCameraBound, moveCamera, andmoveCameraToContain methods.
Optional disableOthersSelectingBox?: boolean
Whether to disable the highlighted box when another user puts their cursor on an object on the whiteboard:
since
2.12.0
- true: Disable the highlighted box.
- false: Enable the highlighted box.
This property does not affect the highlighted box of the local user.
Optional invisiblePlugins?: ReadonlyArray<InvisiblePluginClass<string, any, any>>

Invisible plugins.
Optional wrappedComponents?: WrappedComponents

An array of React.ComponentType objects, which is used to package the whiteboard view. The default value is [].

ContentMode

ContentMode: (screenSize: Size, boundSize: Size) => number

The actual scale factor.

param: The size of the user's screen.
param: The current size of the viewable area.
returns: The scale factor calculated based on screenSize and boundSize.

Type declaration

- (screenSize: Size, boundSize: Size): number
- Parameters
  - screenSize: Size
  - boundSize: Size
  Returns number

ConversionResponse

ConversionResponse: { failedReason?: string; progress: Progress; status: Status; type: ConversionType; uuid: string }

The HTTP response returned by the server when you Query file conversion progress.

Type declaration

Optional failedReason?: string

The reason why the file-conversion task fails.
progress: Progress

Details about the file-conversion progress.
status: Status

The status of the file-conversion task.
type: ConversionType

The type of the file-conversion task.
uuid: string

The unique identifier (UUID) of the file-conversion task.

ConvertedFile

ConvertedFile: { conversionFileUrl: string; height: number; preview?: string; width: number }

The image or dynamic PPT slide generated by file conversion.

Type declaration

conversionFileUrl: string

The URL address of the image, or the URI address of the dynamic PPT slide.
height: number

The height (px) of the image or dynamic PPT slide.
Optional preview?: string

The URL address of the preview for the image or dynamic PPT slide.
width: number

The width (px) of the image or dynamic PPT slide.

CursorDescription

CursorDescription: { height: number; width: number; x: number; y: number }

Cursor description.

Type declaration

height: number

The height of the cursor icon.
width: number

The width of the cursor icon.
x: number

The X coordinate of the center of the area the cursor is pointing to (taking the upper left corner of the cursor icon as the origin).
y: number

The Y coordinate of the center of the area the cursor is pointing to (taking the upper left corner of the cursor icon as the origin).

DisplayerCallbacks

DisplayerCallbacks: { onCatchErrorWhenAppendFrame: (userId: number, error: Error) => void; onCatchErrorWhenRender: (error: Error) => void; onEnableWriteNowChanged: (enableWriteNow: boolean) => void; onHandToolActive: (active: boolean) => void; onPPTMediaPause: (shapeId: string, type: MediaType) => void; onPPTMediaPlay: (shapeId: string, type: MediaType) => void; onPPTMediaPlayError: (shapeId: string, type: MediaType, error: Error) => void; onRenderDuration: (renderDuration: number) => void; onSliceChanged: (slice: string) => void }

Callbacks for Displayer objects.

Type declaration

onCatchErrorWhenAppendFrame: (userId: number, error: Error) => void
- - (userId: number, error: Error): void
  - Reports the error occurred during the synchronization of a user's operations.
    
    Parameters
    - userId: number
      
      The user ID of the user.
    - error: Error
      
      An error message.
    Returns void
onCatchErrorWhenRender: (error: Error) => void
- - (error: Error): void
  - Reports the error occurred in rendering.
    
    Parameters
    - error: Error
      
      An error message.
    Returns void
onEnableWriteNowChanged: (enableWriteNow: boolean) => void
- - (enableWriteNow: boolean): void
  - since
    
    2.10.0
    
    Occurs when the user's write permission changes:
    
    Parameters
    - enableWriteNow: boolean
      Whether the user currently has write permission:
      
      true: The user has write permission.
      
      false: The user does not have write permission.
    Returns void
onHandToolActive: (active: boolean) => void
- - (active: boolean): void
  - Reports whether the hand tool is enabled.
    
    Parameters
    - active: boolean
      Whether the hand tool is enabled:
      
      true: The hand tool is enabled.
      
      false: The hand tool is disabled.
    Returns void
onPPTMediaPause: (shapeId: string, type: MediaType) => void
- - (shapeId: string, type: MediaType): void
  - Occurs when a media file in the dynamic PPT slide stops playing.
    
    Parameters
    - shapeId: string
      
      The ID of the shape where the media file is inserted.
    - type: MediaType
      
      The type of the media file.
    Returns void
onPPTMediaPlay: (shapeId: string, type: MediaType) => void
- - (shapeId: string, type: MediaType): void
  - Occurs when a media file in the dynamic PPT slide starts playing.
    
    Parameters
    - shapeId: string
      
      The ID of the shape where the media file is inserted.
    - type: MediaType
      
      The type of the media file.
    Returns void
onPPTMediaPlayError: (shapeId: string, type: MediaType, error: Error) => void
- - (shapeId: string, type: MediaType, error: Error): void
  - Reports exceptions that occur during the playing of the media file in a dynamic PPT slide.
    
    Parameters
    - shapeId: string
      
      The ID of the shape where the media file is inserted.
    - type: MediaType
      
      The type of the media file. See MediaType.
    - error: Error
      
      An error message.
    Returns void
onRenderDuration: (renderDuration: number) => void
- - (renderDuration: number): void
  - Reports the rendering duration.
    
    Parameters
    - renderDuration: number
      
      The rendering duration.
    Returns void
onSliceChanged: (slice: string) => void
- - (slice: string): void
  - Occurs when the current slice changes.
    
    Parameters
    - slice: string
      
      The unique identifier (UUID) of the slice.
    Returns void

DisplayerState

DisplayerState: { cameraState: CameraState; globalState: GlobalState; roomMembers: ReadonlyArray<RoomMember>; sceneState: SceneState }

DisplayerState is used by Room objects.

Type declaration

cameraState: CameraState

The state of the current view.

since

2.10.0
globalState: GlobalState

The global state of the room. See GlobalState.
roomMembers: ReadonlyArray<RoomMember>

The states of all the users in interactive mode (the users who have read and write permissions on the whiteboard).
sceneState: SceneState

The state of the current scene.

Event

Event: { authorId: number; event: string; payload: any; phase: EventPhase; scope: Scope }

Customized events.

Type declaration

authorId: number

The user ID of the event trigger. If it is a system event, the user ID is AdminObserverId.
event: string

The name of the customized event.
payload: any

The content of the customized event.
phase: EventPhase

The state of the customized event.
scope: Scope

The scope of the customized event.

EventFilter

EventFilter: (event: Event) => boolean

The filter for an event.

Type declaration

- (event: Event): boolean
- Parameters
  - event: Event
  Returns boolean

EventListener

EventListener: (event: Event) => void

The listener for an event.

Type declaration

- (event: Event): void
- Parameters
  - event: Event
  Returns void

EventsListener

EventsListener: (events: Event[]) => void

The listener for a group of events.

Type declaration

- (events: Event[]): void
- Parameters
  - events: Event[]
  Returns void

FloatBarOptions

FloatBarOptions: { colors: ReadonlyArray<Readonly<Color>> }

Floating bar configuration.

Type declaration

colors: ReadonlyArray<Readonly<Color>>

The color palette of the floating bar.

GlobalState

GlobalState: {}

The globalState object is a public global variable.

All users in the room can read the globalState object, while users in interactive mode can modify the globalState object. The modified globalState object will be updated to all users in the room immediately.

Type declaration

HotKey

HotKey: string | HotKeyDescription | ReadonlyArray<string | HotKeyDescription> | HotKeyChecker

Customized hotkeys.

HotKeyChecker

HotKeyChecker: (event: HotKeyEvent, kind: KeyboardKind) => boolean

Hotkey checker.

param

The event of the customized hotkey.

param

The keyboard type.

returns

Whether the hotkey is the customized hotkey:

true: The hotkey is the customized hotkey.
false: The hotkey is not the customized hotkey.

Type declaration

- (event: HotKeyEvent, kind: KeyboardKind): boolean
- Parameters
  - event: HotKeyEvent
  - kind: KeyboardKind
  Returns boolean

HotKeyDescription

HotKeyDescription: { altKey: boolean | null; ctrlKey: boolean | null; key: string; shiftKey: boolean | null }

Description of the customized hotkey.

Type declaration

altKey: boolean | null

Whether the Alt key is used.
ctrlKey: boolean | null

Whether the Ctrl key is used.
key: string

The specified key.
shiftKey: boolean | null

Whether the Shift key is used.

HotKeyEvent

HotKeyEvent: { altKey: boolean; ctrlKey: boolean; key: string; kind: "KeyDown" | "KeyUp"; nativeEvent?: KeyboardEvent; shiftKey: boolean }

The event of the customized hotkey.

Type declaration

altKey: boolean

Whether the Alt key is used.
ctrlKey: boolean

Whether the Ctrl key is used.
key: string

The specified key.
kind: "KeyDown" | "KeyUp"
The event of the hotkey:
- KeyDown: The hotkey is pressed.
- KeyUp: The hotkey is released.
Optional nativeEvent?: KeyboardEvent

The browser event.
shiftKey: boolean

Whether the Shift key is used.

HotKeys

HotKeys: { changeToArrow: HotKey; changeToClick: HotKey; changeToEllipse: HotKey; changeToEraser: HotKey; changeToHand: HotKey; changeToLaserPointer: HotKey; changeToPencil: HotKey; changeToRectangle: HotKey; changeToSelector: HotKey; changeToStraight: HotKey; changeToText: HotKey; copy: HotKey; delete: HotKey; duplicate: HotKey; lock: HotKey; paste: HotKey; redo: HotKey; undo: HotKey }

The action triggered by the hotkey.

Type declaration

changeToArrow: HotKey

Switch to arrow tool (arrow).
changeToClick: HotKey

Switch to clicker (clicker).
changeToEllipse: HotKey

Switch to ellipse tool (ellipse).
changeToEraser: HotKey

Switch to eraser (eraser).
changeToHand: HotKey

Switch to hand tool (hand).
changeToLaserPointer: HotKey

Switch to laser pointer (laserPointer).
changeToPencil: HotKey

Switch to pen tool (pencil).
changeToRectangle: HotKey

Switch to rectangle tool (rectangle).
changeToSelector: HotKey

Switch to selection tool (selector).
changeToStraight: HotKey

Switch to line tool (straight).
changeToText: HotKey

Switch to text tool（text).
copy: HotKey

Copy.
delete: HotKey

Delete.
duplicate: HotKey

Copy and paste.
lock: HotKey

Lock the zoom level.
paste: HotKey

Paste.
redo: HotKey

Redo.
undo: HotKey

Undo.

Identifier

Identifier: string

The unique identifier of a component plugin.

ImageInformation

ImageInformation: { centerX: number; centerY: number; height: number; locked: boolean; uniformScale?: boolean; uuid: string; width: number }

Image description.

Type declaration

centerX: number

The X coordinate of the center of the image in the world coordinate system (taking the center of the initial whiteboard as the origin).
centerY: number

The Y coordinate of the center of the image in the world coordinate system (taking the center of the initial whiteboard as the origin).
height: number

The height (px) of the image. If the height of the image is greater than the boundary of the view, then users cannot see the excess part.
locked: boolean
Whether the image is locked:
- true: Locked. When an image is locked, users cannot move or zoom the image.
- false: Unlocked.
Optional uniformScale?: boolean
Whether the image can only be resized proportionately.
since
2.12.0
- true: The image can only be resized proportionately.
- false: The image can be resized disproportionately.
uuid: string

The unique identifier (UUID) of the image.
width: number

The width (px) of the image. If the width of the image is greater than the boundary of the view, then users cannot see the excess part.

International

International: { displayNote?: string; displaySidebar?: string; hideNote?: string; hideSidebar?: string; jumpTo?: string; nextPage?: string; nextStep?: string; pageNumber?: string; prePage?: string; preStep?: string; resetCurrentPPTAnimation?: string; resetCurrentSlideAnimation?: string }

This type is used to add text to the menu on the PPT preview page. You can pass in the letters to be displayed, for example, "Next".

Type declaration

Optional displayNote?: string

The text for "display slide notes".
Optional displaySidebar?: string

The text for "display the sidebar".
Optional hideNote?: string

The text for "hide slide notes".
Optional hideSidebar?: string

The text for "hide the sidebar".
Optional jumpTo?: string

The text for "jump to".
Optional nextPage?: string

The text for "the next page".
Optional nextStep?: string

The text for "the next step".
Optional pageNumber?: string

The text for "page number".
Optional prePage?: string

The text for “the previous page”.
Optional preStep?: string

The text for "the previous step".
Optional resetCurrentPPTAnimation?: string

The text for "reset animation of the current PPT file".
Optional resetCurrentSlideAnimation?: string

The text for "reset animation of the current slide".

InvisibleCallbacks

InvisibleCallbacks<A>: { onAttributesUpdate: (attributes: A) => void; onDestroy: () => void }

Callbacks for the invisible plugin.

Type parameters

A: Object

Type declaration

onAttributesUpdate: (attributes: A) => void
- - (attributes: A): void
  - Occurs when the attributes of the invisible plugin are updated.
    
    Parameters
    - attributes: A
      
      The updated attributes.
    Returns void
onDestroy: () => void
- - (): void
  - Occurs when the invisible plugin is deleted.
    
    Returns void

InvisiblePluginClass

InvisiblePluginClass<K, A, P>: { kind: K; onCreate?: (plugin: P) => void; onDestroy?: (plugin: P) => void }

Invisible plugin.

Type parameters

K: string
A: Object
P: InvisiblePlugin<A>

Type declaration

kind: K

The type of the invisible plugin.
Optional onCreate?: (plugin: P) => void
- - (plugin: P): void
  - Occurs when the invisible plugin is created.
    
    Parameters
    - plugin: P
      
      The created invisible plugin.
    Returns void
Optional onDestroy?: (plugin: P) => void
- - (plugin: P): void
  - Occurs when the invisible plugin is deleted.
    
    Parameters
    - plugin: P
      
      The deleted invisible plugin.
    Returns void

InvisiblePluginContext

InvisiblePluginContext: { displayer: Displayer; kind: string }

The context of the invisible plugin.

Type declaration

displayer: Displayer

The Displayer object of the invisible plugin.
kind: string

The type of the invisible plugin.

JoinRoomParams

JoinRoomParams: ConstructRoomParams & { disableDeviceInputs?: boolean; disableEraseImage?: boolean; disableMagixEventDispatchLimit?: boolean; disableNewPencil?: boolean; disablePencilWrittingLimitFrequency?: boolean; enableDrawPoint?: boolean; floatBar?: boolean | Partial<FloatBarOptions>; hotKeys?: Partial<HotKeys>; isWritable?: boolean; newPencilWritingQuality?: NewPencilWritingQuality; region?: string; rejectWhenReadonlyErrorLevel?: RoomErrorLevel; roomToken: string; uid: string; userPayload?: {}; uuid: string }

Configurations for a Room object, which are used to join a live Interactive Whiteboard room. This type inherits ConstructRoomParams and adds the following properties:

uuid: string

Room UUID, the unique identifier of a room. This property is returned after a room is created successfully.
uid: string

Since v2.15.0 The unique identifier (UID) of a user in a string format. The maximum length is 1024 bytes. Ensure that the uid of each user in the same room is unique.

region?: string

The data center, which supports the following values:

`region`	Data center	Service area
`us-sv`	Silicon Valley, United States	North America and South America
`sg`	Singapore	Singapore, East Asia, and Southeast Asia
`in-mum`	Mumbai, India	India
`eu`	Frankfurt, Europe	Europe
`cn-hz`	Hangzhou, China	Areas not covered by other data centers

Note

This property must has the same value as the data center of the live Interactive Whiteboard room to be joined; otherwise, the SDK fails to connect to the room.
You can set either this property or the region property in WhiteWebSdkConfiguration to set the data center. If you set both, this property overrides the region in WhiteWebSdkConfiguration.

roomToken: string

The Room Token for user authentication. See Token overview.
userPayload?: {[key: string]: any;}

Customized user information. This property can use any data type.

Refer to the following code to enable other users to read the userPayload of a specific user, which is set when the user joins the room:

example

  for (var member of room.state.roomMembers) {
      console.log(member.userPayload);
  }

isWritable?: boolean

Sets whether the user is in interactive mode in the room.
- true： (Default) The user is in interactive mode (has read and write permissions on the whiteboard).
- false：The user is in subscription mode (has read-only access to the whiteboard).
  
  This method is different from disableDeviceInputs. See Prohibited operation.
disableDeviceInputs?: boolean

Whether to disable the user from operating the whiteboard tools through the mouse, keyboard, or touchscreen:
- true： Disable the user from operating the whiteboard tools.
- false：(Default) Enable the user to operate the whiteboard tools.
  
  This method is different from isWritable. See Prohibited operation.
enableDrawPoint?: boolean

Whether to enable the pen tool (pencil) to draw a point:
- true： Enable the pen tool to draw a point.
- false：(Default) Disable the pen tool from drawing a point. In this case, clicking on the whiteboard with the pen tool does not draw a point on the screen.
Note

This property takes effect only when disableNewPencil is set to false.
disableNewPencil?: boolean

Since 2.12.5

Disables/Enables the new pencil:
- true: (Default) Disable the new pencil. The SDK applies the old stroke smoothing algorithm to pencil.
- false: Enable the new pencil. This allows the SDK to apply the new stroke smoothing algorithm to pencil, which results in smoother, more natural handwriting with a stroke effect.
Note

To enable the stroke effect, ensure that every user in the room uses one of the following SDKs:
- Android SDK 2.12.3 or later
- iOS SDK 2.12.3 or later
- Web SDK 2.12.5 or later
disableMagixEventDispatchLimit?: boolean

Since v2.15.0

Whether to disable the frequency limit for sending custom events:
- true: Disable the frequency limit. When the frequency limit is disabled, freezes may occur.
- false: (Default) Enable the frequency limit. When the frequency limit is enabled, the SDK sends an event every 75 ms.
disableEraseImage?: boolean

Whether to disable the eraser from erasing images on the whiteboard:
- true：Disable the eraser from erasing images.
- false：(Default) Enable the eraser to erase images.
disablePencilWrittingLimitFrequency?: boolean

Since v2.15.2

Whether to disable the frequency limit for synchronizing the writing input while using the pencil tool:
- true: Disable the frequency limit. When the frequency limit is disabled, the writing is synchronized immediately, but CPU consumption can increase.
- false: (Default) Enable the frequency limit. When the frequency limit is enabled, the writing synchronization can be slightly delayed, but CPU consumption is lessened.
floatBar?: boolean | Partial

Whether to enable the floating bar when currentApplianceName is set to selector or text:
- true： Enable the floating bar.
- false：(Default) Disable the floating bar.

hotKeys?: Partial

Add custom hotkeys. If you do not set this property, the SDK uses the following default hotkeys:

Keys	Action
Backspace or Delete	Delete the selected object
Shift	Resize proportionately
Ctrl + Z or Command + Z	Undo
Ctrl + Y or Command + Y	Redo
Ctrl + C or Command + C	Copy
Ctrl + V or Command + V	Paste

To disable the default hotkeys, set this property as {}.

rejectWhenReadonlyErrorLevel?: RoomErrorLevel

The response of the SDK when a user without write permission attempts to write.

Level

Level: "debug" | "info" | "warn" | "error"

The output log level.

since

2.11.8

The log level follows the sequence of error, warn, info, and debug. When choosing a level, you can also see the logs preceding that level. For example, if you set the log level to info, the SDK outputs the logs within levels error，warn，and info.

error: Logs at this level mainly report the errors that cause the SDK to fail to complete a task.
warn: Logs at this level mainly report the issues that the SDK has encountered but automatically solved. If you call a deprecated method, the SDK does not send warning messages.
info: Logs at this level mainly provide information on SDK connection states.
debug: Set your log level as debug if you want to get the most complete log file. At present, logs at the debug level have the same information as those at the info level.

LoggerOptions

LoggerOptions: { printLevelMask?: Level; reportDebugLogMode?: LoggerReportMode; reportLevelMask?: Level; reportQualityMode?: LoggerReportMode }

Log configuration.

Type declaration

Optional printLevelMask?: Level

The log printing level of the SDK. See Level. The default level is info.
Optional reportDebugLogMode?: LoggerReportMode

The mode for the SDK to report logs at the debug level.
Optional reportLevelMask?: Level

The log reporting level of the SDK. See Level.
Optional reportQualityMode?: LoggerReportMode

The mode of the SDK to report connection quality data.

MagixEventListenerOptions

MagixEventListenerOptions: { fireInterval?: number; fireSelfEventAfterCommit?: boolean }

Options for setting a custom event listener.

since: v2.15.2

Type declaration

Optional fireInterval?: number

The interval (ms) of the SDK triggering custom event callbacks. The default value is 500. The value must be equal to or greater than 500.

The SDK triggers the custom event callbacks based on the set value of this parameter.
Optional fireSelfEventAfterCommit?: boolean
Sets whether to send event callbacks after the Agora server acknowledges the dispatchMagixEvent method call is successful:
- true: Send the event callbacks immediately after the dispatchMagixEvent method call.
- false: (Default) Send the event callbacks after the Agora server acknowledges the dispatchMagixEvent method call is successful.

Margin

Margin: { bottom: number; left: number; right: number; top: number }

Margin configuration.

Type declaration

bottom: number

The bottom margin in pixels.
left: number

The left margin in pixels.
right: number

The right margin in pixels.
top: number

The top margin in pixels.

MediaType

MediaType: "video" | "audio"

The type of the media file:

video: A video file.
audio: An audio file.

MemberInformation

MemberInformation: { id: number; payload: any; session: string }

Customized user information.

deprecated: Use userPayload in JoinRoomParams instead.

Type declaration

id: number
payload: any
session: string

MemberState

MemberState: { bold?: boolean; currentApplianceName: ApplianceNames; dottedLine?: boolean; italic?: boolean; lineThrough?: boolean; shapeType?: ShapeType; strokeColor: Color; strokeWidth: number; textCanSelectText?: boolean; textColor?: Color; textSize: number; underline?: boolean }

The state of the whiteboard tool in a live Interactive Whiteboard room.

Type declaration

Optional bold?: boolean
Whether to bold the text:
- true: Bold the text.
- false: (Default) Do not bold the text.
currentApplianceName: ApplianceNames

The name of the whiteboard tool currently in use. See ApplianceNames.
Optional dottedLine?: boolean
Whether to support drawing dotted lines:
- true: Support drawing dotted lines.
- false: (Default) Do not support drawing dotted lines.
Optional italic?: boolean
Whether to italicize the text:
- true: Italicize the text.
- false: (Default) Do not italicize the text.
Optional lineThrough?: boolean
Whether to apply strikethrough formatting to the text:
- true: Apply strikethrough formatting.
- false: (Default) Do not apply strikethrough formatting.
Optional shapeType?: ShapeType

The shape type.
strokeColor: Color

The stroke color in RGB format. For example, [0, 0, 255] represents blue.
strokeWidth: number

The stroke width.
Optional textCanSelectText?: boolean
Whether to allow directly selecting and editing whiteboard text:
- true: Allow directly selecting and editing whiteboard text.
- false: (Default) Do not allow directly selecting and editing whiteboard text.
Optional textColor?: Color

The stroke color in RGB format. For example, [0, 0, 255] represents blue.
textSize: number

The font size of the text. The Chrome browser automatically adjusts fonts smaller than 12 to 12.
Optional underline?: boolean
Whether to underline the text:
- true: Underline the text.
- false: (Default) Do not underline the text.

NativeEvent

NativeEvent: MouseEvent | WheelEvent | KeyboardEvent | TouchEvent

Browser events.

MouseEvent: See MouseEvent。
WheelEvent: See WheelEvent。
KeyboardEvent: See KeyboardEvent。
TouchEvent: See TouchEvent。

PPT

PPT: { height: number; kind: PPTKind; scenes: ReadonlyArray<SceneDefinition>; uuid: string; width: number }

Description of the image or dynamic PPT slide output by file conversion.

Type declaration

height: number

The height of the image or dynamic PPT slide.
kind: PPTKind

The type of the file-conversion task.
scenes: ReadonlyArray<SceneDefinition>

The list of scenes related to the image or dynamic PPT slide.
uuid: string

The unique identifier (UUID) of the file-conversion task.
width: number

The width of the image or dynamic PPT slide.

PPTTaskCallbacks

PPTTaskCallbacks: { onProgressUpdated: (progress: PPTTaskProgress) => void; onTaskFail: (error: Error) => void; onTaskSuccess: (result: PPT) => void }

The callbacks for the file-conversion task.

Type declaration

onProgressUpdated: (progress: PPTTaskProgress) => void
- - (progress: PPTTaskProgress): void
  - Occurs when the conversion progress is updated.
    
    Parameters
    - progress: PPTTaskProgress
      
      The progress details.
    Returns void
onTaskFail: (error: Error) => void
- - (error: Error): void
  - Occurs when the task fails.
    
    Parameters
    - error: Error
      
      The error message.
    Returns void
onTaskSuccess: (result: PPT) => void
- - (result: PPT): void
  - Occurs when the task succeeds.
    
    Parameters
    - result: PPT
      
      The image or dynamic PPT slide output by the task. See PPT.
    Returns void

PPTTaskParams

PPTTaskParams: { callbacks?: PPTTaskCallbacks; checkProgressInterval?: number; checkProgressTimeout?: number; kind: PPTKind; region?: string; taskToken: string; uuid: string }

The parameters of the PPTTask object.

Type declaration

Optional callbacks?: PPTTaskCallbacks

The callbacks for the file-conversion task.
Optional checkProgressInterval?: number

The time interval (ms) to automatically query the state of the file-conversion task.
Optional checkProgressTimeout?: number

The timeout (ms) of the automatic query.
kind: PPTKind

The type of the file-conversion task.

Optional region?: string

The data center that processes the file-conversion task. The following values are supported:

`region`	Data center	Service area
`us-sv`	Silicon Valley, United States	North America and South America
`sg`	Singapore	Singapore, East Asia, and Southeast Asia
`in-mum`	Mumbai, India	India
`eu`	Frankfurt, Europe	Europe
`cn-hz`	Hangzhou, China	Areas not covered by other data centers

taskToken: string

The Task Token for authentication of the file-conversion task.
uuid: string

The unique identifier (UUID) of the file-conversion task.

PPTTaskProgress

PPTTaskProgress: { convertedPageSize: number; convertedPercentage: number; currentStep?: PPTTaskStep; status: PPTTaskStatus; totalPageSize: number }

The progress details of the file-conversion task.

Type declaration

convertedPageSize: number

The number of pages converted.
convertedPercentage: number

The conversion progress (in percentage).
Optional currentStep?: PPTTaskStep

The current step of the file-conversion task.

since

2.10.3
status: PPTTaskStatus

The state of the file-conversion task.
totalPageSize: number

The total number of pages to be converted.

PencilOptions

PencilOptions: { disableBezier: boolean; enableDrawPoint: boolean; sparseHump: number; sparseWidth: number }

Type declaration

disableBezier: boolean
deprecated
Whether to disable the Bézier curve optimization:
- true: Disable.
- false: (Default) Enable.
enableDrawPoint: boolean
Whether to enable the pen tool (pencil) to draw a point:
- true： Enable the pen tool to draw a point.
- false：(Default) Disable the pen tool from drawing a point. In this case, clicking on the whiteboard with the pen tool does not draw a point on the screen.
Note

This parameter takes effect only when disableNewPencil is set to false.
sparseHump: number

deprecated
sparseWidth: number

deprecated

Plugin

Plugin<C, T>: { defaultAttributes?: T; hitTest?: (plugin: PluginInstance<C, T>, x: number, y: number, selectorRadius: number) => boolean; kind?: string; render: ComponentType<PluginProps<C, T>>; willInterruptEvent?: (plugin: PluginInstance<C, T>, event: NativeEvent) => boolean }

Description of component plugins.

Agora supports two kinds of custom plugins: component plugins and invisible plugins.

Type parameters

Type declaration

Optional defaultAttributes?: T

Default attributes.
Optional hitTest?: (plugin: PluginInstance<C, T>, x: number, y: number, selectorRadius: number) => boolean
- - (plugin: PluginInstance<C, T>, x: number, y: number, selectorRadius: number): boolean
  - Hit test, which you can use to define the selectable area of the component plugin for the selection tool.
    
    Parameters
    - plugin: PluginInstance<C, T>
      
      The component plugin object.
    - x: number
      
      The X coordinate of the center of the selectable area.
    - y: number
      
      The Y coordinate of the center of the selectable area.
    - selectorRadius: number
      
      The radius of the selectable area.
    Returns boolean
    
    The result of the hit test:
    - true: The hit test succeeds.
    - false: The hit test fails.
Optional kind?: string

The type of the component plugin, which is the unique identifier of the plugin.
render: ComponentType<PluginProps<C, T>>

The style of the component plugin.
Optional willInterruptEvent?: (plugin: PluginInstance<C, T>, event: NativeEvent) => boolean
- - (plugin: PluginInstance<C, T>, event: NativeEvent): boolean
  - Determines whether to interrupt the native events of the component plugin.
    
    Parameters
    - plugin: PluginInstance<C, T>
      
      The component plugin object.
    - event: NativeEvent
      
      The native events.
    Returns boolean
    
    Whether to interrupt the native events of the component plugin:
    - true: Interrupt the native events.
    - false: Do not interrupt the native events.

PluginDescription

PluginDescription<A>: { attributes?: A; height?: number; originX?: number; originY?: number; selectable?: boolean; width?: number }

Description of component plugin objects.

Type parameters

Type declaration

Optional attributes?: A

The attributes of the component plugin object.
Optional height?: number

The height of the component plugin object.
Optional originX?: number

The X coordinate of the upper left corner of the component plugin object in the world coordinate system (taking the center of the initial whiteboard as the origin).
Optional originY?: number

The Y coordinate of the upper left corner of the component plugin object in the world coordinate system (taking the center of the initial whiteboard as the origin).
Optional selectable?: boolean
Whether the component plugin object can be selected:
- true: The component plugin object can be selected.
- false: The component plugin object cannot be selected.
Optional width?: number

The width of the component plugin object.

PluginProps

PluginProps<C, T>: { margin: Margin; origin: Point; plugin: PluginInstance<C, T>; scale: number; size: Size }

Style configuration of the component plugin.

Type parameters

Type declaration

margin: Margin

The space around the component plugin icon.
origin: Point

The coordinates of the center of the component plugin icon in the world coordinate system (taking the center of the initial whiteboard as the origin).
plugin: PluginInstance<C, T>

The component plugin object.
scale: number

The scale factor of the component plugin icon.
size: Size

The size of the component plugin icon.

Point

Point: { x: number; y: number }

Coordinates of a point in the world coordinate system (taking the center of the initial whiteboard as the origin).

Type declaration

x: number

The X coordinate of the point in the world coordinate system.
y: number

The Y coordinate of the point in the world coordinate system.

PptDescription

PptDescription: { height: number; previewURL?: string; src: string; width: number }

Description of the image or dynamic PPT slide.

To present the image or dynamic PPT slide on the whiteboard scene, you can configure PptDescription when initializing a WhiteScene object .

The following formats are supported:

Static images in PNG, JPG/JPEG, and WEBP formats, or PNG, JPG/JPEG, and WEBP images which are converted from PPT, PPTX, DOC, DOCX, and PDF files.
Dynamic PPT slides which are converted from PPTX files using the Agora file conversion service.

Note

You can insert only one image or dynamic PPT slide on a whiteboard scene.
The image or dynamic PPT slide displayed on the whiteboard scene takes the origin of the world coordinate system as the center and cannot be changed, which means you cannot change the position of the image or dynamic PPT slide inside the whiteboard.

Type declaration

height: number

The height (px) of the image or dynamic PPT slide.
Optional previewURL?: string

The URL address of the preview image for the image or dynamic PPT slide. You can get the URL address of the dynamic PPT preview in the preview field in the query result of the file conversion task. For example, "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/dynamicConvert/2fdxxxxx67e/preview/1.png".
src: string
The address of the image or dynamic PPT slide. The supported formats are as follows:
- For image: The URL address, which can be generated by yourself or by using the Agora file conversion service. For example, "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticConvert/2fdxxxxx67e/1.jpeg".
- For dynamic PPT slide: The URI address, which is generated by using the Agora file conversion service. For example, "pptx://cover.herewhite.com/dynamicConvert/6a212c90fa5311ea8b9c074232aaccd4/1.slide".
width: number

The width (px) of the image or dynamic PPT slide.

PptParams

PptParams: { rtcClient?: RTCClient; useServerWrap?: boolean }

Configurations for dynamic PPT files.

Type declaration

Optional rtcClient?: RTCClient

The AgoraRTCClient class in the Agora RTC SDK. See RTCClient.
Optional useServerWrap?: boolean
Whether to enable server-side typesetting for dynamic PPT slides.
since
2.12.0

As of February 10, 2021, when converting dynamic PPT slides to HTML web pages, the Agora Interactive Whiteboard server supports typesetting the dynamic PPT slides to ensure the presentation of the text in the dynamic PPT slides is consistent across platforms.

Note

From 2.12.18, the default value of useServerWrap is changed from false to true.
- true: (Default) Enable server-side typesetting.
- false: Disable server-side typesetting.

PreviewConfig

PreviewConfig: { international?: International }

Configurations of the PPT preview page.

Type declaration

Optional international?: International

Adds text to the menu on the preview page. See International.

Progress

Progress: { convertedFileList: ConvertedFile[]; convertedPageSize: number; convertedPercentage: number; currentStep?: CurrentStep; totalPageSize: number }

Details about the file-conversion progress.

Type declaration

convertedFileList: ConvertedFile[]

The generated file.
convertedPageSize: number

The number of pages converted.
convertedPercentage: number

The conversion progress (in percentage).
Optional currentStep?: CurrentStep

The current step of the file-conversion task.
totalPageSize: number

The total number of pages to be converted.

RTCClient

RTCClient: { adjustAudioMixingPlayoutVolume?: (volume: number) => number; adjustAudioMixingPublishVolume?: (volume: number) => number; adjustAudioMixingVolume?: (volume: number) => number; getAudioMixingCurrentPosition?: () => number; getAudioMixingDuration?: () => number; getAudioMixingPlayoutVolume?: () => number; getAudioMixingPublishVolume?: () => number; pauseAudioMixing: () => number; resumeAudioMixing: () => number; setAudioMixingPosition: (position: number) => number; startAudioMixing: (filePath: string, loopback: boolean, replace: boolean, cycle: number, callback?: (state: number, errorCode: number) => void) => number; stopAudioMixing: (callback?: (state: number, errorCode: number) => void) => number }

AgoraRTCClient is used for bridging the audio mixing method of the Agora RTC SDK and the Interactive Whiteboard SDK.

When you use the Agora RTC SDK and Interactive Whiteboard SDK at the same time, and the dynamic PPT slides displayed in the whiteboard contain audio files, you may encounter the issues of low volume and/or echoes when playing the audio in the PPT slides.

To solve these issues, you can use the AgoraRTCClient type to call the audio mixing method of the Agora RTC SDK to play the audio files in the dynamic PPT slides.

Note

Currently only the Agora RTC SDK for Electron is supported.

Type declaration

Optional adjustAudioMixingPlayoutVolume?: (volume: number) => number
- - (volume: number): number
  - Adjusts the volume of audio mixing for local playback.
    
    Parameters
    - volume: number
      
      Audio mixing volume for local playback. The value ranges between 0 and 100. The default is 100, indicating the original volume.
    Returns number
    - 0: Success.
    - < 0: Failure.
Optional adjustAudioMixingPublishVolume?: (volume: number) => number
- - (volume: number): number
  - Adjusts the volume of audio mixing for publishing (sending to other users).
    
    Parameters
    - volume: number
      
      Audio mixing volume for remote playback. The value ranges between 0 and 100. The default is 100, indicating the original volume.
    Returns number
    - 0: Success.
    - < 0: Failure.
Optional adjustAudioMixingVolume?: (volume: number) => number
- - (volume: number): number
  - Adjusts the volume of audio mixing.
    
    This method adjusts the audio mixing volume for both local playback and publishing (sending to other users).
    
    Parameters
    - volume: number
      
      Audio mixing volume. The value ranges between 0 and 100. The default is 100, indicating the original volume.
    Returns number
    - 0: Success.
    - < 0: Failure.
Optional getAudioMixingCurrentPosition?: () => number
- - (): number
  - Gets the playback position of the music file.
    
    Returns number
    - Returns the current playback position (ms), if the method call is successful.
    - < 0: Failure.
Optional getAudioMixingDuration?: () => number
- - (): number
  - Gets the duration of the music file played by startAudioMixing.
    
    Returns number
    - Returns the duration (ms), if the method call is successful.
    - < 0: Failure.
Optional getAudioMixingPlayoutVolume?: () => number
- - (): number
  - Gets the audio mixing volume for local playback.
    
    Returns number
    - Returns the audio mixing volume for local playback, if the method call is successful. The value range is [0,100].
    - < 0: Failure.
Optional getAudioMixingPublishVolume?: () => number
- - (): number
  - Gets the audio mixing volume for publishing.
    
    Returns number
    - Returns the audio mixing volume for local playback, if the method call is successful. The value range is [0,100].
    - < 0: Failure.
pauseAudioMixing: () => number
- - (): number
  - Pauses playing and mixing the music file.
    
    Returns number
    - 0: Success.
    - < 0: Failure.
resumeAudioMixing: () => number
- - (): number
  - Resumes playing and mixing the music file.
    
    Returns number
    - 0: Success.
    - < 0: Failure.
setAudioMixingPosition: (position: number) => number
- - (position: number): number
  - Sets the playback position of the music file to a different starting position (the default plays from the beginning).
    
    Parameters
    - position: number
      
      The playback starting position (ms), which must be an integer.
    Returns number
    - 0: Success.
    - < 0: Failure.
startAudioMixing: (filePath: string, loopback: boolean, replace: boolean, cycle: number, callback?: (state: number, errorCode: number) => void) => number
- - (filePath: string, loopback: boolean, replace: boolean, cycle: number, callback?: (state: number, errorCode: number) => void): number
  - Starts playing and mixing the music file.
    
    Parameters
    - filePath: string
      
      The absolute path or URL address of the music file.
    - loopback: boolean
      Whether to only play music files on the local client:
      
      true: Only play music files on the local client so that only the local user can hear the music.
      
      false: Publish music files to remote clients so that both the local user and remote users can hear the music.
    - replace: boolean
      Whether to replace the audio collected by the microphone with a music file:
      
      true: Replace the audio. Users can only hear music.
      
      false: Do not replace the audio. Users can hear both music and audio collected by the microphone.
    - cycle: number
      The number of times the music file plays.
      
      ≥ 0: The number of playback times. For example, 0 means that the SDK does not play the music file, while 1 means that the SDK plays the music file once.
      
      -1: Play the music in an indefinite loop.
    - Optional callback: (state: number, errorCode: number) => void
      
      Occurs when the SDK starts playing and mixing the music file. state: number represents the state of playing or mixing the music file. errorCode: number represents an error code.
      - (state: number, errorCode: number): void
        
        Occurs when the SDK starts playing and mixing the music file. state: number represents the state of playing or mixing the music file. errorCode: number represents an error code.
        
        Parameters
        
        state: number
        
        errorCode: number
        
        Returns void
    Returns number
    - 0: Success.
    - < 0: Failure.
stopAudioMixing: (callback?: (state: number, errorCode: number) => void) => number
- - (callback?: (state: number, errorCode: number) => void): number
  - Stops playing or mixing the music file.
    
    Parameters
    - Optional callback: (state: number, errorCode: number) => void
      
      Occurs when the SDK stops playing or mixing the music file. state: number represents the state of playing or mixing the music file. errorCode: number represents an error code.
      - (state: number, errorCode: number): void
        
        Occurs when the SDK stops playing or mixing the music file. state: number represents the state of playing or mixing the music file. errorCode: number represents an error code.
        
        Parameters
        
        state: number
        
        errorCode: number
        
        Returns void
    Returns number
    - 0: Success.
    - < 0: Failure.

ReconnectionOptions

ReconnectionOptions: { disableReconnect: boolean }

Reconnection configuration.

Type declaration

disableReconnect: boolean
Whether to disable the reconnection mechanism when the user drops offline:
- true: Disable the reconnection mechanism.
- false: Enable the reconnection mechanism.

Rectangle

Rectangle: Size & { originX: number; originY: number }

View rectangle description. This type inherits Size and adds the following members:

originX: number

The X coordinate of the left corner of the view rectangle in the world coordinate system (taking the center of the initial whiteboard as the origin).
originY: number

The Y coordinate of the left corner of the view rectangle in the world coordinate system (taking the center of the initial whiteboard as the origin).

RenderPlugin

RenderPlugin<C, T>: { defaultAttributes?: T; hitTest?: (plugin: PluginInstance<C, T>, x: number, y: number, selectorRadius: number) => boolean; kind: string; render: ComponentType<PluginProps<C, T>>; willInterruptEvent?: (plugin: PluginInstance<C, T>, event: NativeEvent) => boolean }

Rendering of the component plugin.

Type parameters

Type declaration

Optional defaultAttributes?: T

The default attributes of the component plugin.
Optional hitTest?: (plugin: PluginInstance<C, T>, x: number, y: number, selectorRadius: number) => boolean
- - (plugin: PluginInstance<C, T>, x: number, y: number, selectorRadius: number): boolean
  - Hit test, which you can use to define the selectable area of the component plugin for the selection tool.
    
    Parameters
    - plugin: PluginInstance<C, T>
      
      The component plugin object.
    - x: number
      
      The X coordinate of the center of the selectable area.
    - y: number
      
      The Y coordinate of the center of the selectable area.
    - selectorRadius: number
      
      The radius of the selectable area.
    Returns boolean
    
    The result of the hit test:
    - true: The hit test succeeds.
    - false: The hit test fails.
kind: string

The type of the component plugin, which is the unique identifier of the component plugin.
render: ComponentType<PluginProps<C, T>>

The style of the component plugin.
Optional willInterruptEvent?: (plugin: PluginInstance<C, T>, event: NativeEvent) => boolean
- - (plugin: PluginInstance<C, T>, event: NativeEvent): boolean
  - Determines whether to interrupt the native events of the component plugin.
    
    Parameters
    - plugin: PluginInstance<C, T>
      
      The component plugin object.
    - event: NativeEvent
      
      The native events.
    Returns boolean
    
    Whether to interrupt the native events of the component plugin:
    - true: Interrupt the native events.
    - false: Do not interrupt the native events.

RoomCallbacks

RoomCallbacks: DisplayerCallbacks & { onCanRedoStepsUpdate: (canRedoSteps: number) => void; onCanUndoStepsUpdate: (canUndoSteps: number) => void; onDisconnectWithError: (error: Error) => void; onKeyDown: (event: KeyboardEvent) => void; onKeyUp: (event: KeyboardEvent) => void; onKickedWithReason: (reason: string) => void; onPhaseChanged: (phase: RoomPhase) => void; onRoomStateChanged: (modifyState: Partial<RoomState>) => void; willInterceptKeyboardEvent: (event: KeyboardEvent) => boolean }

RoomCallbacks contains callbacks for live Interactive Whiteboard rooms. This type inherits DisplayerCallbacks and adds the following members:

onPhaseChanged: (phase: RoomPhase)=>void

Occurs when the room connection state changes.

param

phase The current connection state of the room. See RoomPhase.

onRoomStateChanged: (modifyState: Partial)=>void

Occurs when the room state changes.

This callback reports only the room state fields that have changed and returns null for the room state fields that have not changed.

param

modifyState The room state that has changed. See RoomState.

onDisconnectWithError: (error: Error)=>void

Occurs when the SDK is disconnected from the server.

param

error The error message.

onKickedWithReason: (reason: string)=>void

Occurs when the local user is removed from the live Interactive Whiteboard room.

param

reason The reason why the user is removed from the room.

`reason`	Description
kickByAdmin	The user is removed by the admin.
roomDelete	The room is deleted.
roomZombie	The room is not active.
roomBan	The room is disabled.
GatewayAdjust	The gateway is adjusted.
replaceByOther	The user is replaced by another user.
crash	The server crashes.

onCanUndoStepsUpdate: (canUndoSteps: number)=>void

Occurs when the number of undoable actions changes.

The SDK triggers this callback every time the local user calls undo and reports the number of remaining undoable actions.

param

canUndoSteps The number of remaining undoable actions.

onCanRedoStepsUpdate: (canRedoSteps: number)=>void

Occurs when the number of redoable actions changes.

The SDK triggers this callback every time the local user calls redo and reports the number of remaining redoable actions.

param

canRedoSteps The number of remaining redoable actions.

willInterceptKeyboardEvent: (event: KeyboardEvent)=>boolean

Whether to intercept the keyboard event for which you have set a listener:
- true: Intercept the keyboard event, which implies that the event does not trigger the callback.
- false: Do not intercept the keyboard event.
onKeyDown: (event: KeyboardEvent)=>void

Occurs when a key is pressed.
onKeyUp: (event: KeyboardEvent)=>void

Occurs when a key is released.

RoomMember

RoomMember: { memberId: number; memberState: MemberState; payload: UserPayload; session: string }

Information of the users in interactive mode in the live Interactive Whiteboard room.

Type declaration

memberId: number

The member ID of the user.

When a user joins the live Interactive Whiteboard room in interactive mode, the SDK assigns a unique member ID for the user.
memberState: MemberState

The state of the whiteboard tool currently in use by the user. See MemberState.
payload: UserPayload

The customized user information, which is passed in when the user joins the room. See UserPayload.

since

v2.15.0
session: string

The session ID.

RoomState

RoomState: DisplayerState & { broadcastState: Readonly<BroadcastState>; memberState: MemberState }

All states of a live Interactive Whiteboard room. This type inherits DisplayerState and adds the following members:

memberState: MemberState

The state of the whiteboard tool currently in use. See MemberState.
broadcastState: Readonly

The current state of the view.

SceneDefinition

SceneDefinition: { name?: string; ppt?: PptDescription }

Definition of a scene.

Type declaration

Optional name?: string

The name of the scene.
Optional ppt?: PptDescription

The image or dynamic PPT slide to be displayed in the scene.

A scene can display one image or dynamic PPT slide. You can set the width, height, URL address, and preview of the image or dynamic PPT slide in PptDescription.

SceneMap

SceneMap: {}

List of scenes.

Type declaration

[dirPath: string]: WhiteScene[]

The list of scenes under a scene directory.

SceneState

SceneState: { contextPath: string; index: number; sceneName: string; scenePath: string; scenes: ReadonlyArray<WhiteScene> }

The scene state.

Type declaration

contextPath: string

The path of the current scene directory.

since

2.10.3
index: number

The index of the current scene under its scene directory.
sceneName: string

The name of the current scene.

since

2.10.3
scenePath: string

The path of the current scene.
scenes: ReadonlyArray<WhiteScene>

The list of scenes under the current scene directory.

ScenesCallbacks

ScenesCallbacks: { onAddScene: (scenesCallbacks: ScenesCallbacksNode, name: string) => void; onAddSceneGroup: (scenesCallbacks: ScenesCallbacksNode, name: string) => void; onRemoveScene: (scenesCallbacks: ScenesCallbacksNode, name: string) => void; onRemoveSceneGroup: (scenesCallbacks: ScenesCallbacksNode, name: string) => void; onScenesCountUpdate: (scenesCallbacks: ScenesCallbacksNode, scenesCount: number) => void; onScenesGroupCountUpdate: (scenesCallbacks: ScenesCallbacksNode, sceneGroupsCount: number) => void }

Scene callbacks.

Type declaration

onAddScene: (scenesCallbacks: ScenesCallbacksNode, name: string) => void

Occurs when a new scene is added to the specified scene directory.

param

The information about the scene directory. See ScenesCallbacksNode.

param

The name of the new scene.
- - (scenesCallbacks: ScenesCallbacksNode, name: string): void
  - Parameters
    - scenesCallbacks: ScenesCallbacksNode
    - name: string
    Returns void
onAddSceneGroup: (scenesCallbacks: ScenesCallbacksNode, name: string) => void

Occurs when a new subdirectory is added to the specified scene directory.

param

The information about the scene directory. See ScenesCallbacksNode.

param

The name of the new subdirectory.
- - (scenesCallbacks: ScenesCallbacksNode, name: string): void
  - Parameters
    - scenesCallbacks: ScenesCallbacksNode
    - name: string
    Returns void
onRemoveScene: (scenesCallbacks: ScenesCallbacksNode, name: string) => void

Occurs when a scene is deleted from the specified scene directory.

param

The information about the scene directory. See ScenesCallbacksNode.

param

The name of the deleted scene.
- - (scenesCallbacks: ScenesCallbacksNode, name: string): void
  - Parameters
    - scenesCallbacks: ScenesCallbacksNode
    - name: string
    Returns void
onRemoveSceneGroup: (scenesCallbacks: ScenesCallbacksNode, name: string) => void

Occurs when a subdirectory is deleted from the specified scene directory.

param

The information about the scene directory. See ScenesCallbacksNode.

param

The name of the deleted subdirectory.
- - (scenesCallbacks: ScenesCallbacksNode, name: string): void
  - Parameters
    - scenesCallbacks: ScenesCallbacksNode
    - name: string
    Returns void
onScenesCountUpdate: (scenesCallbacks: ScenesCallbacksNode, scenesCount: number) => void

Occurs when the number of scenes under the specified scene directory changes.

param

The information about the scene directory. See ScenesCallbacksNode.

param

The current number of scenes under the specified scene directory.
- - (scenesCallbacks: ScenesCallbacksNode, scenesCount: number): void
  - Parameters
    - scenesCallbacks: ScenesCallbacksNode
    - scenesCount: number
    Returns void
onScenesGroupCountUpdate: (scenesCallbacks: ScenesCallbacksNode, sceneGroupsCount: number) => void

Occurs when the number of subdirectories under the specified scene directory changes.

param

The information about the scene directory. See ScenesCallbacksNode.

param

The current number of subdirectories under the specified scene directory.
- - (scenesCallbacks: ScenesCallbacksNode, sceneGroupsCount: number): void
  - Parameters
    - scenesCallbacks: ScenesCallbacksNode
    - sceneGroupsCount: number
    Returns void

Size

Size: { height: number; width: number }

Size description.

Type declaration

height: number

The height of the object.
width: number

The width of the object.

TextFormat

TextFormat: { bold?: boolean; color?: Color; fontSize?: number; italic?: boolean; lineThrough?: boolean; underline?: boolean }

The text format.

Type declaration

Optional bold?: boolean
Whether to bold the text:
- true: Bold the text.
- false: (Default) Do not bold the text.
Optional color?: Color

The stroke color in RGB format. For example, [0, 0, 255] represents blue.
Optional fontSize?: number

The font size. The value must be greater than 0.
Optional italic?: boolean
Whether to italicize the text:
- true: Italicize the text.
- false: (Default) Do not italicize the text.
Optional lineThrough?: boolean
Whether to apply strikethrough formatting to the text:
- true: Apply strikethrough formatting.
- false: (Default) Do not apply strikethrough formatting.
Optional underline?: boolean
Whether to underline the text:
- true: Underline the text.
- false: (Default) Do not underline the text.

UserCursorIcons

UserCursorIcons: {}

Custom icons.

Type declaration

[key: string]: ReadonlyArray<string>

UserFonts

UserFonts: {}

Custom fonts.

Type declaration

[font: string]: string

Custom fonts in key-value pairs. The key is the font name and the value is the URL address of the font file. For example, "Calibri": "https://your-cdn.com /Calibri.ttf".

UserPayload

UserPayload: {} & { uid: string }

Customized user information.

[key: string]: any

The customized user information in key-value pairs. For example, "avatar", "https://example.com/user.png".
uid: string

The unique identifier of a user in a string format. The maximum length is 1024 bytes.

Ensure that the uid of each user in the same room is unique.

since: v2.15.0

WhiteScene

WhiteScene: { name: string; ppt?: PptDescription }

Whiteboard scene.

Type declaration

name: string

The scene name.
Optional ppt?: PptDescription

The image or dynamic PPT slide to be displayed in the scene. A scene can display one image or dynamic PPT slide. You can set the width, height, URL address, and preview of the image or dynamic PPT slide in PptDescription.

WhiteWebSdkConfiguration

WhiteWebSdkConfiguration: { appIdentifier: string; deviceType?: DeviceType; disableCurveAnimes?: boolean; disableNewPencilStroke?: boolean; disableRotation?: boolean; fontFamily?: string; fonts?: UserFonts; handToolKey?: string; invisiblePlugins?: ReadonlyArray<InvisiblePluginClass<string, any, any>>; loggerOptions?: LoggerOptions; onWhiteSetupFailed?: (error: Error) => void; onlyCallbackRemoteStateModify?: boolean; plugins?: Plugins; pptParams?: PptParams; preloadDynamicPPT?: boolean; reconnectionOptions?: Partial<ReconnectionOptions> | false; region?: string; renderEngine?: RenderEngine; screenType?: ScreenType; urlInterrupter?: (url: string) => string; useMobXState?: boolean; wrappedComponents?: WrappedComponents }

Configuration for the WhiteWebSdk object.

Note

After the WhiteWebSdk object is initialized, you cannot call any method in WhiteWebSdkConfiguration to modify the configuration of the WhiteWebSdk object.

Type declaration

appIdentifier: string

The unique app identifier issued to your Interactive Whiteboard project by Agora. See Get security credentials for your whiteboard project.
Optional deviceType?: DeviceType

The device type, which determines how the SDK handles mouse and touch events.

If you pass in an incorrect value, the SDK may not respond to the device inputs as expected. If you do not pass in a value, the SDK determines the device type using its internal logic.
Optional disableCurveAnimes?: boolean
Sets whether to disable tween animation for the new pencil:
- true: Disable tween animation. This can decrease latency, but cause freezes in the writing or drawing process seen by remote users.
- false: (Default) Enable tween animation. This allows the SDK to automatically insert frames between keyframes when a user draws or writes with the pencil, so that remote users see a smoother drawing process, but this increases latency.
note

This property takes effect only when disableNewPencil is set as false.
Optional disableNewPencilStroke?: boolean
Sets whether to disable the stroke effect of the new pencil:
- true: Disable the stroke effect.
- false: (Default) Enable the stroke effect.
note

This property takes effect only when disableNewPencil is set as false.
Optional disableRotation?: boolean
Sets whether to disable image rotation:
- true: Enable image rotation.This allows users to rotate a selected image by any angle.
- false: (Default) Disable image rotation.
Optional fontFamily?: string

The font of the characters entered by the text tool (currentApplianceName="text"). If you do not set this property, the SDK uses the default font of the browser.
Optional fonts?: UserFonts

Custom fonts.

To display unconventional fonts in dynamic PPT slides, you need to upload the font file to your app server or a third-party cloud storage and generate a URL address, then pass the URL address to this property when initializing the WhiteWebSdk object.
Optional handToolKey?: string

The hotkey for the hand tool.

When you press the hotkey, the whiteboard tool automatically switches to the hand tool (currentApplianceName="hand"). Once you release the key, the whiteboard tool switches back to your original tool in use. If you do not set this property, the hotkey switch function is disabled.
Optional invisiblePlugins?: ReadonlyArray<InvisiblePluginClass<string, any, any>>

Invisible plugins.
Optional loggerOptions?: LoggerOptions

SDK log configuration. See LoggerOptions.
Optional onWhiteSetupFailed?: (error: Error) => void
- - (error: Error): void
  - Occurs when the WhiteWebSdk object fails to initialize.
    example
    
    const whiteWebSdk = new WhiteWebSdk({ appIdentifier: "$APP_IDENTIFIER", onWhiteSetupFailed: function(error) { console.error(error); }, });
    
    This callback only reports network and authentication errors. If you pass in incorrect parameters, an error message occurs when calling new WhiteWebSdk({...}).
    Parameters
    - error: Error
      
      An error message.
    Returns void
Optional onlyCallbackRemoteStateModify?: boolean
Whether to receive only callbacks of remote user state changes.
- true: (Default) The local user receives only callbacks of remote user state changes and does not receive callbacks of their own state changes.
- false: The local user receives callbacks of remote user state changes as well as callbacks of their own state changes.
Optional plugins?: Plugins

Component plugins.
Optional pptParams?: PptParams

Configuration for dynamic PPT files. See PptParams.
Optional preloadDynamicPPT?: boolean
Whether to preload all image resources in dynamic PPT slides when loading the homepage of the slides.
- true: Preload all image resources in dynamic PPT slides when loading the homepage of the slides.
- false: (Default) Do not preload all image resources in dynamic PPT slides when loading the homepage of the slides.
Note

Agora does not recommend setting preloadDynamicPPT(true), because the setting slows down the PPT display.
Optional reconnectionOptions?: Partial<ReconnectionOptions> | false

Reconnection configuration. The reconnection mechanism is enabled by default.

To disable the reconnection mechanism, set reconnectionOptions as false or disableReconnect as true.

Optional region?: string

The data center, which supports the following values:

`region`	Data center	Service area
`us-sv`	Silicon Valley, United States	North America and South America
`sg`	Singapore	Singapore, East Asia, and Southeast Asia
`in-mum`	Mumbai, India	India
`eu`	Frankfurt, Europe	Europe
`cn-hz`	Hangzhou, China	Areas not covered by other data centers

Note

This property must has the same value as the data center you set when creating the room; otherwise, the SDK fails to connect to the room.

Optional renderEngine?: RenderEngine

Rendering modes for drawings on the whiteboard. The default is Canvas.
Optional screenType?: ScreenType

The user's screen type, which is used to adjust parameters for gesture recognition. The default is Desktop.
Optional urlInterrupter?: (url: string) => string
- - (url: string): string
  - Intercepts the URL address of a resource on the whiteboard (for example, an image) and replaces it.
    
    For example, you can use the following code to add a suffix for the URL addresses of all images in the return value:
    example
    
    const whiteWebSdk = new WhiteWebSdk({ appIdentifier: "$APP_IDENTIFIER", urlInterrupter: function(url) { return url + "?token=bm1n4pisugWrWK"; }, });
    Parameters
    - url: string
      
      The original URL address of the resource.
    Returns string
    
    The new URL address.
Optional useMobXState?: boolean
Whether to use MobX to listen for displayer.state:
- true: Use MobX to listen for displayer.state, which turns displayer.state into a MobX observable object. See Creating observable state.
- false: Do not use MobX to listen for displayer.state.

Optional wrappedComponents?: WrappedComponents

An array of React.ComponentType objects, which is used to package the whiteboard view. The default value is [].

Refer to the following code to package the whiteboard view:

example

import React from "react";

class WrappedComponent extends React.Component {

    render() {
        return (
            <div>
                <span>hello world</span>
                {this.props.children}
            </div>
        );
    }
}

const whiteWebSdk = new WhiteWebSdk({
    appIdentifier: "$APP_IDENTIFIER",
    wrappedComponents: [WrappedComponent],
});

WorldViewRectangle

WorldViewRectangle: { height: number; originX: number; originY: number; width: number }

Configurations for the view rectangle.

The view rectangle defines a rectangle area which the view must cover. After you set a view rectangle, the SDK automatically adjusts the view to fully contain the rectangle area, so as to ensure contents within the rectangle area are completely displayed.

You can set a rectangle according to the size of the PPT slide or image to be displayed, to ensure the same content is displayed completely on screens of different sizes.

Type declaration

height: number

The height of the view rectangle.

Do not set this property to a value smaller than the height of the area you want to display; otherwise, the user may not see the area completely.
originX: number

The X coordinate of the top left corner of the view rectangle in the world coordinate system (taking the center of the initial whiteboard as the origin).
originY: number

The Y coordinate of the top left corner of the view rectangle in the world coordinate system (taking the center of the initial whiteboard as the origin).
width: number

The width of the view rectangle.

Do not set this property to a value smaller than the width of the area you want to display; otherwise, the user may not see the area completely.

WrappedComponents

WrappedComponents: ReadonlyArray<ComponentType<{}>>

An array of React.ComponentType objects, which is used to package the whiteboard view. The default value is [].

Variables

Const AdminObserverId

AdminObserverId: number

The user ID of the event trigger.

Const AkkoVersion

AkkoVersion: any

The version of Akko.

Const DefaultHotKeys

DefaultHotKeys: Partial<HotKeys>

The default hotkeys.

Keys	Action
Backspace or Delete	Delete the selected object
Shift	Resize proportionately
Ctrl + Z or Command + Z	Undo
Ctrl + Y or Command + Y	Redo
Ctrl + C or Command + C	Copy
Ctrl + V or Command + V	Paste

Const DisplayerConsumer

DisplayerConsumer: Consumer<Displayer>

The Consumer for a Displayer object.

Const RoomConsumer

RoomConsumer: Consumer<Room | undefined>

The Consumer for a Room object.

Const WhiteVersion

WhiteVersion: string

The version of the current SDK in the string format. For example, "2.12.11".

Functions

contentModeAspectFill

contentModeAspectFill(): ContentMode

- Defined in index-en.d.ts:1328
Resizes the viewable area proportionately until its shorter sides meet with the screen sides perpendicular to them, so that the viewable area completely covers the screen.

Returns ContentMode

The actual scale factor.

contentModeAspectFillScale

contentModeAspectFillScale(scale: number): ContentMode

- Defined in index-en.d.ts:1339
Resizes the viewable area proportionately until its shorter sides meet with the screen sides perpendicular to them, so that the viewable area completely covers the screen. Then, resizes the viewable area by the specified scale factor.

Parameters
- scale: number
  
  The specified scale factor.
Returns ContentMode

The actual scale factor.

contentModeAspectFit

contentModeAspectFit(): ContentMode

- Defined in index-en.d.ts:1297
Resizes the viewable area proportionately until its longer sides meet with the screen sides perpendicular to them, so that the viewable area is completely displayed on the screen.

Returns ContentMode

The actual scale factor.

contentModeAspectFitScale

contentModeAspectFitScale(scale: number): ContentMode

- Defined in index-en.d.ts:1308
Resizes the viewable area proportionately until its longer sides meet with the screen sides perpendicular to them, so that the viewable area is completely displayed on the screen. Then, resizes the viewable area by the specified scale factor.

Parameters
- scale: number
  
  The specified scale factor.
Returns ContentMode

The actual scale factor.

contentModeAspectFitSpace

contentModeAspectFitSpace(space: number): ContentMode

- Defined in index-en.d.ts:1319
Resizes the viewable area proportionately until its longer sides meet with the screen sides perpendicular to them, so that the viewable area is completely displayed on the screen. Then, adds the specified spaces around the viewable area.

Parameters
- space: number
  
  The specified spaces in pixels.
Returns ContentMode

The actual scale factor.

contentModeScale

contentModeScale(scale: number): ContentMode

- Defined in index-en.d.ts:1288
Resizes the viewable area by the specified scale factor.

Parameters
- scale: number
  
  The specified scale factor.
Returns ContentMode

The actual scale factor.

createPPTTask

createPPTTask(params: PPTTaskParams): PPTTask

- Defined in index-en.d.ts:1044
Creates a PPTTask object.

After the app server starts a file-conversion task, the app client can create a PPTTask object by calling this function and passing in the Task Token and Task UUID obtained from the app server. You can get the progress and result of the file-conversion task through the callbacks for the PPTTask object.

Parameters
- params: PPTTaskParams
  
  Parameters of the PPTTask object.
Returns PPTTask

The created PPTTask object.

createPlugins

createPlugins<C_MAP>(plugins: Readonly<{}>): Plugins<C_MAP>

- Defined in index-en.d.ts:430
Creates a plugin.

Type parameters
- C_MAP: Object
Parameters
- plugins: Readonly<{}>
  
  The plugin to be created.
Returns Plugins<C_MAP>

injectCustomStyle

injectCustomStyle(icons: UserCursorIcons): void

- Defined in index-en.d.ts:3537
Adds a custom icon.

Parameters
- icons: UserCursorIcons
  
  The custom icon.
Returns void

isRoom

isRoom(displayer: Displayer): boolean

- Defined in index-en.d.ts:806
Determines whether the Displayer object is a Room object.

Parameters
- displayer: Displayer
  
  The Displayer object.
Returns boolean

Whether the Displayer object is a Room object:
- true: The Displayer object is a Room object.
- false: The Displayer object is not a Room object.

previewPPT

previewPPT(conversionResponse: ConversionResponse, container: HTMLDivElement, config?: PreviewConfig, preload?: boolean, userFonts?: UserFonts, logger?: Logger, pptPrams?: PptParams, events?: EventEmitter): EventEmitter

- Defined in index-en.d.ts:251
Previews the PowerPoint (PPT) file.

This function creates a new page for PPT preview, which is separate from the whiteboard page.

since

2.13.2

Parameters
- conversionResponse: ConversionResponse
  
  The response for querying the progress of PPT file conversion. See ConversionResponse.
- container: HTMLDivElement
  
  An empty HTML container.
- Optional config: PreviewConfig
  
  Configurations of the preview page. See PreviewConfig.
- Optional preload: boolean
  Whether to request the resources of the next slide in advance:
  - true: Request the resources of the next slide in advance. In this case, the response is saved using the browser cache.
  - false: Do not request the resources of the next slide in advance.
- Optional userFonts: UserFonts
  
  Custom fonts. See UserFonts.
- Optional logger: Logger
  
  PPT preview logs. Reserved for future use.
- Optional pptPrams: PptParams
  
  Other parameters related to PPT preview. See PptParams.
- Optional events: EventEmitter
  
  Events.
Returns EventEmitter

The EventEmitter object.

setAsyncModuleLoadMode

setAsyncModuleLoadMode(mode: AsyncModuleLoadMode): void

- Defined in index-en.d.ts:722
Sets the load mode of asynchronous modules.

Parameters
- mode: AsyncModuleLoadMode
  
  The load mode of asynchronous modules. See AsyncModuleLoadMode.
Returns void

Index

Enumerations

Classes

Interfaces

Type aliases

Variables

Functions

Type aliases

BroadcastState

Type declaration

Optional broadcasterId?: number

mode: ViewMode

Camera

Type declaration

centerX: number

centerY: number

scale: number

CameraBound

Type declaration

Optional centerX?: number

Optional centerY?: number

Optional damping?: number

Optional height?: number

Optional maxContentMode?: ContentMode

Optional minContentMode?: ContentMode

Optional width?: number

CameraState

Color

ConstructRoomParams

Type declaration

Optional cameraBound?: CameraBound

Optional cursorAdapter?: CursorAdapter

Optional disableAutoResize?: boolean

Optional disableCameraTransform?: boolean

Optional disableOthersSelectingBox?: boolean

Optional invisiblePlugins?: ReadonlyArray<InvisiblePluginClass<string, any, any>>

Optional wrappedComponents?: WrappedComponents

ContentMode

Type declaration

Parameters

screenSize: Size

boundSize: Size

Returns number

ConversionResponse

Type declaration

Optional failedReason?: string

progress: Progress

status: Status

type: ConversionType

uuid: string

ConvertedFile

Type declaration

conversionFileUrl: string

height: number

Optional preview?: string

width: number

CursorDescription

Type declaration

height: number

width: number

x: number

y: number

DisplayerCallbacks

Type declaration

onCatchErrorWhenAppendFrame: (userId: number, error: Error) => void

Parameters

userId: number

error: Error

Returns void

onCatchErrorWhenRender: (error: Error) => void

Parameters

error: Error

Returns void

onEnableWriteNowChanged: (enableWriteNow: boolean) => void

Parameters

enableWriteNow: boolean

Returns void

onHandToolActive: (active: boolean) => void

Parameters

active: boolean