EasyJSSDK

https://github.com/wukongim/wukongeasysdk-js
Admin
A simple and easy-to-use communication SDK for WuKongIM, supporting WebSocket-based message sending...
Tokens:13,839
Snippets:163
Trust Score:6.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Start a Local Server

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/README.md

Install and start a local HTTP server to serve the example files. Ensure you have http-server installed globally.

```bash
# npm install -g http-server
http-server .
```

--------------------------------

### Complete Integration Example

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_FLOW.md

This snippet demonstrates the complete integration of the Wukong IM SDK, including initialization, event handler setup, registration, error handling, and connection. It shows how to set up listeners for custom events and errors, and how the SDK automatically processes incoming events.

```javascript
// 1. Initialize SDK
const wkim = WKIM.init('ws://localhost:5100', {
    uid: 'user123',
    token: 'auth-token'
});

// 2. Setup event handlers
const eventHandlers = {
    'user.status.changed': (data) => {
        updateUserStatus(data.userId, data.status);
    },
    'channel.updated': (data) => {
        refreshChannel(data.channelId);
    },
    'system.announcement': (data) => {
        showNotification(data.message);
    }
};

// 3. Register event listener
wkim.on(WKIM.Event.CustomEvent, (event) => {
    const handler = eventHandlers[event.type];
    if (handler) {
        try {
            handler(event.data);
        } catch (error) {
            console.error('Error handling event:', error);
        }
    }
});

// 4. Register error handler
wkim.on(WKIM.Event.Error, (error) => {
    console.error('SDK Error:', error);
});

// 5. Connect
await wkim.connect();

// Now the SDK will automatically:
// - Receive event notifications from server
// - Parse and validate them
// - Emit CustomEvent with parsed data
// - Your handlers will process the events
```

--------------------------------

### Complete Event Handling Example

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

Demonstrates initializing the SDK with a device flag, registering a map of event handlers for various event types, and setting up listeners for connection and error events.

```javascript
// Initialize
const wkim = WKIM.init('ws://localhost:5100', {
    uid: 'user123',
    token: 'your-token',
    deviceFlag: 2 // WEB
});

// Event handler map
const eventHandlers = {
    'user.status.changed': (data) => {
        console.log('User status:', data);
        updateUserStatus(data.userId, data.status);
    },
    
    'channel.updated': (data) => {
        console.log('Channel updated:', data);
        refreshChannel(data.channelId);
    },
    
    'system.announcement': (data) => {
        console.log('Announcement:', data);
        showNotification(data.message, data.severity);
    },
    
    'notification.received': (data) => {
        console.log('Notification:', data);
        if (Notification.permission === 'granted') {
            new Notification(data.title, { body: data.body });
        }
    }
};

// Register event listener
wkim.on(WKIM.Event.CustomEvent, (event) => {
    console.log('Event received:', event.type);
    
    const handler = eventHandlers[event.type];
    if (handler) {
        try {
            handler(event.data);
        } catch (error) {
            console.error('Error handling event:', error);
        }
    } else {
        console.log('Unhandled event type:', event.type);
    }
});

// Other event listeners
wkim.on(WKIM.Event.Connect, () => {
    console.log('Connected to server');
});

wkim.on(WKIM.Event.Disconnect, () => {
    console.log('Disconnected from server');
});

wkim.on(WKIM.Event.Error, (error) => {
    console.error('SDK Error:', error);
});

// Connect
wkim.connect()
    .then(() => console.log('Ready to receive events'))
    .catch((error) => console.error('Connection failed:', error));
```

--------------------------------

### Listen for Custom Events

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/IMPLEMENTATION_SUMMARY.md

Set up a listener for custom events from the SDK. This example shows how to log any received custom event.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    console.log('Event received:', event);
});
```

--------------------------------

### Install EasyJSSDK

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/README.md

Install the EasyJSSDK package using npm. This command is used for both general installation and within WeChat Mini Program projects.

```bash
npm install easyjssdk
```

--------------------------------

### SDK Error Event Handling

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/IMPLEMENTATION_SUMMARY.md

Provides an example of how to listen for general SDK errors and specifically identify and handle errors related to event notifications.

```javascript
wkim.on(WKIM.Event.Error, (error) => {
    if (error.message.includes('event notification')) {
        console.error('Invalid event received:', error);
    }
});
```

--------------------------------

### Listen for Custom Events

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/README.md

Implement event listeners for custom events received from the server. This example shows how to log event details and handle different event types using a switch statement.

```javascript
// Listen for custom events
im.on(WKIMEvent.CustomEvent, (event) => {
    console.log('Event Type:', event.type);
    console.log('Event Data:', event.data);

    // Handle different event types
    switch (event.type) {
        case 'user.status.changed':
            updateUserStatus(event.data);
            break;
        case 'system.announcement':
            showAnnouncement(event.data);
            break;
    }
});
```

--------------------------------

### Import SDK in WeChat Mini Program

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/README.md

Import necessary components from the EasyJSSDK in a WeChat Mini Program environment after installation and building the npm package.

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

--------------------------------

### Example of Good Event Data Structure

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

Illustrates an event data structure that includes all necessary information for client-side handling, avoiding additional API requests.

```javascript
// ✅ Good: Includes all necessary information
{
    type: "user.status.changed",
    data: {
        userId: "user123",
        status: "online",
        lastSeen: 1704067200000,
        deviceType: "mobile"
    }
}
```

--------------------------------

### Automatic JSON Parsing Example

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/IMPLEMENTATION_SUMMARY.md

Illustrates the SDK's capability to automatically parse JSON string payloads received in the 'data' field of event notifications into JavaScript objects.

```javascript
// Server sends: data: "{\"userId\":\"123\",\"status\":\"online\"}"
// SDK automatically parses to: data: { userId: "123", status: "online" }
```

--------------------------------

### Initialize SDK and Listen for Custom Events (TypeScript)

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

Demonstrates initializing the SDK with TypeScript and setting up a listener for custom events, logging event details.

```typescript
import { WKIM, Event, EventNotification } from 'easyjssdk';

const wkim = WKIM.init('ws://localhost:5100', {
    uid: 'user123',
    token: 'token'
});

wkim.on(Event.CustomEvent, (event: EventNotification) => {
    console.log(event.id);        // string
    console.log(event.type);      // string
    console.log(event.timestamp); // number
    console.log(event.data);      // any
});
```

--------------------------------

### Initialize SDK and Listen for Custom Events

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_IMPLEMENTATION.md

Initialize the SDK with connection details and set up a listener for custom events. Handles different event types using a switch statement.

```javascript
// Initialize SDK
const wkim = WKIM.init('ws://localhost:5100', {
    uid: 'user123',
    token: 'auth-token'
});

// Listen for custom events
wkim.on(WKIM.Event.CustomEvent, (event) => {
    console.log('Event ID:', event.id);
    console.log('Event Type:', event.type);
    console.log('Event Timestamp:', event.timestamp);
    console.log('Event Data:', event.data);
    
    // Handle specific event types
    switch (event.type) {
        case 'user.status.changed':
            handleUserStatusChanged(event.data);
            break;
        case 'system.announcement':
            handleSystemAnnouncement(event.data);
            break;
    }
});

// Connect
await wkim.connect();
```

--------------------------------

### Initialize SDK and Listen for Custom Events

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

Initializes the WuKongIM SDK and sets up a listener for all custom events. Ensure you have the correct server address and authentication token.

```javascript
// Initialize SDK
const wkim = WKIM.init('ws://localhost:5100', {
    uid: 'user123',
    token: 'your-auth-token'
});

// Listen for custom events
wkim.on(WKIM.Event.CustomEvent, (event) => {
    console.log('Event received:', event);
    // event = {
    //   id: "event-uuid",
    //   type: "user.status.changed",
    //   timestamp: 1704067200000,
    //   data: { userId: "user456", status: "online" }
    // }
});

// Connect to server
await wkim.connect();
```

--------------------------------

### Initialize SDK

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/IMPLEMENTATION_SUMMARY.md

Initialize the WuKongIM SDK with the server address and user credentials. Ensure the server address and token are correctly provided.

```javascript
const wkim = WKIM.init('ws://your-server:5100', {
    uid: 'user123',
    token: 'your-token'
});
```

--------------------------------

### SDK Initialization and Event Listening

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/IMPLEMENTATION_SUMMARY.md

Demonstrates how to initialize the SDK, listen for custom events using WKIM.Event.CustomEvent, and handle different event types with their associated data. Requires prior SDK initialization and connection.

```javascript
// Initialize SDK
const wkim = WKIM.init('ws://localhost:5100', {
    uid: 'user123',
    token: 'auth-token'
});

// Listen for custom events
wkim.on(WKIM.Event.CustomEvent, (event) => {
    console.log('Event Type:', event.type);
    console.log('Event Data:', event.data);
    
    // Handle different event types
    switch (event.type) {
        case 'user.status.changed':
            updateUserStatus(event.data);
            break;
        case 'system.announcement':
            showAnnouncement(event.data);
            break;
    }
});

// Connect
await wkim.connect();
```

--------------------------------

### Initialize and Use EasyJSSDK

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/README.md

Initialize the SDK with server details and authentication credentials. This snippet also shows how to set up message and custom event listeners, connect to the server, and send a message.

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

// 1. Initialization
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. Receive messages
im.on(WKIMEvent.Message, (message) => {
    console.log("Received message:", message);
    // Process received message (message.payload, message.fromUid, etc.)
});

// 2.1 Receive custom event notifications
im.on(WKIMEvent.CustomEvent, (event) => {
    console.log("Received event:", event);
    // Handle custom events from server
    // event = { id, type, timestamp, data }
});

// For more events, see:
// https://github.com/WuKongIM/EasyJSSDK/blob/main/example/app.js#L132

// 3. Connect to the server
await im.connect()

// 4. Example: Send a message after successful connection
const targetChannelID = "friend_user_id"; // Target user ID
const messagePayload = { type: 1, content: "Hello from EasyJSSDK!" };
const sendResult = await im.send(targetChannelID, WKIMChannelType.Person, messagePayload);
// sendResult.reasonCode
```

--------------------------------

### SPA Application Connection Initialization and Cleanup

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/CONNECTION_MANAGEMENT.md

Initialize the SDK at application startup and connect when appropriate. Ensure the instance is destroyed when the application is about to be unloaded.

```javascript
// 在应用启动时初始化
const im = WKIM.init('ws://localhost:5100', {
    uid: getCurrentUserId(),
    token: getAuthToken()
});

// 在合适的时机连接
await im.connect();

// 在应用销毁时清理
window.addEventListener('beforeunload', () => {
    im.destroy();
});
```

--------------------------------

### Initialize SDK and UI Elements

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/example/event-test.html

Initializes the Wukongim SDK and references UI elements for status updates, buttons, and event/log displays. Ensure corresponding HTML elements exist.

```javascript
let wkim = null;
let stats = { total: 0, user: 0, channel: 0, system: 0 };

const statusEl = document.getElementById('status');
const connectBtn = document.getElementById('connectBtn');
const disconnectBtn = document.getElementById('disconnectBtn');
const clearEventsBtn = document.getElementById('clearEventsBtn');
const clearLogsBtn = document.getElementById('clearLogsBtn');
const eventList = document.getElementById('eventList');
const logList = document.getElementById('logList');
const simulateUserEventBtn = document.getElementById('simulateUserEvent');
const simulateSystemEventBtn = document.getElementById('simulateSystemEvent');
```

--------------------------------

### Connect to Server

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/IMPLEMENTATION_SUMMARY.md

Establish a connection to the WuKongIM server. This is an asynchronous operation and should be awaited.

```javascript
await wkim.connect();
```

--------------------------------

### Package.json Module Format Configuration

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/README.md

Excerpt from package.json demonstrating how the 'main', 'module', 'types', and 'miniprogram' fields are configured to specify entry points for different module formats and environments.

```json
// package.json (excerpt)
{
  "main": "dist/cjs/index.js",       // CJS entry
  "module": "dist/esm/index.js",     // ESM entry
  "types": "dist/esm/index.d.ts",    // TypeScript types
  "miniprogram": "dist/cjs"          // WeChat Mini Program entry
}
```

--------------------------------

### Initial Log Message

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/example/event-test.html

Displays an initial log message indicating that the application is ready to connect.

```javascript
// Initial log
addLog('Ready to connect', 'info');
```

--------------------------------

### Initialize SDK with Auto-Generated Device ID

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/CONNECTION_MANAGEMENT.md

Initialize the SDK with authentication options. A unique deviceId will be automatically generated for each instance, helping to distinguish connections.

```javascript
const im = WKIM.init('ws://localhost:5100', {
    uid: 'user123',
    token: 'your-token'
    // deviceId 将自动生成：web_12345678_1703123456789
});
```

--------------------------------

### Connect to Wukongim Server

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/example/event-test.html

Handles the connection process to the Wukongim server using provided credentials and sets up event listeners for connection status, errors, and custom events. It also updates the UI accordingly.

```javascript
connectBtn.addEventListener('click', () => {
  updateStatus('connecting', 'Connecting...');
  addLog('Initializing SDK...', 'info');
  wkim = WKIM.init('ws://localhost:5100', {
    uid: 'test-user-' + Date.now(),
    token: 'test-token',
    deviceFlag: 2
  });

  wkim.on(WKIM.Event.Connect, (result) => {
    updateStatus('connected', 'Connected');
    addLog('Connected to server', 'success');
    connectBtn.disabled = true;
    disconnectBtn.disabled = false;
  });

  wkim.on(WKIM.Event.Disconnect, (info) => {
    updateStatus('disconnected', 'Disconnected');
    addLog('Disconnected from server', 'warning');
    connectBtn.disabled = false;
    disconnectBtn.disabled = true;
  });

  wkim.on(WKIM.Event.Error, (error) => {
    addLog(`Error: ${error.message}`, 'error');
  });

  wkim.on(WKIM.Event.CustomEvent, (event) => {
    addLog(`Event received: ${event.type}`, 'success');
    addEvent(event);
  });

  wkim.connect().catch((error) => {
    updateStatus('disconnected', 'Connection Failed');
    addLog(`Connection failed: ${error.message}`, 'error');
  });
});
```

--------------------------------

### Manual Connection Lifecycle Management

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/CONNECTION_MANAGEMENT.md

Manually manage the connection lifecycle by connecting, disconnecting, and destroying the SDK instance as needed.

```javascript
const im = WKIM.init('ws://localhost:5100', authOptions);

// 连接
await im.connect();

// 业务逻辑...

// 断开连接（保留实例）
im.disconnect();

// 完全销毁实例（推荐在页面卸载前调用）
im.destroy();
```

--------------------------------

### Simulate System Event

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/example/event-test.html

Generates and adds a mock 'system.announcement' event to the event list for testing. This simulates receiving system-level notifications.

```javascript
simulateSystemEventBtn.addEventListener('click', () => {
  const mockEvent = {
    id: 'mock-' + Date.now(),
    type: 'system.announcement',
    timestamp: Date.now(),
    data: {
      message: 'This is a test system announcement',
      severity: 'info',
      expiresAt: Date.now() + 3600000
    }
  };
  addLog('Simulated system event', 'info');
  addEvent(mockEvent);
});
```

--------------------------------

### Simulate Receiving an Event for Testing

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

This code snippet demonstrates how to manually create and log a mock event object. This is useful for testing your event handling logic without a live server connection.

```javascript
// Simulate receiving an event (for testing)
const mockEvent = {
    id: 'test-event-123',
    type: 'user.status.changed',
    timestamp: Date.now(),
    data: {
        userId: 'user456',
        status: 'online',
        lastSeen: Date.now()
    }
};

// Your event handler will process this
console.log('Mock event:', mockEvent);
```

--------------------------------

### Handle System Announcement Events

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

This snippet filters for 'system.announcement' events and displays a notification. It assumes the SDK has already been initialized and connected.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    if (event.type === 'system.announcement') {
        const { message, severity } = event.data;
        showNotification(message, severity);
    }
});
```

--------------------------------

### Handle Custom Events with Wukongim SDK

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_FLOW.md

Use `wkim.on` to subscribe to custom events. The callback function receives an event object that can be inspected for routing logic.

```javascript
wkim.on(Event.CustomEvent, (event) => { ... })
```

--------------------------------

### Singleton Pattern for Connection Management

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/CONNECTION_MANAGEMENT.md

Use the singleton pattern to ensure only one active connection exists. Subsequent initializations will automatically destroy the previous instance unless singleton mode is explicitly disabled.

```javascript
// 启用单例模式（默认）
const im1 = WKIM.init('ws://localhost:5100', authOptions);

// 第二次初始化会自动销毁第一个实例
const im2 = WKIM.init('ws://localhost:5100', authOptions);

// 禁用单例模式
const im3 = WKIM.init('ws://localhost:5100', authOptions, { singleton: false });
```

--------------------------------

### Development Build Command

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/README.md

Command to build the project, compiling TypeScript into both ESM and CJS formats. This is part of the development workflow.

```bash
npm run build
```

--------------------------------

### Client-side Event Handling

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_FLOW.md

Illustrates the client-side logic within the EasyJSSDK for handling incoming WebSocket messages, specifically focusing on event notifications.

```javascript
WebSocket.onmessage
handleMessage(data)
- Parse JSON
- Identify message type
handleNotification(notification)
- Check method === "event"
handleEventNotification(params)
1. Extract fields (id, type, timestamp, data)
2. Validate required fields
3. Parse JSON data if string
4. Create EventNotification object
emit(Event.CustomEvent, eventData)
Registered Event Listeners
wkim.on(Event.CustomEvent, callback)
```

--------------------------------

### Global Instance Management for Preventing Leaks

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/CONNECTION_MANAGEMENT.md

Manages a global instance of the SDK to prevent memory and connection leaks. If a global instance exists, it is destroyed before a new one is created.

```javascript
// 防止内存泄漏和连接泄漏
if (WKIM.globalInstance) {
    WKIM.globalInstance.destroy(); // 销毁旧实例
}
WKIM.globalInstance = newInstance; // 设置新实例
```

--------------------------------

### Simulate User Event

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/example/event-test.html

Generates and adds a mock 'user.status.changed' event to the event list for testing purposes. This bypasses actual server communication.

```javascript
simulateUserEventBtn.addEventListener('click', () => {
  const mockEvent = {
    id: 'mock-' + Date.now(),
    type: 'user.status.changed',
    timestamp: Date.now(),
    data: {
      userId: 'user123',
      status: 'online',
      lastSeen: Date.now()
    }
  };
  addLog('Simulated user event', 'info');
  addEvent(mockEvent);
});
```

--------------------------------

### Check Connection Status

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

Verify the current connection status of the Wukong IM SDK.

```javascript
console.log('Connected:', wkim.isConnected);
```

--------------------------------

### Handle SDK Error Events

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

Subscribe to WKIM.Event.Error to log SDK errors and implement specific handling for event-related processing failures.

```javascript
wkim.on(WKIM.Event.Error, (error) => {
    console.error('SDK Error:', error);
    
    // Check if it's an event-related error
    if (error.message.includes('event notification')) {
        // Handle event processing errors
        notifyUser('Failed to process server event');
    }
});
```

--------------------------------

### Handle Channel Update Events

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

This snippet filters for 'channel.updated' events and logs details about the channel update. It assumes the SDK has already been initialized and connected.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    if (event.type === 'channel.updated') {
        const { channelId, updateType, newValue } = event.data;
        console.log(`Channel ${channelId} ${updateType} updated to ${newValue}`);
    }
});
```

--------------------------------

### Listening for Custom Events in JavaScript

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

Register a listener for the `WKIM.Event.CustomEvent` to receive all custom event notifications. The handler processes the event data and dispatches to type-specific handlers.

```javascript
wkim.on(WKIM.Event.CustomEvent, (eventNotification) => {
    console.log('Event received:', eventNotification);
    
    const { id, type, timestamp, data, header } = eventNotification;
    
    // Handle the event based on type
    switch (type) {
        case 'user.status.changed':
            handleUserStatusChanged(data);
            break;
        case 'system.announcement':
            handleSystemAnnouncement(data);
            break;
        // ... more handlers
    }
});
```

--------------------------------

### React Hook for WKIM Connection Management

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/CONNECTION_MANAGEMENT.md

A custom React hook to manage the WKIM connection lifecycle within a React component. It initializes the connection on mount and cleans it up on unmount.

```javascript
import { useEffect, useRef } from 'react';
import { WKIM } from 'easyjssdk';

function useWKIM(uid, token) {
    const imRef = useRef(null);
    
    useEffect(() => {
        // 初始化连接
        imRef.current = WKIM.init('ws://localhost:5100', { uid, token });
        imRef.current.connect();
        
        // 清理函数
        return () => {
            if (imRef.current) {
                imRef.current.destroy();
            }
        };
    }, [uid, token]);
    
    return imRef.current;
}
```

--------------------------------

### Handle Channel Updates

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

Respond to 'channel.updated' events by fetching and updating channel information in the UI. Ensure the client-side can handle channel data updates.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    if (event.type === 'channel.updated') {
        const { channelId, channelType, updateType, newValue } = event.data;
        
        // Fetch updated channel information
        fetch(`/api/channels/${channelId}`)
            .then(response => response.json())
            .then(channelData => {
                updateChannelInUI(channelData);
            });
    }
});
```

--------------------------------

### Handle Unknown Event Types Gracefully

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

Implement a fallback mechanism to log unhandled event types instead of throwing errors, ensuring application stability.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    const handler = eventHandlers[event.type];
    
    if (handler) {
        handler(event.data);
    } else {
        console.log(`Unhandled event type: ${event.type}`);
        // Don't throw errors for unknown event types
    }
});
```

--------------------------------

### Handle Events with Try-Catch

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

Use try-catch blocks to gracefully handle potential errors during event processing, preventing application crashes.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    try {
        handleEvent(event);
    } catch (error) {
        console.error('Error handling event:', error);
    }
});
```

--------------------------------

### Page Unload Event Handling for Cleanup

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/CONNECTION_MANAGEMENT.md

The SDK listens to 'beforeunload' and 'pagehide' events to ensure the WebSocket connection is properly closed using standard WebSocket close codes.

```javascript
// 监听多个事件确保连接被正确关闭
// 使用标准的 WebSocket 关闭代码
window.addEventListener('beforeunload', cleanupHandler);
window.addEventListener('pagehide', cleanupHandler);

// 关闭代码说明：
// 1000: 正常关闭
// 3000-4999: 自定义关闭代码（用于异常情况）
```

--------------------------------

### Automatic Connection Cleanup on Page Unload

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/CONNECTION_MANAGEMENT.md

The SDK automatically handles connection cleanup when the page is unloaded or refreshed. No explicit code is required in your application for this.

```javascript
window.addEventListener('beforeunload', () => {
    // SDK 内部会自动处理
});
```

--------------------------------

### Event Handler Callback

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_FLOW.md

Implement this callback to process incoming event notifications. It logs the event type and data, then dispatches to specific handlers based on the event type.

```javascript
event: EventNotification) => {
    console.log(event.type);
    console.log(event.data);

    switch (event.type) {
      case 'user.status.changed':
        updateUserStatus(event.data);
        break;
      case 'system.announcement':
        showAnnouncement(event.data);
        break;
    }
  }
```

--------------------------------

### Handle User Status Change Events

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

This snippet filters for 'user.status.changed' events and logs the user ID and their new status. It assumes the SDK has already been initialized and connected.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    if (event.type === 'user.status.changed') {
        const { userId, status } = event.data;
        console.log(`User ${userId} is now ${status}`);
    }
});
```

--------------------------------

### Handle User Status Changes

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

Listen for 'user.status.changed' custom events to update the UI with user online/offline status and last seen information.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    if (event.type === 'user.status.changed') {
        const { userId, status, lastSeen } = event.data;
        
        // Update UI
        const userElement = document.querySelector(`[data-user-id="${userId}"]`);
        if (userElement) {
            userElement.classList.remove('online', 'offline', 'away');
            userElement.classList.add(status);
            
            if (status === 'offline' && lastSeen) {
                userElement.setAttribute('title', `Last seen: ${new Date(lastSeen).toLocaleString()}`);
            }
        }
    }
});
```

--------------------------------

### Verify Event Listener Registration

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

Confirm that an event listener is correctly registered and being called when an event occurs.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    console.log('Event listener called:', event);
});
```

--------------------------------

### Listen for SDK Errors

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

Register a listener for the SDK's error event to capture and log any errors that occur within the SDK.

```javascript
wkim.on(WKIM.Event.Error, (error) => {
    console.error('SDK Error:', error);
});
```

--------------------------------

### TypeScript Event Handling with Type Safety

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/IMPLEMENTATION_SUMMARY.md

Shows how to use TypeScript's type safety when handling events by importing the EventNotification interface and applying it to the event handler callback.

```typescript
import { EventNotification } from 'easyjssdk';

wkim.on(Event.CustomEvent, (event: EventNotification) => {
    // Full TypeScript support with autocomplete
    console.log(event.id, event.type, event.timestamp, event.data);
});
```

--------------------------------

### Vue Composable for WKIM Connection Management

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/CONNECTION_MANAGEMENT.md

A Vue composable function to manage the WKIM connection. It provides methods to connect and disconnect, and automatically cleans up the connection when the component is unmounted.

```javascript
// composables/useWKIM.js
import { ref, onUnmounted } from 'vue';
import { WKIM } from 'easyjssdk';

export function useWKIM(uid, token) {
    const im = ref(null);
    
    const connect = async () => {
        im.value = WKIM.init('ws://localhost:5100', { uid, token });
        await im.value.connect();
    };
    
    const disconnect = () => {
        if (im.value) {
            im.value.destroy();
            im.value = null;
        }
    };
    
    onUnmounted(() => {
        disconnect();
    });
    
    return { im, connect, disconnect };
}
```

--------------------------------

### Add Event to List and Update Stats

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/example/event-test.html

Processes incoming events, categorizes them (user, channel, system), updates statistics, and displays them in the event list. Limits the display to the last 20 events.

```javascript
function addEvent(event) {
  stats.total++;

  let category = 'other';
  if (event.type.startsWith('user.')) {
    category = 'user';
    stats.user++;
  } else if (event.type.startsWith('channel.')) {
    category = 'channel';
    stats.channel++;
  } else if (event.type.startsWith('system.')) {
    category = 'system';
    stats.system++;
  }

  document.getElementById('totalEvents').textContent = stats.total;
  document.getElementById('userEvents').textContent = stats.user;
  document.getElementById('channelEvents').textContent = stats.channel;
  document.getElementById('systemEvents').textContent = stats.system;

  const eventItem = document.createElement('div');
  eventItem.className = `event-item ${category}`;
  eventItem.innerHTML = `
 <div class="event-header">
 <span class="event-type">${event.type}</span>
 <span class="event-time">${new Date(event.timestamp).toLocaleTimeString()}</span>
 </div>
 <div class="event-data">${JSON.stringify(event.data, null, 2)}</div>
 `;
  eventList.insertBefore(eventItem, eventList.firstChild);

  while (eventList.children.length > 20) {
    eventList.removeChild(eventList.lastChild);
  }
}
```

--------------------------------

### Handle Custom Events with Try-Catch

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

Wrap event handlers in a try-catch block to prevent application crashes. This ensures that errors during event processing are caught and logged, allowing for graceful error handling and reporting.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    try {
        handleEvent(event);
    } catch (error) {
        console.error('Error handling event:', error);
        // Report error to monitoring service
        reportError(error, { eventType: event.type, eventId: event.id });
    }
});
```

--------------------------------

### Show Real-time Browser Notifications

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

Handle 'notification.received' events to display browser notifications to the user. Requires user permission for notifications and supports priority levels.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    if (event.type === 'notification.received') {
        const { title, body, icon, priority } = event.data;
        
        // Show browser notification
        if (Notification.permission === 'granted') {
            new Notification(title, {
                body: body,
                icon: icon || '/default-icon.png',
                tag: event.id,
                requireInteraction: priority === 'high'
            });
        }
    }
});
```

--------------------------------

### Handle Specific Event Types

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/IMPLEMENTATION_SUMMARY.md

Handle different types of custom events by using a switch statement on the event type. This allows for specific logic for each event.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    switch (event.type) {
        case 'user.status.changed':
            // Handle user status change
            break;
        case 'system.announcement':
            // Handle system announcement
            break;
    }
});
```

--------------------------------

### Import EventNotification Interface

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_IMPLEMENTATION.md

Import the EventNotification interface for type safety when working with events.

```typescript
import { EventNotification } from 'easyjssdk';
```

--------------------------------

### Display System Announcements

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

Process 'system.announcement' events to display banner notifications to users, with optional auto-hiding based on an expiration timestamp.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    if (event.type === 'system.announcement') {
        const { message, severity, expiresAt } = event.data;
        
        // Show banner notification
        const banner = document.createElement('div');
        banner.className = `announcement-banner ${severity}`;
        banner.textContent = message;
        document.body.prepend(banner);
        
        // Auto-hide after expiration
        if (expiresAt) {
            const timeout = expiresAt - Date.now();
            setTimeout(() => banner.remove(), timeout);
        }
    }
});
```

--------------------------------

### Add Log Entry to UI

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/example/event-test.html

Appends a new log message to the log display area. It automatically timestamps the message and limits the log history to the last 50 entries.

```javascript
function addLog(message, type = 'info') {
  const logEntry = document.createElement('div');
  logEntry.className = `log-entry ${type}`;
  logEntry.textContent = `[${new Date().toLocaleTimeString()}] ${message}`;
  logList.insertBefore(logEntry, logList.firstChild);

  while (logList.children.length > 50) {
    logList.removeChild(logList.lastChild);
  }
}
```

--------------------------------

### Create Type-Specific Event Handlers

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

A utility function to create filtered handlers for specific event types. This helps in organizing event handling logic by type.

```javascript
function onEventType(eventType, callback) {
    wkim.on(WKIM.Event.CustomEvent, (event) => {
        if (event.type === eventType) {
            callback(event);
        }
    });
}

// Usage
onEventType('user.status.changed', (event) => {
    updateUserUI(event.data);
});

onEventType('system.announcement', (event) => {
    showBanner(event.data.message);
});
```

--------------------------------

### Disconnect from Wukongim Server

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/example/event-test.html

Provides a function to disconnect from the Wukongim server if an active connection exists.

```javascript
disconnectBtn.addEventListener('click', () => {
  if (wkim) {
    wkim.disconnect();
  }
});
```

--------------------------------

### JSON-RPC Event Notification Structure

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

This is the standard JSON-RPC 2.0 format for sending custom event notifications from the server to the client. It includes a method 'event' and parameters containing event details.

```json
{
  "jsonrpc": "2.0",
  "method": "event",
  "params": {
    "header": {
      "noPersist": false,
      "redDot": true,
      "syncOnce": false,
      "dup": false
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "user.status.changed",
    "timestamp": 1704067200000,
    "data": "{\"userId\":\"user123\",\"status\":\"online\"}"
  }
}
```

--------------------------------

### Creating Type-Specific Event Handlers in JavaScript

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

A utility function to create filtered event handlers for specific event types. This simplifies managing different event notifications by routing them to dedicated callback functions.

```javascript
function onEventType(eventType, callback) {
    wkim.on(WKIM.Event.CustomEvent, (eventNotification) => {
        if (eventNotification.type === eventType) {
            callback(eventNotification);
        }
    });
}

// Usage
onEventType('user.status.changed', (event) => {
    console.log('User status changed:', event.data);
});

onEventType('system.announcement', (event) => {
    showNotification(event.data.message);
});
```

--------------------------------

### Deduplicate Events Using Event IDs

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

Utilize a Set to store processed event IDs, preventing duplicate handling and managing memory by cleaning up old IDs.

```javascript
const processedEvents = new Set();

wkim.on(WKIM.Event.CustomEvent, (event) => {
    // Check if already processed
    if (processedEvents.has(event.id)) {
        console.log('Duplicate event ignored:', event.id);
        return;
    }
    
    // Process event
    handleEvent(event);
    
    // Mark as processed
    processedEvents.add(event.id);
    
    // Clean up old IDs (keep last 1000)
    if (processedEvents.size > 1000) {
        const firstId = processedEvents.values().next().value;
        processedEvents.delete(firstId);
    }
});
```

--------------------------------

### Device ID Generation Format

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/CONNECTION_MANAGEMENT.md

The deviceId is automatically generated in the format 'web_{first 8 characters of sessionId}_{timestamp}'.

```plaintext
deviceId: 'web_12345678_1703123456789'
```

--------------------------------

### Automatic Data Parsing in JavaScript

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

The SDK automatically parses the `data` field of an event notification if it is a valid JSON string. If parsing fails, the data remains as a string.

```javascript
// Server sends: data: "{\"userId\":\"123\",\"status\":\"online\"}"
// SDK parses to: data: { userId: "123", status: "online" }

wkim.on(WKIM.Event.CustomEvent, (event) => {
    // data is already parsed as an object
    console.log(event.data.userId);  // "123"
    console.log(event.data.status);  // "online"
});
```

--------------------------------

### Event Notification JSON Structure

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_FLOW.md

This is the JSON structure used by the WuKongIM server to create an event notification. It includes fields like id, type, timestamp, and data.

```json
{
  "jsonrpc": "2.0",
  "method": "event",
  "params": {
    "id": "uuid",
    "type": "user.status.changed",
    "timestamp": 1704067200000,
    "data": "{...}"
  }
}
```

--------------------------------

### Authentication Payload with Session ID

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/CONNECTION_MANAGEMENT.md

The authentication payload sent during connection includes a unique sessionId, along with uid, token, and deviceId.

```json
{
    uid: 'user123',
    token: 'token',
    deviceId: 'web_12345678_1703123456789',
    sessionId: 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'
}
```

--------------------------------

### Error Handler Callback

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_FLOW.md

This callback function is invoked when an Event.Error is emitted. It checks if the error message pertains to an event notification and logs it accordingly. Ensure this handler is registered with wkim.on(Event.Error, ...).

```javascript
(error) => {
    if (error.message.includes('event notification')) {
      console.error('Invalid event:', error);
      // Handle error appropriately
    }
  }
```

--------------------------------

### Handle Incoming Event Notifications in TypeScript

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_IMPLEMENTATION.md

Processes incoming event notifications, validates required fields, attempts to parse JSON data, and emits a custom event. Handles potential parsing or validation errors.

```typescript
private handleEventNotification(params: any): void {
    try {
        const eventData: EventNotification = {
            header: params.header,
            id: params.id,
            type: params.type,
            timestamp: params.timestamp,
            data: params.data
        };

        // Validate required fields
        if (!eventData.id || !eventData.type || !eventData.timestamp || eventData.data === undefined) {
            console.error('Invalid event notification: missing required fields', params);
            this.emit(Event.Error, new Error('Invalid event notification: missing required fields'));
            return;
        }

        // Try to parse data if it's a JSON string
        if (typeof eventData.data === 'string') {
            try {
                eventData.data = JSON.parse(eventData.data);
            } catch (e) {
                // Keep as string if not valid JSON
                console.debug('Event data is not JSON, keeping as string');
            }
        }

        console.log(`Event notification received: type=${eventData.type}, id=${eventData.id}`);
        
        // Emit the custom event to registered listeners
        this.emit(Event.CustomEvent, eventData);
    } catch (error) {
        console.error('Error handling event notification:', error);
        this.emit(Event.Error, new Error(`Failed to handle event notification: ${error}`));
    }
}
```

--------------------------------

### Update Status Display

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/example/event-test.html

Updates the visual status indicator on the UI. Call this function to reflect connection state or other important messages.

```javascript
function updateStatus(status, text) {
  statusEl.className = `status ${status}`;
  statusEl.textContent = text;
}
```

--------------------------------

### Prevent Duplicate Event Processing

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

Utilize a Set to keep track of processed event IDs and avoid handling the same event multiple times.

```javascript
const processedEvents = new Set();

wkim.on(WKIM.Event.CustomEvent, (event) => {
    if (processedEvents.has(event.id)) {
        return; // Already processed
    }
    
    handleEvent(event);
    processedEvents.add(event.id);
});
```

--------------------------------

### Validate User Status Event Data

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL.md

Perform validation on incoming event data to ensure required fields like 'userId' and 'status' are present before processing.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    if (event.type === 'user.status.changed') {
        const { userId, status } = event.data || {};
        
        if (!userId || !status) {
            console.error('Invalid user status event data:', event.data);
            return;
        }
        
        updateUserStatus(userId, status);
    }
});
```

--------------------------------

### EventNotification Interface Definition

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/IMPLEMENTATION_SUMMARY.md

Defines the structure for event notifications, including optional headers, unique IDs, event types, timestamps, and a data payload that is automatically parsed from JSON.

```typescript
interface EventNotification {
    header?: Header;      // Optional message flags
    id: string;          // Unique event identifier (UUID)
    type: string;        // Event type (e.g., "user.status.changed")
    timestamp: number;   // Event timestamp in milliseconds
    data: string | any;  // Event payload (auto-parsed from JSON)
}
```

--------------------------------

### Clear Log Display

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/example/event-test.html

Clears all messages from the log display area. Useful for maintaining a clean log view.

```javascript
clearLogsBtn.addEventListener('click', () => {
  logList.innerHTML = '';
  addLog('Logs cleared', 'info');
});
```

--------------------------------

### Clear Event Display and Stats

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/example/event-test.html

Resets the event list UI and clears all event statistics. Use this to clean up the displayed events.

```javascript
clearEventsBtn.addEventListener('click', () => {
  eventList.innerHTML = '';
  stats = {
    total: 0,
    user: 0,
    channel: 0,
    system: 0
  };
  document.getElementById('totalEvents').textContent = '0';
  document.getElementById('userEvents').textContent = '0';
  document.getElementById('channelEvents').textContent = '0';
  document.getElementById('systemEvents').textContent = '0';
  addLog('Events cleared', 'info');
});
```

--------------------------------

### Define EventNotification Interface in TypeScript

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_IMPLEMENTATION.md

Defines the structure for incoming event notifications, including optional headers and required event details. The 'data' field can be a string or any parsed object.

```typescript
export interface EventNotification {
    /** Optional header with message flags */
    header?: Header;
    /** Unique event identifier */
    id: string;
    /** Event type/category */
    type: string;
    /** Event timestamp (milliseconds) */
    timestamp: number;
    /** Event data payload (JSON string or object) */
    data: string | any;
}
```

--------------------------------

### Integrate Event Notifications into Handler in TypeScript

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_IMPLEMENTATION.md

Updates the main notification handler to route 'event' method calls to the specific `handleEventNotification` function. This ensures custom events are processed correctly.

```typescript
private handleNotification(notification: JsonRpcNotification): void {
    console.debug(`<-- Handling notification (${notification.method}):`, notification.params);
    switch (notification.method) {
        case 'recv':
            // ... existing code
            break;
        case 'pong':
            // ... existing code
            break;
        case 'disconnect':
            // ... existing code
            break;
        case 'event':
            this.handleEventNotification(notification.params);
            break;
        default:
            console.warn(`Received unhandled notification method: ${notification.method}`);
    }
}
```

--------------------------------

### Validate Event Data

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_QUICKSTART.md

Always validate incoming event data to ensure required fields like userId and status are present before processing.

```javascript
wkim.on(WKIM.Event.CustomEvent, (event) => {
    const { userId, status } = event.data || {};
    
    if (!userId || !status) {
        console.error('Invalid event data');
        return;
    }
    
    updateUserStatus(userId, status);
});
```

--------------------------------

### Define Custom Event Enum Value in TypeScript

Source: https://github.com/wukongim/wukongeasysdk-js/blob/main/docs/EVENT_PROTOCOL_IMPLEMENTATION.md

Adds a new enum value for custom event notifications. Ensure this is used consistently with server-side event types.

```typescript
export enum Event {
    // ... existing events
    /** Received a custom event notification from the server */
    CustomEvent = 'customevent',
}
```
Tokens:
Raw