Before joining a real-time room, you need to construct a room object. You can read the 《Real-time Room》 chapter of the advanced tutorial to have a good understanding of the process.
You can join a room with the following code, and get the room object in the callback method.
var joinRoomParams = {...};
var roomCallbacks = {...};
whiteWebSdk.joinRoom(joinRoomParams, roomCallbacks)
.then(function (room) {
// Join the room successfully and get the room object
})
.catch(function (error) {
// Failed to join the room, get the error object
});
Among them, the signature of joinRoom is like this.
interface Room {
joinRoom(params: JoinRoomParams, callbacks?:Partial<RoomCallbacks>): Promise<Room>
};
The second parameter of the method callbacks?:Partial<RoomCallbacks> is the initialized callback function. We will explain it in the last part of this chapter.
The type of the first parameter of the method JoinRoomParams is the most important part of joining the room, and its definition is as follows.
type JoinRoomParams = {
readonly uuid: string;
readonly uid: string;
readonly roomToken: string;
readonly userPayload?: any;
readonly isWritable?: boolean;
readonly disableDeviceInputs?: boolean;
readonly disableCameraTransform?: boolean;
readonly disableBezier?: boolean;
readonly disableAutoResize?: boolean;
readonly cursorAdapter?: CursorAdapter;
readonly cameraBound?: CameraBound;
readonly disableEraseImage?: boolean;
readonly floatBar?: boolean | Partial<FloatBarOptions>;
readonly hotKeys?: Partial<HotKeys>;
readonly invisiblePlugins?: ReadonlyArray<InvisiblePluginClass<string, any>>;
readonly wrappedComponents?: WrappedComponents;
readonly rejectWhenReadonlyErrorLevel?: RoomErrorLevel;
};
The uuid of the room, which is returned when the room is constructed, is the unique identifier of the room.
The unique id of each client. It should not exceed 1024 bytes.
The Token of the room, used for authentication. Read 《Access Key｜Project and Authentication》 to understand how to check out the Token of the room.
It can be any type of data structure used to describe the custom information of the current user. The `ʻuserPayload`` set by the user in the room when joining the room can be read by other users in the room with the following code.
for (var member of room.state.roomMembers) {
// Read the userPayload field of a user in the room
console.log(member.userPayload);
}
In particular, if the type of userPayload is object and contains the userId field, this field will be included in each log and reported (if the log reporting function is not turned off).
Whether to join the room in writable mode, the default is true, if it is false, it is read-only mode. Note the distinction between "read-only mode" and "prohibited device operation", refer to the advanced tutorial 《read-only mode｜prohibited operation》
Whether to prohibit device operation, the default is false. Note the distinction between "read-only mode" and "prohibit device operation". For details, please refer to the advanced tutorial 《prohibit device operation|prohibit operation》.
Whether to prohibit the pencil tool (currentApplianceName="pencil") to draw strokes with Bezier curve, the default is false.
The floating bar that appears after selecting an object with the selection tool (currentApplianceName="selector").
If it is false (default value), the floating bar will never appear. If it is true, a floating bar will appear. In addition, it can also be an object of type FloatBarOptions, which is defined as follows.
type FloatBarOptions = {
// The color list of the floating bar palette
readonly colors?: readonly Readonly<Color>;
}
// An array composed of 3 to 4 components from 0 to 255, representing the values of R, G, B, and A respectively
type Color = readonly number[];
Used to configure hot keys. If not, use the default hotkey scheme, as follows.
| Keyboard keys | Effect |
|---|---|
| Backspace / Delete | Delete the selected object |
| Shift | Lock the zoom aspect ratio so that it is zoomed in proportions |
| ctrl + z / command + z | Withdraw |
| ctrl + y / command + y | Redo |
| ctrl + c / command + c | copy |
| ctrl + v / command + v | Paste |
If you want to turn off the hotkey function, you can set its value to {}. The type of hotKeys is Partial<HotKeys>, and its definition is as follows.
type HotKeys = {
// Reissue
readonly duplicate: HotKey;
// copy
readonly copy: HotKey;
// paste
readonly paste: HotKey;
// Withdraw
readonly undo: HotKey;
// redo
readonly redo: HotKey;
// delete
readonly delete: HotKey;
// Lock the zoom ratio
readonly lock: HotKey;
// Switch to the selection tool (selector)
readonly changeToSelector: HotKey;
// Switch to laser pointer (laserPointer)
readonly changeToLaserPointer: HotKey;
// Switch to the pencil tool (pencil)
readonly changeToPencil: HotKey;
// Switch to the rectangle tool (rectangle)
readonly changeToRectangle: HotKey;
// Switch to the circle tool (ellipse)
readonly changeToEllipse: HotKey;
// Switch to the eraser tool (eraser)
readonly changeToEraser: HotKey;
// Switch to the straight line tool (straight)
readonly changeToStraight: HotKey;
// switch to arrow tool (arrow)
readonly changeToArrow: HotKey;
// Switch to the hand tool (handle)
readonly changeToHand: HotKey;
};
// keyboard type
enum KeyboardKind {
Mac = "mac", // mac keyboard
Windows = "windows", // windows keyboard
}
// Hotkey type, as the value of HotKeys
type HotKey = string | HotKeyDescription | ReadonlyArray<string | HotKeyDescription> | HotKeyChecker;
type HotKeyDescription = {
// keyboard keys
readonly key: string;
// Whether to press the alt key at the same time
readonly altKey: boolean | null;
// Whether to press the ctrl key at the same time
readonly ctrlKey: boolean | null;
// Whether to press the shift key at the same time
readonly shiftKey: boolean | null;
};
// Check whether the hotkey conditions are met
type HotKeyChecker = (event: HotKeyEvent, kind: KeyboardKind) => boolean;
type HotKeyEvent = {
// JavaScript native keyboard events
readonly nativeEvent?: KeyboardEvent;
// press or release
readonly kind: "KeyDown" | "KeyUp";
// keyboard keys
readonly key: string;
// Whether the alt key was pressed
readonly altKey: boolean;
// Whether the ctrl key is pressed
readonly ctrlKey: boolean;
// Whether the shift key is pressed
readonly shiftKey: boolean;
};
For example, in the following ways, ctrl + c can be bound to the "Withdraw" button.
// Based on HotKeyDescription definition
whiteWebSdk.joinRoom({
uuid: "$uuid",
roomToken: "$roomToken",
hotKeys: {
undo: {key: "c", ctrlKey: true},
},
});
// Based on HotKeyChecker definition
whiteWebSdk.joinRoom({
uuid: "$uuid",
roomToken: "$roomToken",
hotKeys: {
undo: function(event, kind) {
return (
kind === "windows" &&
event.key === "c" &&
event.ctrlKey
);
},
},
});
It is decided that if the write operation is actively invoked when the room does not have the write permission, what response the SDK should do at this time. Its type is the enumeration RoomErrorLevel The definition is as follows.
enum RoomErrorLevel {
// When the write operation is performed without permission, an error will be thrown directly
ThrowError = "throwError",
// Execute write operation when there is no right to write, intercept operation, and print warning on console
Warn = "warn",
// Execute write operation when there is no right to write, intercept operation, do nothing
Ignore = "ignore",
}
Before you need to play back a video, you need to construct a player object. You can read the ["Replay"] (/javascript-zh/home/replay) chapter of the advanced tutorial to have a good understanding of the process.
You can start playback with the following code and get the player object in the callback method.
var replayRoomParams = {...};
var replayCallbacks = {...};
whiteWebSdk.replayRoom(replayRoomParams, replayCallbacks)
.then(function (player) {
// Successful playback, get the player object
})
.catch(function (error) {
// Replay failed, get error object
});
The method signature of replayRoom is as follows.
replayRoom(params: ReplayRoomParams, callbacks?: Partial<PlayerCallbacks>): Promise<Player>
The second parameter of the method callbacks?:Partial<PlayerCallbacks> is the initialized callback function. We will explain it in the last part of this chapter.
The type of the first parameter of the method ReplayRoomParams is the most important part of joining the room, and its definition is as follows.
type ReplayRoomParams = {
readonly slice?: string;
readonly room?: string;
readonly beginTimestamp?: number;
readonly duration?: number;
readonly mediaURL?: string;
readonly cursorAdapter?: CursorAdapter;
readonly cameraBound?: CameraBound;
readonly disableAutoResize?: boolean;
readonly disableCameraTransform?: boolean;
readonly invisiblePlugins?: ReadonlyArray<InvisiblePluginClass<string, any>>;
readonly wrappedComponents?: WrappedComponents;
};
Specify the uuid to play back a specific "video clip". You can get it from room.slice while the room is still recording.
When this parameter is passed in, it indicates that only specific clips are played back, so it is forbidden to pass in room, beginTimestamp, and duration.
The uuid that specifies a specific room will be returned when the room is constructed. It is the unique identifier of the room. After passing in this parameter, it is prohibited to pass in the slice parameter.
If only this parameter is passed, and beginTimestamp and duration are not passed, it means that all video clips in the room are played back.
If it is passed in at the same time, beginTimestamp and duration, it means that all the video clips in this room are played back.
The timestamp indicating the start of the playback (unix time, in milliseconds). This parameter must be used together with room and duration, and it is forbidden to pass in the slice parameter when using it.
Indicates the duration of the playback interval (in milliseconds). This parameter must be used together with room and beginTimestamp, and it is forbidden to pass in the slice parameter when using it.
A URL accessible on the public network should point to a media file. During playback, this media file will be played synchronously, and the time axis will be aligned automatically.
Whether you are joining a real-time room or replaying a video, its parameters JoinRoomParams and ReplayRoomParams have some common fields, and their definitions are as follows.
To set the mouse cursor adapter, refer to 《Mouse Cursor Adapter》.
Whether to turn off the "Auto Fit Size" function, the default is false. After closing, whenever the view size of the whiteboard changes, you must actively call room.refreshViewSize() to adapt.
Whether to prohibit the device from actively operating the viewing angle, the default is false.
List of invisible plugins.
The default value is []. This is an array filled with React.ComponentType type, used to package the whiteboard view. You can use it to customize the whiteboard view.
The viewing angle boundary, the user's viewing angle will be limited to this range, beyond this range, the viewing angle will be pulled back. Its type CameraBound is defined as follows.
type CameraBound = {
// The damping size when the screen breaks through the boundary, the value range is 0.0 ~ 1.0
// The greater the damping, the greater the damping. When 1.0 is taken, no matter how you pull it, the angle of view cannot break the boundary
// The smaller the damping, the smaller the damping. When 0.0 is set, the angle of view can be pulled out of the boundary without resistance, and will rebound only when you let go
// The default value is 0.75
readonly damping?: number;
// The x coordinate of the center point of the boundary in the world coordinate system
// The default value is 0.0
readonly centerX?: number;
// The y coordinate of the center point of the boundary in the world coordinate system
// The default value is 0.0
readonly centerY?: number;
// The width of the boundary in the world coordinate system. If Infinity is taken, it means that there is no restriction on the horizontal direction
// The default value is Infinity
readonly width?: number;
// The height of the boundary in the world coordinate system. If Infinity is taken, it means that there is no restriction on the vertical direction
// The default value is Infinity
readonly height?: number;
// Restricted mode of viewing angle zoom
// There is no limit if you leave it blank
readonly maxContentMode: ContentMode;
// Restricted mode of viewing angle reduction
// There is no limit if you leave it blank
readonly minContentMode: ContentMode;
}
Among them, ContentMode is used to set the viewing angle's restriction on zooming, we can set it in the following way.
import sdk from "white-web-sdk";
// scale is 2.5
sdk.contentModeScale(2.5);
// Scaling to the extent that the short side of the bounding rectangle just touches the screen
sdk.contentModeAspectFill();
// The short side of the bounding rectangle just touches the screen, and then scales it by 2.5 times on this basis
sdk.contentModeAspectFillScale(2.5);
// Zoom to the point where the complete bounding rectangle can be seen on the screen
sdk.contentModeAspectFit();
// Just to the extent that the complete bounding rectangle can be seen on the screen, on this basis, zoom in and out by 0.75 times
sdk.contentModeAspectFitScale(0.75);
// When the zoom is just enough to see the complete bounding rectangle on the screen, and 120 px of empty space is reserved around
sdk.contentModeAspectFitSpace(120);
Refer to the method signatures of joinRoom and replayRoom in the previous chapter to see the two types of RoomCallbacks and PlayerCallbacks. They define the callback method signature of the real-time room and playback, which are defined as follows.
// The callback method signature of the real-time room
type RoomCallbacks = DisplayerCallbacks & {
readonly onPhaseChanged: (phase: RoomPhase) => void;
readonly onRoomStateChanged: (modifyState: Partial<RoomState>) => void;
readonly onDisconnectWithError: (error: Error) => void;
readonly onKickedWithReason: (reason: string) => void;
readonly onCanUndoStepsUpdate: (canUndoSteps: number) => void;
readonly onCanRedoStepsUpdate: (canUndoSteps: number) => void;
readonly willInterceptKeyboardEvent: (event: KeyboardEvent) => boolean;
readonly onKeyDown: (event: KeyboardEvent) => void;
readonly onKeyUp: (event: KeyboardEvent) => void;
};
// Signature of callback method for playback video
type PlayerCallbacks = DisplayerCallbacks & {
readonly onIsPlayableChanged: (isPlayable: boolean) => void;
readonly onPhaseChanged: (phase: PlayerPhase) => void;
readonly onLoadFirstFrame: () => void;
readonly onPlayerStateChanged: (modifyState: Partial<PlayerState>) => void;
readonly onStoppedWithError: (error: Error) => void;
readonly onProgressTimeChanged: (progressTimestamp: number) => void;
};
// Signature of callback method common to real-time room and playback video
type DisplayerCallbacks = {
readonly onEnableWriteNowChanged: (enableWriteNow: boolean) => void;
readonly onHandToolActive: (active: boolean) => void;
readonly onSliceChanged: (slice: string) => void;
readonly onCatchErrorWhenAppendFrame: (userId: number, error: Error) => void;
readonly onCatchErrorWhenRender: (error: Error) => void;
readonly onPPTLoadProgress: (uuid: string, progress: number) => void;
readonly onPPTMediaPlay: (shapeId: string, type: MediaType) => void;
readonly onPPTMediaPause: (shapeId: string, type: MediaType) => void;
};
Take the callback method of "the user is presented to the room" as an example. We can use the following code to register a callback method when we just join the room.
whiteWebSdk.joinRoom({uuid: "$uuid", roomToken: "$roomToken"}, {
"onKickedWithReason": function(reason) {
console.log("kicked by server with reason:" + reason);
},
});
You can also wait until the room is successfully added and the room object is obtained before registering the callback method.
room.callbacks.on("onKickedWithReason", function(reason) {
console.log("kicked by server with reason:" + reason);
});
You can also cancel the previously registered callback method.
function onKicked(reason) {
console.log("kicked by server with reason:" + reason);
}
// Register callback method
room.callbacks.on("onKickedWithReason", onKicked);
// Logout callback method
room.callbacks.off("onKickedWithReason", onKicked);
It is also possible not to specify the callback method, and cancel all the callback methods registered before.
room.callbacks.off("onKickedWithReason");
You can also register a one-time callback, which will automatically unregister itself after the first call.
room.callbacks.once("onKickedWithReason", function(reason) {
console.log("kicked by server with reason:" + reason);
});
In particular, you can do a similar operation to player.callbacks, which is not an example here.
The methods in DisplayerCallbacks are the common callback methods of room and player. In the following, I will use displayer to mean room or player.
It means that displayer.enableWriteNow has changed.
Indicates that displayer.handToolKey has changed.
displayer.slice has changed.
The signature is (userId: number, error: Error) => void. Indicates that the behavior of a certain user (the user indicated by userId) reported an error during synchronization. Generally speaking, this error report can usually be ignored. Please decide whether to monitor it according to the business situation.
Indicates that an error occurred while rendering the screen.
The progress callback of loading to web page PPT, the signature is (uuid: string, progress: number) => void. Among them, uuid is the taskUUID of the PPT, and progress is a number from 0.0 to 1.0, indicating the progress.
It indicates that the media resource corresponding to a certain shape in the PPT of the webpage has started to play.
It indicates that the media resource corresponding to a certain shape in the PPT of the webpage is suspended.
RoomCallbacks is a unique callback method for room.
Indicates that the room.phase has changed. It will pass a phase parameter, its meaning can refer to 《Real-time Room State Management》. The definition of its type RoomPhase is as follows.
Indicates that room.state has changed. For details, please refer to 《Business State Management of Room and Playback》.
There was an error in the real-time room and it was disconnected as a result.
Was taken out of the room, and was therefore disconnected. The value of the callback parameter reason will indicate the reason for being kicked out.
reason field |
description |
|---|---|
| kickByAdmin | kicked out by administrator |
| roomDelete | Room was deleted |
| roomZombie | Room is inactive |
| roomBan | Room is banned |
| GatewayAdjust | Gateway Adjustment |
| replaceByOther | Replaced by another user, the current user is forced to go offline |
| crash | server crash |
Indicates that room.canUndoSteps has changed.
Indicates that room.canRedoSteps has changed.
Interceptor, declare whether to intercept keyboard events monitored by the whiteboard, if it returns true, it will be intercepted. After intercepting, the keyboard event will not trigger the business response of the whiteboard.
The whiteboard has monitored the keyboard press event.
The whiteboard monitored the keyboard release event.
PlayerCallbacks is a unique callback method for player.
Indicates that player.isPlayable has changed.
Indicates that player.phase has changed.
Indicates that the first frame is loaded. This callback can be adjusted at most once in the entire life cycle of player. Before the first frame is loaded, the whiteboard will not display anything in the video, nor can it read ``player.state'' in the code.
Indicates that player.state has changed. For details, please refer to 《Business State Management of Room and Playback》.
An error occurred during playback and therefore failed, and the status of player.phase became PlayerPhase.Stopped.
Indicates that player.progressTime has changed.