Remote Collaboration SDK for Web

The Remote Collaboration Web SDK lets web applications integrate remote collaboration meeting capabilities. Developers can build meeting entry points, expert consoles, dispatch workspaces, call handling, media controls, screen sharing, whiteboard, video pointing, video control, file upload, and file download in browser-based workflows.

1. Use Cases

• Add remote collaboration meeting entry points to a web management console.
• Build expert seats, dispatch consoles, or remote assistance workspaces.
• Receive meeting invitations initiated by glasses or mobile clients in the browser.
• Manage meeting members, contact status, camera, microphone, and media streams.
• Use freeze-frame annotation, whiteboard, video pointing, video control, screen sharing, and file upload during meetings.

2. Preparation And SDK Import

2.1 Preparation Checklist

Before integration, confirm the following items. Web SDK initialization, WebSocket signaling, and browser media capabilities all depend on these prerequisites.

Item	Purpose	How to prepare
Remote collaboration enabled	Confirms that the company account can use remote collaboration.	Confirm with the Rokid project manager, sales, or delivery contact.
npm registry access	Used to install rokid-xpert-sdk.	Make sure the development environment can access the Rokid npm registry.
Login token	SDK initialization parameter for user authentication.	Provided by the integrating app login state or backend service.
saasUrl	SDK initialization parameter for remote collaboration service requests.	Provided by the project environment configuration.
saasWssUrl	Optional parameter for WebSocket signaling.	Use project-specific values when provided.
rtcConfig	Optional parameter for RTC ICE Server and WebSocket configuration.	Use project-specific values when provided.
Browser media permissions	Required for camera, microphone, screen sharing, and related capabilities.	Users authorize these permissions in the browser; the business UI should handle denial prompts.
HTTPS or local development environment	Browser media capabilities usually require a secure context.	Use HTTPS in production. localhost can be used for local debugging.

If the page only needs signaling messages and does not need camera or microphone, onlyHttp can be used. Media device capabilities are unavailable when it is enabled.

2.2 Account And Authentication

The Remote Collaboration Web SDK integration guide does not require the Platform OpenAPI API_KEY to be configured in the browser. The web client needs the current login token, remote collaboration service URL, and available WebSocket / RTC configuration. These values usually come from the integrating app login state, backend service, or project environment configuration.

If the business backend also calls Platform OpenAPI to query meeting records, participants, meeting files, IM messages, or recordings, configure server-side authentication according to the Platform OpenAPI documentation. Keep the related secrets on the server side only. Do not put them into frontend code or expose them to the browser.

2.3 Import The SDK

The Web SDK package name is rokid-xpert-sdk.

If the project needs to configure an npm registry, use the Rokid npm registry provided for the project:

npm config set registry https://maven.rokid.com/repository/npm-group/
npm install rokid-xpert-sdk

Import it after installation:

import xpertSdk from 'rokid-xpert-sdk'

3. Initialization And Lifecycle

Initialization validates the token, fetches user information, registers the WebSocket signaling connection, and uploads device information.

await xpertSdk.initConfig({
  token,
  saasUrl
})

3.1 Initialization Parameters

Parameter	Required	Description
token	Yes	Login token of the current user.
saasUrl	Yes	Remote collaboration service URL.
saasWssUrl	No	WebSocket signaling service URL.
rtcConfig.iceServers	No	RTC ICE Server configuration.
rtcConfig.wssUrl	No	RTC WebSocket URL.
forceRefreshToken	No	Whether to force-refresh the internal RTC token when it expires. Defaults to true.
consoleLog	No	Whether to enable console logs.
showVersion	No	Whether to print SDK version information.
supportGuest	No	Set to 1 to support guest access.
onlyHttp	No	If true, media devices cannot be used, but WebSocket messages can still be received.

Type definitions:

type XPertCoreArgv = {
  token: string
  saasUrl: string
  saasWssUrl?: string
  rtcConfig?: {
    iceServers: IceServer[]
    wssUrl: string
  }
  forceRefreshToken?: boolean
  consoleLog?: boolean
  showVersion?: boolean
  supportGuest?: number
  onlyHttp?: boolean
}

type IceServer = {
  userName: string | null
  password: string | null
  urls: string[]
}

3.2 Global APIs

API	Description
initConfig(params)	Initialize the SDK.
refreshToken(token)	Refresh the SDK internal token.
setLanguage(lang)	Switch language. lang can be zh or en.
destroy()	Destroy the SDK and release WebSocket and media resources.

xpertSdk.refreshToken(token)
xpertSdk.setLanguage('en')
xpertSdk.destroy()

3.3 Global Event

xpertSdk.on('logout', () => {
  // Triggered when the user is forced offline, token expires, and similar cases.
})

3.4 Minimal Verification Path

For the first integration pass, verify the minimum path first:

1. npm can install rokid-xpert-sdk.
2. The page runs in HTTPS or localhost.
3. initConfig succeeds and does not trigger logout.
4. The contacts event can be received.
5. cameraCheck and microphoneCheck return normal results or clear permission prompts.
6. The page can receive a meeting invitation or join a test meeting.

4. Core Modules

xpertSdk is the main SDK instance and contains four primary modules.

Module	Description
userManager	User and contact management.
deviceManager	Camera, microphone, speaker, resolution, stream switching, and device checks.
meetingManager	Meeting invitation, meeting lifecycle, member state, and in-meeting message events.
extendManager	Freeze-frame annotation, whiteboard, video pointing, video control, AR annotation, screen sharing, and file management.

5. User Module: UserManager

The user module maintains current user information, contact lists, and contact status.

5.1 User Fields

Common current-user fields:

Field	Description
userId	User ID.
realName	Real name or display name.
userName	Username.
companyId	Company ID.
companyName	Company name.
avatar	Avatar URL.
phone / phoneNum	Phone number.
unitName	Department or organization name.

Common contact fields:

Field	Description
userId	Contact user ID.
userName / username	Username.
realName	Real name or display name.
status	Contact online status.
deviceType	Device type.
headPortrait	Avatar URL.
phoneNum / phoneNumber	Phone number.
postName	Position name.
unitName	Department or organization name.
tagName / tagStatus	Expert tag and tag status.
guestFlag	Guest flag. 0 means tenant user, 1 means guest.
personType	Person type. Common values: 1 normal user, 2 IPC user.

5.2 User APIs

API	Description
updateToken(token)	Update the token used by the user module.
getUserInfo(userId)	Get contact information by user ID.
destroy()	Destroy the user module and release user-related WebSocket connections.

xpertSdk.userManager.updateToken(token)

const user = xpertSdk.userManager.getUserInfo(userId)

xpertSdk.userManager.destroy()

5.3 Contact Event

xpertSdk.userManager.on('contacts', (data) => {
  // data is the latest contact list, including online/offline status.
})

6. Device Module: DeviceManager

The device module manages camera, microphone, speaker, picture quality, and media streams. Except for cameraCheck and microphoneCheck, device APIs usually need to be called during a meeting.

6.1 Device Checks

const cameraStatus = await xpertSdk.deviceManager.cameraCheck()
const microphoneStatus = await xpertSdk.deviceManager.microphoneCheck()

Common DeviceCheckResult values:

Value	Description
NORMAL	Device is normal.
DEVICE_PERMISSION_DENIED	Browser permission is denied.
DEVICE_NOT_FOUND	Device is not found.
DEVICE_UNKNOWN_ERROR	Unknown device error.

6.2 Audio/Video Device Control

API	Description
startCamera(restart?, deviceId?)	Start camera. A device ID can be specified.
stopCamera(restart?, deviceId?)	Stop camera. A device ID can be specified.
startMicrophone(restart?, deviceId?)	Start microphone. A device ID can be specified.
stopMicrophone(restart?)	Stop microphone.
switchAudioOutput(enable)	Enable or disable speaker output.
toggleFrontCamera(isFront?)	Switch front/rear camera.

await xpertSdk.deviceManager.startCamera()
await xpertSdk.deviceManager.stopCamera()

await xpertSdk.deviceManager.startMicrophone()
await xpertSdk.deviceManager.stopMicrophone()

xpertSdk.deviceManager.switchAudioOutput(true)
await xpertSdk.deviceManager.toggleFrontCamera(true)

6.3 Quality And Stream Control

API	Description
selectVideoConstraints(value)	Switch resolution, such as 360P, 720P, or 1080P.
switchStream(userId, isHighStream)	Switch large/small stream for a user.
getStreamInfo(userId)	Get stream information for a user. Invalid outside meetings.
setPictureMode(userId, mode)	Set picture mode. 0 means fluent, 1 means HD.

await xpertSdk.deviceManager.selectVideoConstraints('720P')
await xpertSdk.deviceManager.switchStream(userId, true)
await xpertSdk.deviceManager.setPictureMode(userId, 1)

const streamInfo = await xpertSdk.deviceManager.getStreamInfo(userId)

6.4 Device Events

xpertSdk.deviceManager.on('microphone-change', (deviceList) => {
  // Microphone device list changed.
})

xpertSdk.deviceManager.on('camera-change', (deviceList) => {
  // Camera device list changed.
})

xpertSdk.deviceManager.on('video-mode', ({ userId, mode }) => {
  // Member picture mode changed.
})

7. Meeting Module: MeetingManager

The meeting module receives meeting invitations, lifecycle updates, member state changes, media status changes, IM messages, and SDK reconnect events.

7.1 Meeting Invitation

xpertSdk.meetingManager.on('invite', (data) => {
  // data: { userId, meetingId, meetingName, maxResolution }
})

Field	Description
userId	Inviter user ID.
meetingId	Meeting ID.
meetingName	Meeting name.
maxResolution	Maximum meeting resolution.

7.2 Meeting Started

xpertSdk.meetingManager.on('meeting-start', (meetingInfo) => {
  // meetingInfo is the in-meeting state.
})

Common MeetingLife fields:

Field	Description
meetingId	Meeting ID.
members	Meeting member list.
moderator	Moderator user ID.
speaker	Speaker output state.
meetingMuted	Whether the meeting is muted.
isRecord	Whether recording is active.
shareInfo	In-meeting sharing state.

7.3 Member State Events

xpertSdk.meetingManager.on('remote-join', (data) => {
  // A remote member joined the meeting.
})

xpertSdk.meetingManager.on('remote-leave', (data) => {
  // A remote member left the meeting.
})

xpertSdk.meetingManager.on('remote-refuse', (data) => {
  // A remote member refused the invitation.
})

Event	Description
remote-join	A remote member joins. Returns userId, latest members, and joinType.
remote-leave	A remote member leaves. Returns userId and latest members.
remote-refuse	A remote member refuses the invitation. Returns the user ID.

7.4 Meeting State Events

xpertSdk.meetingManager.on('busy-invite', (data) => {
  // Another meeting invitation is received during a meeting.
})

xpertSdk.meetingManager.on('meeting-end', ({ type }) => {
  // type: close | leave
})

xpertSdk.meetingManager.on('meeting-muted', ({ userId }) => {
  // Meeting mute event.
})

7.5 Media Status, IM, And Reconnect

xpertSdk.meetingManager.on('media-status', ({ userId, mediaStatus }) => {
  // mediaStatus only includes changed media fields.
})

xpertSdk.meetingManager.on('im-message', (data) => {
  // In-meeting IM message.
})

xpertSdk.meetingManager.on('sdk-reconnect', ({ status, meetingId }) => {
  // status: start | success
})

Common mediaStatus fields:

Field	Description
audio	Microphone state.
video	Camera state.
netQuality	Network quality. Common values: 0 unknown, 1 excellent, 2 good, 3 poor.

8. Extension Module: ExtendManager

The extension module manages in-meeting sharing and collaboration capabilities.

Property	Description
shareDoodleManage	Freeze-frame annotation and whiteboard.
shareVideoDrawManage	Video pointing.
shareVideoControlManage	Video control.
shareARManage	AR annotation.
shareScreenManage	Screen sharing.
fileManage	File upload and management.

9. Freeze-Frame Annotation / Whiteboard: ShareDoodleManage

xpertSdk.extendManager.shareDoodleManage.addDoodle(canvasName, {
  canvasHeight,
  canvasWidth,
  panColor
})

xpertSdk.extendManager.shareDoodleManage.setDoodleParams({
  panColor: '#1677ff',
  panSize: 4
})

await xpertSdk.extendManager.shareDoodleManage.startShareDoodle(
  meetingId,
  doodleImageUrl
)

await xpertSdk.extendManager.shareDoodleManage.joinShareDoodle(meetingId)
await xpertSdk.extendManager.shareDoodleManage.stopShareDoodle(meetingId)

API	Description
addDoodle(canvasName, options)	Initialize annotation with a canvas name and canvas options.
setDoodleParams(params)	Set pen color and pen width.
startShareDoodle(meetingId, doodleImageUrl, domain?, replaceDomain?)	Start whiteboard or screenshot annotation. If doodleImageUrl is empty, whiteboard annotation starts. If it has a value, screenshot annotation starts.
joinShareDoodle(meetingId)	Join annotation by meeting ID.
stopShareDoodle(meetingId)	Stop annotation.
revoke(userId?)	Revoke one stroke.
clearAll()	Clear all annotations.
save()	Save the freeze-frame image and return base64.
generateDoodleBg(videoId)	Generate an image from the current video element.

Event:

xpertSdk.extendManager.shareDoodleManage.on('doodle', ({ msg, action }) => {
  // action: start | end
})

msg.message.msgBody.actionType common values: 0 add, 1 revoke, 2 clear.

10. Video Pointing: ShareVideoDrawManage

xpertSdk.extendManager.shareVideoDrawManage.addVideoDraw(canvasName, {
  deviceRatio,
  canvasHeight,
  canvasWidth,
  brushWidth,
  brushColor,
  sdkRender
})

xpertSdk.extendManager.shareVideoDrawManage.setVideoDrawParams({
  brushWidth: 4,
  color: 0xff0000
})

await xpertSdk.extendManager.shareVideoDrawManage.beginVideoPoint(
  executorUserId,
  promoterUserId
)

await xpertSdk.extendManager.shareVideoDrawManage.endVideoPoint(
  executorUserId,
  promoterUserId
)

API	Description
addVideoDraw(canvasName, options)	Initialize video pointing.
setVideoDrawParams(params)	Set video pointing pen parameters.
beginVideoPoint(executorUserId, promoterUserId)	Start video pointing.
endVideoPoint(executorUserId, promoterUserId)	Stop video pointing.

Events:

xpertSdk.extendManager.shareVideoDrawManage.on('videopoint', ({ msg, action }) => {
  // action: start | end
})

xpertSdk.extendManager.shareVideoDrawManage.on('backVideoPoints', (nowClickList) => {
  // The business layer can render points when sdkRender is disabled.
})

msg.message.msgBody.actionType common values: 0 new point, 1 connection request, 2 connection response.

11. Video Control: ShareVideoControlManage

xpertSdk.extendManager.shareVideoControlManage.addVideoControl(canvasName, {
  deviceRatio,
  canvasHeight,
  canvasWidth
})

xpertSdk.extendManager.shareVideoControlManage.beginVideoControl(currUserId)
xpertSdk.extendManager.shareVideoControlManage.endVideoControl()

xpertSdk.extendManager.shareVideoControlManage.sendVideoControl(
  ctrType,
  currUserId,
  scale,
  pointF
)

const image = await xpertSdk.extendManager.shareVideoControlManage.save(videoId)

API	Description
addVideoControl(canvasName, options)	Initialize video control.
beginVideoControl(currUserId)	Start video control.
endVideoControl()	Stop video control.
sendVideoControl(ctrType, currUserId?, scale?, pointF?)	Send a video control notification.
save(videoId)	Save the video control frame and return base64 and blob.

Event:

xpertSdk.extendManager.shareVideoControlManage.on('videocontroll', ({ msg, action }) => {
  // Video control action.
})

Common msg.message.msgBody.ctrType values: 2 turn on flashlight, 4 turn off flashlight, 6 zoom.

12. Screen Sharing: ShareScreenManage

await xpertSdk.extendManager.shareScreenManage.startShare('720P')
await xpertSdk.extendManager.shareScreenManage.stopShare()

API	Description
startShare(constraints?)	Start screen sharing. constraints can be 360P, 480P, 720P, or 1080P.
stopShare()	Stop screen sharing.

Events:

xpertSdk.extendManager.shareScreenManage.on('start-share', ({ userId, shareInfo }) => {
  // userId is the screen sharing initiator.
})

xpertSdk.extendManager.shareScreenManage.on('stop-share', ({ userId, shareInfo }) => {
  // userId is the user who stopped screen sharing.
})

13. File Upload And Management: FileManage

File management is available through xpertSdk.extendManager.fileManage. Supported default file formats include image/*, video/mp4, video/mpeg, .mov, .mkv, and application/pdf.

API	Description
formats	Current supported upload formats.
meetingLife	Current meeting state.
setFormats(formats)	Set supported upload formats.
selectFile()	Open file picker and upload selected file.
getMeetingFiles(meetingId)	Get uploaded files for a meeting.
batchDownload({ files, packageName })	Download files in a batch.

xpertSdk.extendManager.fileManage.setFormats([
  'image/*',
  'video/mp4',
  'application/pdf'
])

await xpertSdk.extendManager.fileManage.selectFile()

const files = await xpertSdk.extendManager.fileManage.getMeetingFiles(meetingId)

await xpertSdk.extendManager.fileManage.batchDownload({
  files,
  packageName: 'meeting-files'
})

File upload event:

xpertSdk.extendManager.fileManage.on('file-upload', ({ message, fromUserId }) => {
  // message is file information. fromUserId is the uploader ID.
})

14. Integration Notes

• Prepare a valid user token, remote collaboration service URL, and required WebSocket / RTC configuration before initialization.
• Use onlyHttp only when the page only needs signaling messages. Media device capabilities are unavailable when it is enabled.
• Device control, stream switching, video pointing, and video control usually need to be called during a meeting.
• Call destroy() when the page unloads, the user logs out, or the account changes.
• Remove event listeners when the page is destroyed to avoid duplicate UI reactions.
• For meeting records, participants, files, IM messages, and recording list queries, see Platform OpenAPI: Remote Collaboration.