Overview
WuKongIM Web EasySDK is a lightweight JavaScript SDK that enables you to add real-time chat functionality to your web application in just 5 minutes. This guide will take you through the complete process from installation to sending your first message.
System Requirements: Supports modern browsers (Chrome 60+, Firefox 55+, Safari 11+, Edge 79+)
Step 1: Install SDK
Choose any of the following methods to install EasyJSSDK:
Step 2: Basic Integration
2.1 Import SDK
ES6 Modules
CommonJS
CDN (Global Variables)
import { WKIM, WKIMChannelType, WKIMEvent } from 'easyjssdk';
2.2 Initialize SDK
// 1. Initialize SDK
const im = WKIM.init("ws://your-wukongim-server.com:5200", {
uid: "your_user_id", // Your user ID
token: "your_auth_token" // Your authentication token
// deviceId: "optional_device_id", // Optional: Device ID
// deviceFlag: 2 // Optional: Device flag (1:APP, 2:WEB, default is 2)
});
2.3 Listen for Messages
// 2. Listen for various events
im.on(WKIMEvent.Connect, (result) => {
console.log("Event: Connected!", result);
// Connection successful, can start sending messages
updateUI(true);
});
im.on(WKIMEvent.Disconnect, (disconnectInfo) => {
console.log("Event: Disconnected.", disconnectInfo);
console.log("Disconnect code:", disconnectInfo.code, "reason:", disconnectInfo.reason);
// Connection lost, update UI status
updateUI(false);
});
im.on(WKIMEvent.Message, (message) => {
console.log("Event: Message Received", message);
// Handle received messages
displayMessage(message);
});
im.on(WKIMEvent.Error, (error) => {
console.log("Event: Error Occurred", error.message || error);
// Handle errors, may need to update UI or reconnect
});
// You can add multiple listeners for the same event
im.on(WKIMEvent.Message, (message) => {
console.log("Second listener also received message:", message.messageId);
// Add different processing logic here
});
2.4 Remove Event Listeners
In some cases, you may need to remove event listeners to avoid memory leaks or duplicate processing. EasyJSSDK provides the off method to remove event listeners.
Important Reminder: Both eventName and callback parameters are required for the off method. The callback reference must be exactly the same as the one used when adding the listener with on().
Syntax
im.off(eventName, callback)
eventName (Event): The event name to remove the listener for (required)callback (EventHandler): The specific callback function to remove (required)
Correct Usage
// ✅ Correct: Use named functions
function handleMessage(message) {
console.log('Handle message:', message);
}
function handleConnect(result) {
console.log('Connection successful:', result);
}
function handleError(error) {
console.log('Error occurred:', error);
}
// Add event listeners
im.on(WKIMEvent.Message, handleMessage);
im.on(WKIMEvent.Connect, handleConnect);
im.on(WKIMEvent.Error, handleError);
// Remove specific event listeners - use the same function reference
im.off(WKIMEvent.Message, handleMessage);
im.off(WKIMEvent.Connect, handleConnect);
im.off(WKIMEvent.Error, handleError);
Incorrect Usage
// ❌ Incorrect: Using anonymous functions cannot be properly removed
im.on(WKIMEvent.Message, (message) => {
console.log('Handle message:', message);
});
// This cannot remove the above listener because the function reference is different
im.off(WKIMEvent.Message, (message) => {
console.log('Handle message:', message);
});
Practical Application Example
class ChatManager {
constructor() {
// Bind methods to instance to ensure correct 'this' context
this.handleMessage = this.handleMessage.bind(this);
this.handleConnect = this.handleConnect.bind(this);
this.handleDisconnect = this.handleDisconnect.bind(this);
this.handleError = this.handleError.bind(this);
}
init() {
// Initialize SDK
this.im = WKIM.init("ws://your-server.com:5200", {
uid: "user123",
token: "user-token"
});
// Add event listeners
this.im.on(WKIMEvent.Message, this.handleMessage);
this.im.on(WKIMEvent.Connect, this.handleConnect);
this.im.on(WKIMEvent.Disconnect, this.handleDisconnect);
this.im.on(WKIMEvent.Error, this.handleError);
}
destroy() {
if (this.im) {
// Remove event listeners - use the same method references
this.im.off(WKIMEvent.Message, this.handleMessage);
this.im.off(WKIMEvent.Connect, this.handleConnect);
this.im.off(WKIMEvent.Disconnect, this.handleDisconnect);
this.im.off(WKIMEvent.Error, this.handleError);
this.im = null;
}
}
handleMessage(message) {
console.log('Message received:', message);
}
handleConnect(result) {
console.log('Connection successful:', result);
}
handleDisconnect(disconnectInfo) {
console.log('Connection lost:', disconnectInfo);
console.log('Disconnect code:', disconnectInfo.code, 'reason:', disconnectInfo.reason);
}
handleError(error) {
console.log('Error occurred:', error);
}
}
// Usage example
const chatManager = new ChatManager();
chatManager.init();
// Cleanup when page unloads
window.addEventListener('beforeunload', () => {
chatManager.destroy();
});
Framework Integration Best Practices
React Example:
import React, { useEffect, useRef } from 'react';
import { WKIM, WKIMEvent } from 'easyjssdk';
function ChatComponent() {
const imRef = useRef(null);
useEffect(() => {
// Define event handler functions
const handleMessage = (message) => {
console.log('Message received:', message);
};
const handleConnect = (result) => {
console.log('Connection successful:', result);
};
// Initialize SDK
const im = WKIM.init("ws://your-server.com:5200", {
uid: "user123",
token: "user-token"
});
imRef.current = im;
// Add event listeners
im.on(WKIMEvent.Message, handleMessage);
im.on(WKIMEvent.Connect, handleConnect);
// Cleanup function: remove listeners when component unmounts
return () => {
if (imRef.current) {
imRef.current.off(WKIMEvent.Message, handleMessage);
imRef.current.off(WKIMEvent.Connect, handleConnect);
}
};
}, []);
return <div>Chat Component</div>;
}
export default {
data() {
return {
im: null
};
},
mounted() {
// Define event handler functions
this.handleMessage = (message) => {
console.log('Message received:', message);
};
this.handleConnect = (result) => {
console.log('Connection successful:', result);
};
// Initialize SDK
this.im = WKIM.init("ws://your-server.com:5200", {
uid: "user123",
token: "user-token"
});
// Add event listeners
this.im.on(WKIMEvent.Message, this.handleMessage);
this.im.on(WKIMEvent.Connect, this.handleConnect);
},
beforeUnmount() {
// Remove listeners before component destruction
if (this.im) {
this.im.off(WKIMEvent.Message, this.handleMessage);
this.im.off(WKIMEvent.Connect, this.handleConnect);
}
}
};
Source Code Reference: You can check the EasyJSSDK source code to understand the specific implementation details of the off method. 2.5 Connect to Server
// 4. Connect to server
try {
await im.connect();
console.log("Connection successful!");
} catch (error) {
console.error("Connection failed:", error);
}
2.6 Send Messages
// 5. Send message example
async function sendMessage() {
const targetChannelID = "friend_user_id"; // Target user ID
const messagePayload = {
type: 1,
content: "Hello from EasyJSSDK!"
}; // Your custom message payload
try {
const result = await im.send(targetChannelID, WKIMChannelType.Person, messagePayload);
console.log("Message sent successfully:", result);
} catch (error) {
console.error("Message sending failed:", error);
}
}
