5分钟集成 Web

概述

WuKongIM Web EasySDK 是一个轻量级的 JavaScript SDK，让您能够在 5 分钟内为 Web 应用添加实时聊天功能。本指南将带您快速完成从安装到发送第一条消息的全过程。

系统要求：支持现代浏览器（Chrome 60+、Firefox 55+、Safari 11+、Edge 79+）

步骤 1：安装 SDK

选择以下任一方式安装 EasyJSSDK：

npm
yarn
CDN

npm install easyjssdk

yarn add easyjssdk

<script src="https://unpkg.com/easyjssdk@latest/dist/easyjssdk.min.js"></script>

步骤 2：基本集成

2.1 导入 SDK

ES6 模块
CommonJS
CDN (全局变量)

import { WKIM, WKIMChannelType, WKIMEvent } from 'easyjssdk';

const { WKIM, WKIMChannelType, WKIMEvent } = require('easyjssdk');

// SDK 通过 CDN 加载后，可直接使用全局变量
const { WKIM, WKIMChannelType, WKIMEvent } = window.EasyJSSDK;

2.2 初始化 SDK

// 1. 初始化 SDK
const im = WKIM.init("ws://your-wukongim-server.com:5200", {
    uid: "your_user_id",        // 您的用户 ID
    token: "your_auth_token"    // 您的认证 Token
    // deviceId: "optional_device_id", // 可选：设备 ID
    // deviceFlag: 2 // 可选：设备标识 (1:APP, 2:WEB, 默认为 2)
});

2.3 监听消息

// 2. 监听各种事件
im.on(WKIMEvent.Connect, (result) => {
    console.log("Event: Connected!", result);
    // 连接成功，可以开始发送消息
    updateUI(true);
});

im.on(WKIMEvent.Disconnect, (disconnectInfo) => {
    console.log("Event: Disconnected.", disconnectInfo);
    console.log("Disconnect code:", disconnectInfo.code, "reason:", disconnectInfo.reason);
    // 连接断开，更新UI状态
    updateUI(false);
});

im.on(WKIMEvent.Message, (message) => {
    console.log("Event: Message Received", message);
    // 处理接收到的消息
    displayMessage(message);
});

im.on(WKIMEvent.Error, (error) => {
    console.log("Event: Error Occurred", error.message || error);
    // 处理错误，可能需要更新UI或重连
});

// 可以为同一事件添加多个监听器
im.on(WKIMEvent.Message, (message) => {
    console.log("Second listener also received message:", message.messageId);
    // 在这里可以添加不同的处理逻辑
});

2.4 移除事件监听器

在某些情况下，您可能需要移除事件监听器以避免内存泄漏或重复处理。EasyJSSDK 提供了 off 方法来移除事件监听器。

重要提醒：off 方法的 eventName 和 callback 参数都是必需的。callback 引用必须与使用 on() 添加监听器时的引用完全相同。

语法

im.off(eventName, callback)

参数说明：

eventName (Event): 要移除监听器的事件名称（必需）
callback (EventHandler): 要移除的具体回调函数（必需）

正确的使用方式

// ✅ 正确：使用具名函数
function handleMessage(message) {
    console.log('处理消息:', message);
}

function handleConnect(result) {
    console.log('连接成功:', result);
}

function handleError(error) {
    console.log('发生错误:', error);
}

// 添加事件监听器
im.on(WKIMEvent.Message, handleMessage);
im.on(WKIMEvent.Connect, handleConnect);
im.on(WKIMEvent.Error, handleError);

// 移除特定的事件监听器 - 使用相同的函数引用
im.off(WKIMEvent.Message, handleMessage);
im.off(WKIMEvent.Connect, handleConnect);
im.off(WKIMEvent.Error, handleError);

错误的使用方式

// ❌ 错误：使用匿名函数无法正确移除
im.on(WKIMEvent.Message, (message) => {
    console.log('处理消息:', message);
});

// 这样无法移除上面的监听器，因为函数引用不同
im.off(WKIMEvent.Message, (message) => {
    console.log('处理消息:', message);
});

实际应用示例

class ChatManager {
    constructor() {
        // 绑定方法到实例，确保 this 上下文正确
        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() {
        // 初始化 SDK
        this.im = WKIM.init("ws://your-server.com:5200", {
            uid: "user123",
            token: "user-token"
        });

        // 添加事件监听器
        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) {
            // 移除事件监听器 - 使用相同的方法引用
            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);
    }

    handleConnect(result) {
        console.log('连接成功:', result);
    }

    handleDisconnect(disconnectInfo) {
        console.log('连接断开:', disconnectInfo);
        console.log('断开代码:', disconnectInfo.code, '原因:', disconnectInfo.reason);
    }

    handleError(error) {
        console.log('发生错误:', error);
    }
}

// 使用示例
const chatManager = new ChatManager();
chatManager.init();

// 页面卸载时清理
window.addEventListener('beforeunload', () => {
    chatManager.destroy();
});

框架集成最佳实践

React 示例：

import React, { useEffect, useRef } from 'react';
import { WKIM, WKIMEvent } from 'easyjssdk';

function ChatComponent() {
    const imRef = useRef(null);

    useEffect(() => {
        // 定义事件处理函数
        const handleMessage = (message) => {
            console.log('收到消息:', message);
        };

        const handleConnect = (result) => {
            console.log('连接成功:', result);
        };

        // 初始化 SDK
        const im = WKIM.init("ws://your-server.com:5200", {
            uid: "user123",
            token: "user-token"
        });
        imRef.current = im;

        // 添加事件监听器
        im.on(WKIMEvent.Message, handleMessage);
        im.on(WKIMEvent.Connect, handleConnect);

        // 清理函数：组件卸载时移除监听器
        return () => {
            if (imRef.current) {
                imRef.current.off(WKIMEvent.Message, handleMessage);
                imRef.current.off(WKIMEvent.Connect, handleConnect);
            }
        };
    }, []);

    return <div>聊天组件</div>;
}

Vue 示例：

export default {
    data() {
        return {
            im: null
        };
    },

    mounted() {
        // 定义事件处理函数
        this.handleMessage = (message) => {
            console.log('收到消息:', message);
        };

        this.handleConnect = (result) => {
            console.log('连接成功:', result);
        };

        // 初始化 SDK
        this.im = WKIM.init("ws://your-server.com:5200", {
            uid: "user123",
            token: "user-token"
        });

        // 添加事件监听器
        this.im.on(WKIMEvent.Message, this.handleMessage);
        this.im.on(WKIMEvent.Connect, this.handleConnect);
    },

    beforeUnmount() {
        // 组件销毁前移除监听器
        if (this.im) {
            this.im.off(WKIMEvent.Message, this.handleMessage);
            this.im.off(WKIMEvent.Connect, this.handleConnect);
        }
    }
};

参考源码实现：您可以查看 EasyJSSDK 源码了解 off 方法的具体实现细节。

2.5 连接服务器

// 4. 连接到服务器
try {
    await im.connect();
    console.log("连接成功！");
} catch (error) {
    console.error("连接失败:", error);
}

2.6 发送消息

// 5. 发送消息示例
async function sendMessage() {
    const targetChannelID = "friend_user_id"; // 目标用户 ID
    const messagePayload = { 
        type: 1, 
        content: "Hello from EasyJSSDK!" 
    }; // 您的自定义消息载荷
    
    try {
        const result = await im.send(targetChannelID, WKIMChannelType.Person, messagePayload);
        console.log("消息发送成功:", result);
    } catch (error) {
        console.error("消息发送失败:", error);
    }
}

完整示例代码

查看完整的示例代码和更多功能演示

协议完整文档

查看 WuKongIM 的完整协议文档

GitHub 仓库

访问 EasyJSSDK 的 GitHub 仓库

问题反馈

报告问题或提出建议

WuKongEasySDK

WuKongIMSDK

5分钟集成 Web

概述

步骤 1：安装 SDK

步骤 2：基本集成

2.1 导入 SDK

2.2 初始化 SDK

2.3 监听消息

2.4 移除事件监听器

语法

正确的使用方式

错误的使用方式

实际应用示例

框架集成最佳实践

2.5 连接服务器

2.6 发送消息

相关资源

完整示例代码

协议完整文档

GitHub 仓库

问题反馈

​概述

​步骤 1：安装 SDK

​步骤 2：基本集成

​2.1 导入 SDK

​2.2 初始化 SDK

​2.3 监听消息

​2.4 移除事件监听器

​语法

​正确的使用方式

​错误的使用方式

​实际应用示例

​框架集成最佳实践

​2.5 连接服务器

​2.6 发送消息

​相关资源

完整示例代码

协议完整文档

GitHub 仓库

问题反馈

概述

步骤 1：安装 SDK

步骤 2：基本集成

2.1 导入 SDK

2.2 初始化 SDK

2.3 监听消息

2.4 移除事件监听器

语法

正确的使用方式

错误的使用方式

实际应用示例

框架集成最佳实践

2.5 连接服务器

2.6 发送消息

相关资源