Agora Interactive Whiteboard Web SDK API Reference

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.

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.

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.

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 commandWheelToZoom?: boolean

  Whether to allow zooming the whiteboard by holding down the command key and scrolling the mouse wheel.

  since

  2.16.51

  • true: Allows zooming the whiteboard by holding down the command key and scrolling.
  • false (default): Disallows zooming the whiteboard by holding down the command key and scrolling.

  note

  • This property is only available on macOS systems.
  • This property does not affect the zoom behavior of the control wheel.

• Optional cursorAdapter?: CursorAdapter | false

  Sets the cursor adapter. Set to false to no longer display internal preset cursors (laser pen, eraser, etc.).

• 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 [].

Type declaration

• • (screenSize: Size, boundSize: Size): number

  • Parameters

    • screenSize: Size

    • boundSize: Size

    Returns number

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.

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.

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

Type declaration

• onBackgroundError: (url: string) => void

  Reports the failure of loading background image.

  • • (url: string): void

    • Parameters

      • url: string

      Returns void

• 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

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.

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.

Type declaration

• • (event: Event): boolean

  • Parameters

    • event: Event

    Returns boolean

Type declaration

• • (event: Event): void

  • Parameters

    • event: Event

    Returns void

Type declaration

• • (events: Event[]): void

  • Parameters

    • events: Event[]

    Returns void

Type declaration

• colors: ReadonlyArray<Readonly<Color>>

  The color palette of the floating bar.

Type declaration

Type declaration

• • (event: HotKeyEvent, kind: KeyboardKind): boolean

  • Parameters

    • event: HotKeyEvent

    • kind: KeyboardKind

    Returns boolean

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.

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.

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.

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

• Optional crossOrigin?: boolean | string

  Whether to load images in cross-origin mode.

  since

  2.16.48

  • true: (default) Load images in cross-origin mode.
  • false: Do not load images in cross-origin mode.

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

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

Type declaration

• displayer: Displayer

  The Displayer object of the invisible plugin.

• kind: string

  The type of the invisible plugin.

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.

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.

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.

Type declaration

• id: number

• payload: any

• session: string

Type declaration

• Optional arrowCompleteToSelector?: boolean

  Whether to automatically switch to the selection tool after drawing an arrow:

  • true: Automatically switch.
  • false: (Default) Do not automatically switch.

• 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 ellipseCompleteToSelector?: boolean

  Whether to automatically switch to the selection tool after drawing a circle:

  • true: Automatically switch.
  • false: (Default) Do not automatically switch.

• Optional fillColor?: Color

  Sets the fill color of the graphic element. Only applicable to closed shapes such as circles and rectangles.

• 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 rectangleCompleteToSelector?: boolean

  Whether to automatically switch to the selection tool after drawing a rectangle:

  • true: Automatically switch.
  • false: (Default) Do not automatically switch.

• Optional shapeCompleteToSelector?: boolean

  Whether to automatically switch to the selection tool after drawing a triangle, speech balloon, or other shapes:

  • true: Automatically switch.
  • false: (Default) Do not automatically switch.

• Optional shapeType?: ShapeType

  The shape type.

• Optional straightCompleteToSelector?: boolean

  Whether to automatically switch to the selection tool after drawing a straight line:

  • true: Automatically switch.
  • false: (Default) Do not automatically switch.

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

• Optional textCompleteToSelector?: boolean

  Whether to automatically switch to the selection tool after typing with the text tool:

  • true: Automatically switch.
  • false: (Default) Do not automatically switch.

• textSize: number

  The font size of the text. The Chrome browser automatically adjusts fonts smaller than 12 to 12.

• Optional textSizeOverride?: number

  Sets the default font size for the text tool. If not set, the default is to use textSize, which is the last set text size.

• Optional underline?: boolean

  Whether to underline the text:

  • true: Underline the text.
  • false: (Default) Do not underline the text.

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.

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

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.

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.

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

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.

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.

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.

Type declaration

• Optional international?: International

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

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.

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.

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.

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.

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.

Type declaration

• [dirPath: string]: WhiteScene[]

  The list of scenes under a scene directory.

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.

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

Type declaration

• height: number

  The height of the object.

• width: number

  The width of the object.

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.

Type declaration

• [key: string]: ReadonlyArray<string>

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

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.

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],
  });

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.