# JS-SDK Documentation

# Download Link

raw-jssdk-v2.0.3

Description of the file directory structure after download:

├─ demo　　 // Main directory
　│　　├─html-demo　　 // Demo using native HTML/JS approach to integrate the SDK
　│　　│　　├─index.html　// Business code
　│　　│　　├─index.js　　// Business code
　│　　├─react-demo　 // React demo
　│　　
　├─ dist 　　
　 　　├─rtcsdk.min.js　　// Raw RTC SDK, packaged using the UMD format, compatible with script tags, import/require
　 　　├─esm
　 　　　　├─rtcsdk.js // Packaged using the ESM format, only supports import

# I. Integration Methods

# Script Tag Reference

rtcsdk.min.js is packaged using UMD

<script type='text/javascript' src="rtcsdk.min.js"></script>

# Import or Require Method

esm/rtcsdk.js is packaged using ESM

# II. API

# Instantiation

Initialization parameters

let rtcVideo = new RctVideo({
    videoWrapper: 'videoWrapper', // Container element for video insertion (requires ID attribute)
    host: 'wss://rtc-sgp.megvii.com', // Service address (wss protocol)
    width: '100%', // Video width (px, rem, em). Video scales proportionally to longest side
    height: 'auto', // Video height (px, rem, em)
    token: 'xxxxxxx', // Token from server-side getToken request (NEVER call from frontend)
    videoPermsTimeout: '6000', // Camera permission timeout (ms, optional)
    webSocketTimeout: '6000', // WebSocket timeout (ms, optional)
    WebRTCTimeout: '6000', // WebRTC connection timeout (ms, optional)
    colorListener: (color, status, index, sum)=>{}, // Color change callback
    tipListener: (tipCode, tipTxt)=>{}, // Tip message callback
    statusListener: (statusCode)=>{}, // Status change callback
    resultCallback: (isSuccess, resultCode, resultMessage)=>{}, // Result callback
    autoplayFailCallback: (play)=>{}, // Callback when auto-play fails
})
rtcVideo.start()

# Callback Parameter Descriptions

• colorListener(color, status, index, sum)

Parameter	Description
color	Color in HEX format (e.g. "#00FFFF")
status	RESET/DONE/COLORING RESET: Mirror stage failed DONE: Coloring complete COLORING: Coloring in progress
index	Current coloring progress (e.g. 1)
sum	Total colors (matches Raw-GetToken color_number)

• tipListener: (tipCode, tipTxt)

Parameter	Description
tipCode	Tip code identifier
tipTxt	Default tip text

Tip content may change with service updates. Only handle FaceOK errors.

tipCode	tipTxt
NoFaceFound	No face detected
InvalidFaceYaw	Face camera directly
InvalidFacePitch	Face camera directly
InvalidFaceEyeOcclusion	Keep eyes visible
InvalidFaceMouth	Keep mouth visible
TooFarAwayFromCamera	Move closer to camera
TooCloseFromCamera	Move farther from camera
InvalidFaceOutOfImage	Face camera directly
InvalidFaceBrightness	Adjust lighting
FaceOK	Hold still

• statusListener = (statusCode)

statusCode	Description
INIT_LOADING	Initial configuration loading
INIT_LOADING_OVER	Initial configuration complete
LOOK_MIRROR	Mirror stage (face adjustment)
SHOW_COLOR	Coloring stage
RESULT_LOADING	Processing results (loading)
RESULT_LOADING_OVER	Results processing complete
DISCONNECTED	WebRTC disconnected (refresh required)

• resultCallback = (isSuccess, resultCode, resultMessage)

isSuccess	Description
true	Process completed normally
false	Error occurred during process
resultCode	resultMessage	Description
------------	-------------------------------	-------------------------------------------------
1000	SUCCESS	Process completed normally
2000	DISCONNECTED	WebRTC disconnected
3000	TIMEOUT	30s timeout from connection establishment
4000	SUPPORT_ERROR	Device not supported (WebRTC unavailable)
4000	PERMISSIONS_ERROR	Camera permission denied/timeout
4000	NETWORK_ERROR	No data transmission within 6s of connection
5000	TOKEN_EXPIRED	Token expired/invalid/used
5000	TOKEN_TIMES_EXCEEDED	Token usage limit exceeded
5000	ILLEGAL_PARAMETER:{params}	Invalid initialization parameters

• autoplayFailCallback = (play)
  play is the playback method.

# start()

Starts verification (activates camera). Inserts video element into videoWrapper container.

rtcVideo.start()

# destroy()

Manually terminates process (closes WebRTC). Remove video element manually.

rtcVideo.destroy()

# version()

Gets SDK version

rtcVideo.version()

# III. Workflow

Main flow follows statusListener changes:

1. LOOK_MIRROR Stage: Detects face position/lighting. Triggers tipListener for user adjustments
2. SHOW_COLOR Stage: Triggers colorListener for background color changes. Maximize screen coverage
3. RESULT_LOADING: Processes results. Upon completion triggers resultCallback
4. DISCONNECTED: Network issues - requires page refresh

# IV. Common Issues & Solutions

1. Requires HTTPS
2. WebView Adaptation:
   • Android: https://blog.csdn.net/weixin_37939704/article/details/88554967
   • iOS: https://www.jianshu.com/p/e4452707e33a

# Directory Structure

├─ demo
　│　├─html-demo       // HTML/JS implementation
　│　│　├─index.html
　│　│　├─index.js
　│　├─react-demo      // React implementation
　
├─ dist
　　 ├─rtcsdk.min.js    // SDK (supports both script tags and modules)

# V. Changelog

v2.0.3 August 22, 2025

• Added host configuration (no default)
• Added regional service support

v2.0.2 October 11, 2024

• Updated WebSocket ICE message structure

v2.0.1 May 6, 2024

• Added ESM module format

v2.0.0 December 7, 2021

• Fixed class name (RctVideo → RtcVideo)
• Merged callbacks into resultCallback
• Added statusListener updates
• Added autoplayFailCallback
• Added version() method

v1.1.2 August 3, 2021

• Fixed destroy() exception on legacy devices

v1.1.1 June 25, 2021

• Fixed tipCode parameter error

v1.1.0 June 10, 2021

• Added destroy() method
• Improved network handling
• Fixed INIT_LOADING_OVER trigger logic