Skip to main content

​
Overview

WuKongIM iOS EasySDK is a lightweight iOS SDK that enables you to add real-time chat functionality to your iOS application in just 5 minutes. This guide will take you through the complete process from installation to sending your first message.
System Requirements: iOS 12.0 or higher, Xcode 12.0 or higher, Swift 5.0 or higher

​
Step 1: Install SDK

Choose any of the following methods to install iOS EasySDK:
Add to your Podfile:
pod 'WuKongEasySDK', '~> 1.0.0'
Then run:
pod install

​
Step 2: Basic Integration

​
2.1 Import SDK

import WuKongEasySDK

​
2.2 Initialize SDK

// 1. Initialize SDK
let config = WuKongConfig(
    serverUrl: "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: .APP // Optional: Device flag, default is .APP
)

let easySDK = WuKongEasySDK(config: config)

​
2.3 Listen for Events

// 2. Listen for various events
easySDK.onConnect { result in
    print("Event: Connected!", result)
    // Connection successful, can start sending messages
    DispatchQueue.main.async {
        self.updateUI(connected: true)
    }
}

easySDK.onDisconnect { disconnectInfo in
    print("Event: Disconnected.", disconnectInfo)
    print("Disconnect code: \(disconnectInfo.code), reason: \(disconnectInfo.reason)")
    // Connection lost, update UI status
    DispatchQueue.main.async {
        self.updateUI(connected: false)
    }
}

easySDK.onMessage { message in
    print("Event: Message Received", message)
    // Handle received messages
    DispatchQueue.main.async {
        self.displayMessage(message)
    }
}

easySDK.onError { error in
    print("Event: Error Occurred", error.localizedDescription)
    // Handle errors, may need to update UI or reconnect
    DispatchQueue.main.async {
        self.handleError(error)
    }
}

// You can add multiple listeners for the same event
easySDK.onMessage { message in
    print("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. iOS EasySDK provides methods to remove listeners.
Important Reminder: In iOS, removing event listeners requires maintaining references to the listeners. It’s recommended to use class properties to store listener references for later removal.

​
Correct Usage

class ChatManager {
    private let easySDK: WuKongEasySDK

    // Save listener references
    private var messageListener: EventListener?
    private var connectListener: EventListener?
    private var disconnectListener: EventListener?
    private var errorListener: EventListener?

    init(config: WuKongConfig) {
        self.easySDK = WuKongEasySDK(config: config)
    }

    func setupEventListeners() {
        // ✅ Correct: Save listener references
        messageListener = easySDK.onMessage { [weak self] message in
            print("Handle message:", message)
            DispatchQueue.main.async {
                self?.handleMessage(message)
            }
        }

        connectListener = easySDK.onConnect { [weak self] result in
            print("Connection successful:", result)
            DispatchQueue.main.async {
                self?.handleConnect(result)
            }
        }

        disconnectListener = easySDK.onDisconnect { [weak self] disconnectInfo in
            print("Connection lost:", disconnectInfo)
            print("Disconnect code: \(disconnectInfo.code), reason: \(disconnectInfo.reason)")
            DispatchQueue.main.async {
                self?.handleDisconnect(disconnectInfo)
            }
        }

        errorListener = easySDK.onError { [weak self] error in
            print("Error occurred:", error)
            DispatchQueue.main.async {
                self?.handleError(error)
            }
        }
    }

    func removeEventListeners() {
        // Remove specific event listeners - use saved references
        if let listener = messageListener {
            easySDK.removeListener(listener)
            messageListener = nil
        }

        if let listener = connectListener {
            easySDK.removeListener(listener)
            connectListener = nil
        }

        if let listener = disconnectListener {
            easySDK.removeListener(listener)
            disconnectListener = nil
        }

        if let listener = errorListener {
            easySDK.removeListener(listener)
            errorListener = nil
        }
    }

    private func handleMessage(_ message: Message) {
        // Message handling logic
    }

    private func handleConnect(_ result: ConnectResult) {
        // Connection success handling logic
    }

    private func handleDisconnect(_ disconnectInfo: DisconnectInfo) {
        // Connection lost handling logic
        print("Handle disconnect event - code: \(disconnectInfo.code), reason: \(disconnectInfo.reason)")
    }

    private func handleError(_ error: Error) {
        // Error handling logic
    }
}

​
2.5 Connect to Server

// 4. Connect to server
Task {
    do {
        try await easySDK.connect()
        print("Connection successful!")
    } catch {
        print("Connection failed:", error)
    }
}

​
2.6 Send Messages

// 5. Send message example
func sendMessage() async {
    let targetChannelID = "friend_user_id" // Target user ID
    let messagePayload = MessagePayload(
        type: 1,
        content: "Hello from iOS EasySDK!"
    ) // Your custom message payload
    
    do {
        let result = try await easySDK.send(
            channelId: targetChannelID,
            channelType: .person,
            payload: messagePayload
        )
        print("Message sent successfully:", result)
    } catch {
        print("Message sending failed:", error)
    }
}

​
Step 3: Error Handling and Best Practices

​
3.1 Error Handling

Built-in Auto Reconnection: iOS EasySDK has built-in intelligent reconnection mechanism, no need to manually implement reconnection logic. The SDK will automatically attempt to reconnect when the connection is lost.
// Proper connection status listening
easySDK.onConnect { result in
    print("Connection successful:", result)
    // Update UI status, enable sending functionality
    DispatchQueue.main.async {
        self.updateConnectionUI(connected: true)
    }
}

easySDK.onDisconnect { disconnectInfo in
    print("Connection lost:", disconnectInfo)
    print("Disconnect code: \(disconnectInfo.code), reason: \(disconnectInfo.reason)")
    // Update UI status, disable sending functionality
    DispatchQueue.main.async {
        self.updateConnectionUI(connected: false)
    }
    // SDK will automatically attempt to reconnect, no manual handling needed
}

easySDK.onError { error in
    print("Error occurred:", error)

    // Handle based on error type
    DispatchQueue.main.async {
        switch error {
        case WuKongError.authFailed:
            // Authentication failed, need to get new token
            self.handleAuthError()
        case WuKongError.networkError:
            // Network error, show network prompt
            self.showNetworkError()
        default:
            // Other errors
            self.showGeneralError(error.localizedDescription)
        }
    }
}

Complete Example Code

View complete example code and more feature demonstrations

Complete Protocol Documentation

View WuKongIM’s complete protocol documentation

GitHub Repository

Visit EasyJSSDK’s GitHub repository

Issue Feedback

Report issues or provide suggestions

​
Next Steps

Congratulations! You have successfully integrated WuKongIM iOS EasySDK. Now you can:
  1. Extend Functionality: Add group chat, file transfer and other features
  2. Customize UI: Customize chat interface according to your app design
  3. Integrate into Project: Integrate chat functionality into your existing project
  4. Performance Optimization: Optimize performance based on actual usage
If you need more complex functionality or higher performance requirements, consider using the full version of WuKongIMSDK.