Browser script
Update time: 2024/03/14 18:45:31
IM SDK(Web) provides complete messaging features for PC and Mobile Web apps, Node.js, React Native, WeChat Mini Program, ByteDance, and other cross-platform apps which can shield internal complex details and provide a simple API API for the third-party apps to fast integrate IM features.
Web-SDK browser environment is compatible with mainstream desktop browsers such as IE9+ (IE10 and later for audio and video), Edge, Chrome 58+, Safari 10+, Firefox 54+; Compatible with smartphones of iPhone 5s and later (iOS 8.0+) and built-in WeChat browser; Chrome browser for mainstream Android 5+ system and built-in WeChat browser.
Web-SDK cross-platform environment supports many scene apps, for example, WeChat Mini Program/ByteDance Microapp, React Native, Node.js.
Install IM SDK
- To use messaging, add
NIM_Web_NIM_*.js
and initialize an IM instance usingNIM.getInstance({...})
. - To use chat room, add
NIM_Web_Chatroom_*.js
and initialize a chat room instance usingChatroom.getInstance({...})
. - If you want to use messaging and chat room, add
NIM_Web_SDK_*.js
and initialize IM and chat room instance withSDK.NIM.getInstance({...})
andSDK.Chatroom.getInstance({...})
.
Add IM dependency
Download IM SDK and get IM SDK for Web.
Notes: CommsEase Web IM SDK is compatible with IE9+ (v5.0.0 and earlier versions are available to IE8). IE8/IE9 can be connected to CommsEase server only when the project is deployed under HTTPS environment. Other advanced browsers can be connected to CommsEase IM server under HTTP or HTTPS environment.
Integration at cross-platform environment
The operation method of cross-platform features related API from CommsEase Web-SDK is basically the same with JavaScript invoking mode under browser environment, which can reduce learning costs for users. Definitely, SDK will also make some adaptations based on some differences among different platforms, for example, "use database", "upload file", "restrict WebSocket", etc.
Applet
Applet overview
Please visit SDK download page to get Web-SDK of the latest applet.
- WeChat Mini Program: Available from
v5.1.0
. - ByteDance Microapp: Available from
v7.8.0
.
The global variable is "window" for browser environment and "wx" for applet, so that they have different attributes. To implement compatibility and adaptability, SDK will mock some attributes (e.g. navigator, location, io) to global, which will not influence ordinary application of users.
The number of WebSocket connections
WeChat Mini Program v1.7.0 and later allow maximum 5 WebSocket connections. Therefore, connection count must be controlled when multiple sockets are used.
When users switch account and use new instance of chat room, in order not to exceed limitation of applet WS connection, they must executedestroy
of IM/chat room instance and then try new connection in callbackdone
.
A whitelist of domain names
A list of related configurations:
-
Legal domain name of request:
- https://lbs.netease.im
- https://wlnimsc0.netease.im (required for IM)
- https://wlnimsc1.netease.im (required for chat room)
-
Legal domain name of socket:
- wss://wlnimsc0.netease.im (required for IM)
- wss://wlnimsc1.netease.im (required for chat room)
-
Legal domain name of uploadFile:
- https://nos.netease.com (required for uploading file, for example, sending file message)
-
Legal domain name of downloadFile:
- https://nim-nosdn.netease.im (required for downloading CommsEase resource file, for example, downloading audio file)
React Native
React Native overview
From v5.3.0, CommsEase Web-SDK is adaptive to React Native. RN version >=0.51 is recommended. The operation method of most APIs of CommsEase WebSDK React Native (hereinafter referred to as "RN-SDK") is same with Web browser environment for SDK in order to reduce obstacles resulting from using SDK by developers.
For information on related SDK files, contact CommsEase technical support.
Local database
RN-SDK supports the mode of application with and without database. You can select independently based on service scene of developers.
- If database is not used,
db
shall be set tofalse
at the operation of IM initialization, for example:
javascript const nim = NIM.getInstance({
debug: true,
appKey: appKey,
account: account,
token: token,
db: false, // don't use database
onconnect: onConnect,
onwillreconnect: onWillReconnect,
ondisconnect: onDisconnect,
onerror: onError
});
- If the database is used, developers shall install realm. It's available to use
sqlite3
as local database although RN-SDK currently does not support it. You can plug in SDK instance to database withusePlugin
as below:
javascript const SDK = require('NIM_Web_SDK_vx.x.x.js');
const Realm = require('realm');
// The external realm database is mounted to the sdk for use
SDK.usePlugin({
db: Realm,
});
const nim = SDK.NIM.getInstance({
debug: true,
appKey: appKey,
account: account,
token: token,
db: true, // use database
onconnect: onConnect,
onwillreconnect: onWillReconnect,
ondisconnect: onDisconnect,
onerror: onError
});
Local log
RN-SDK supports storing logs locally and and remote acquire logs remotely. Developers can select to enable local log feature as required.
After enabling local log feature, the SDK will write logs to user devices (mobile phone) in the form of file. When users are online, they can invoke the server API to get logs on user client for troubleshooting.
Local storage depends on the library react-native-fs, with steps as below:
- Install react-native-fs
npm install react-native-fs --save
- Plug in database to SDK with usePlugin as below:
javascriptconst RNFS = require('react-native-fs');
const params = {
rnfs: RNFS
};
params.rnfs.size = 1024 * 1024; // maximum log file size, unit: bytes; optional, 1M by default
SDK.usePlugin(params);
const nim = SDK.NIM.getInstance({
// .....
// initialize IM
});
Message push
From V5.3.0, message push is provided. When configuring a project, developers need to introduce related Android and APNs dependence.
-
APNs
- For APNs configuration, developers shall visit Apple website for applying for certificate with the push feature.
- After configuring a certificate, they shall add related features as per RN push configuration.
-
Android push
- Please refer to
./android/nimpush
and./nim/NIM_Android_Push.js
of RN-Demo. - For configurations, see Android push configuration.
- Please refer to
If push is not required parametersiosPushConfig
andandroidPushConfig
shall not be passed in.
Sample codes:
javascript // iOS/Android external push code
const iosPushConfig = {
tokenName: 'push_online',
};
const androidPushConfig = {
xmAppId: '2882303106219',
xmAppKey: '59717219',
xmCertificateName: 'RN_MI_PUSH',
hwCertificateName: 'RN_HW_PUSH',
mzAppId: '11398',
mzAppKey: 'b74148973e60a2af4c2f6779',
mzCertificateName: 'RN_MZ_PUSH',
fcmCertificateName: 'RN_FCM_PUSH',
vivoCertificateName: "vivopush",
oppoAppId: "xxx", // oppoAppId, oppoAppKey, oppoAppSercet are available by registering with oppo push platform
oppoAppKey: "xxx",
oppoAppSercet: "xxx",
oppoCertificateName: "oppopush"
};
var nim = SDK.NIM.getInstance({
// ...
iosPushConfig,
androidPushConfig,
// ...
})
// Android internal push example code, not remote push
import { showNotification } from '../nim/NIM_Android_Push';
showNotification({
icon: '', title: msg.from, content: showText, time: `${msg.time}`,
});
Send files
We do not recommend sending files with The APIsendFile
, but get file handle withpreviewFile
, add other file attributes to file object by other api methods, and finally send file with The APIsendFile
, because RN-SDK requires to get attributes of file message and sends them together with file message. An example of sending image files:
javascript nim.previewFile({
type: 'image',
filePath: options.filePath,
maxSize: maxSize,
commonUpload: true,
uploadprogress(obj) {
// ...
},
done: (error, file) => {
// Image attributes such as length, width,and size can be obtained using other API APIs
file.w = options.width;
file.h = options.height;
file.MD5 = options.MD5;
file.size = options.size;
const { scene, to } = options;
if (!error) {
constObj.nim.sendFile({
type: 'image',
scene,
to,
file,
done: (err, msg) => {
if (err) {
return;
}
this.appendMsg(msg);
},
});
}
},
});
- List of extra attached attributes required for message:
- Image object
- size: Size, unit: byte
- MD5: Value after transforming image file MD5
- w: Width, unit: px
- h: Height, unit: px
- Audio object
- size: Size, unit: byte
- MD5: Value after transforming audio file MD5
- dur: Length, unit: ms
- Video object
- size: Size, unit: byte
- MD5: Value after transforming video file MD5
- w: Width, unit: px
- h: Height, unit: px
- dur: Length, unit: ms
- File object
- size: Size, unit: byte
- MD5: Value after transforming file MD5
- Image object
Node.js
Node.js Overview
From v5.6.0, CommsEase WebSDK is designed to adapt node.js, so that IM app scene can be extended to server with Node.js environment. The node.js solution can be used to scenes of Server-as-a-Client and Client-as-a-Server, for example, linux industrial control, chatbot, data pipeline, standalone monitoring, scale data analysis.
The global variable is "window" for browser environment and "global" for node.js, so that they have different attributes. To implement compatibility and adaptability, SDK will mock some attributes (e.g. Navigator, location, WebSocket) to global, which will not influence ordinary application of users.
For information on related SDK files, contact CommsEase technical support.
Local database
Due to a variety of storage systems in server environment, the SDK will not integrate database, and users can use data storage services such as mysql, oracle, ms-sql, sqlite, mongodb, and hbase independently. When using node.js sdk, users can still enable server-api features of CommsEase to process server data to save time.
Send files
Please use the parameterfilePath
to upload Node.js.
javascript nim.previewFile({
type: 'image',
maxSize: maxSize,
commonUpload: true,
filePath: options.filePath,
uploadprogress(obj) {
// ...
},
done: (error, file) => {
const { scene, to } = options;
if (!error) {
constObj.nim.sendFile({
type: 'image',
scene,
to,
file,
done: (err, msg) => {
if (err) {
return;
}
this.appendMsg(msg);
},
});
}
},
});
Log record
The SDK supports to using the third-party log recording tool to help users record logs at server in the form of file log. Here is an example of third-party librarynpm
-log4js 3.*
for log recording.
- Initialization
log4js
:
javascript const log4js = require('log4js');
log4js.configure({
replaceConsole: true,
appenders: { nimlog: { type: 'file', filename: 'nim-debug.log' } },
categories: { default: { appenders: ['nimlog'], level: 'ALL' } }
});
const logger = log4js.getLogger('nimlog');
- Method of introducing log plug-in in IM and chat room:
javascript global.nim = NIM.getInstance({
debug: true,
logFunc: logger,
// ...
})
How can I introduce the SDK
How can I introduce script
The required SDK file is input to src with script tag.The SDK can be introduced by the attribute of window object hereinafter.
html<!-- Example -->
<script src="NIM_Web_SDK_vx.x.x.js"></script>
Introduce import/require
In browser framework and cross-platform environment, SDK can be introduced by import/require.
Notes: If developers select webpack/babel to pack, please use "exclude" to excluse SDK files to avoid error due to second packing of babel.
Example of SDK invocation in project:
javascript // Example
import SDK from 'NIM_Web_SDK_vx.x.x.js'
const nim = SDK.NIM.getInstance({
// ...
})
Related Webpack configurations:
javascript // Webpack reference configuration
module: {
rules: [
{
test: /\.js$/,
loader: 'babel-loader',
exclude: /NIM_Web_SDK_vx.x.x.js/,
query: {
presets: [
// ...
],
// ...
}
// ...
},
// ...
],
// ...
}
Instructions
Instance invocation mode
All services can be invoked by NIM SDK singleton, for example:
javascript // After introducing a reference to the SDK class, get the SDK instance
var nim = SDK.NIM.getInstance({
debug: true,
appKey: appKey,
account: account,
token: token,
// ...
});
Sending peer-to-peer messages is taken for an example:
javascript var msg = nim.sendText({
scene: 'p2p',
to: account,
text: 'hello',
done: function sendMsgDone (error, msg) {
// ...
}
});
Event notification mode
The SDK notifies API invoking results to upper-level developers by callback and "delegate". The two methods are triggered on the main thread only (To ensure browser compatibility, web worker is not used.)
- Generally, callback APIs are reflected in the parameter
done
of corresponding APIs and can be set when they are called. - In the "Delegate" mode, the developers need to handle the initialized asynchronous listener function at a proper time.
javascript // Delegate a notification example
var nim = NIM.getInstance({
// ... Other configurations are omitted
onmsg: function (msg) {
// Here is a delegate message event. After a message is sent successfully, the message is also processed here
}
});
// Callback notification event
var msg = nim.sendText({
scene: 'p2p',
to: account,
text: 'hello',
done: function sendMsgDone (error, msg) {
// Here is a callback message event that simply informs the developer whether The message is sent successfully.
}
});