XuqmGroup-Web/docs-site/docs/ios/index.md

iOS SDK 概览

版本：0.1.0 · 最低 iOS 版本：iOS 14 · 语言：Swift 5.9+

功能模块

模块	功能
XuqmCore	初始化、网络、鉴权、UserSig 过期检测
XuqmIM	单聊、群聊、消息收发（15 种类型）、连接状态监听
XuqmPush	APNs 设备 Token 注册、FCM 备选、通知处理
XuqmUpdate	App 版本检查、App Store 跳转

安装

Swift Package Manager（推荐）

在 Xcode → File → Add Package Dependencies 中输入：

https://github.com/xuqm/XuqmGroup-iOSSDK

或在 Package.swift 中添加：

dependencies: [
    .package(url: "https://github.com/xuqm/XuqmGroup-iOSSDK", from: "0.1.0")
]

按需引入所需模块：

.target(
    name: "MyApp",
    dependencies: [
        .product(name: "XuqmCore", package: "XuqmGroup-iOSSDK"),
        .product(name: "XuqmIM",   package: "XuqmGroup-iOSSDK"),
        .product(name: "XuqmPush", package: "XuqmGroup-iOSSDK"),
        .product(name: "XuqmUpdate", package: "XuqmGroup-iOSSDK"),
    ]
)

快速接入

1. 初始化

在 AppDelegate.application(_:didFinishLaunchingWithOptions:) 中：

import XuqmCore

let config = SDKConfig(appId: "your_app_id", appSecret: "your_app_secret")
XuqmSDK.shared.initialize(config: config)

2. IM 登录与监听消息（UserSig 模式）

import XuqmIM

// 方式一：使用 UserSig 登录（推荐生产环境）
try await XuqmSDK.shared.login(userId: "user_001", userSig: "your_user_sig_jwt")

// 方式二：Demo 环境快速登录
try await ImSDK.shared.loginWithDemo(userId: "user_001", password: "123456")

// 设置事件代理
ImSDK.shared.setDelegate(self)

extension ViewController: ImEventDelegate {
    func imClientDidConnect() { print("WS connected") }
    func imClientDidReceiveMessage(_ msg: ImMessage) { /* 处理单聊消息 */ }
    func imClientDidReceiveGroupMessage(_ msg: ImMessage) { /* 处理群消息 */ }
    func imClientDidReadMessage(_ msg: ImMessage) { /* 对方已读回执 */ }
    func imClientDidReceiveRevokedMessage(_ msg: ImMessage) { /* 消息被撤回 */ }
    func imClientDidDisconnect(reason: String?) { /* 断线 */ }
    func imClientDidError(_ error: String) { /* 错误 */ }
}

3. 连接状态监听

SDK 暴露 connectionState 属性与 addConnectionStateListener，方便业务层实时感知 WebSocket 连接状态：

// 查询当前状态
let state = ImSDK.shared.connectionState
// 返回：.disconnected / .connecting / .connected

// 注册状态变更监听器
ImSDK.shared.addConnectionStateListener { state in
    switch state {
    case .connected:
        print("IM 已连接")
    case .connecting:
        print("IM 连接中...")
    case .disconnected:
        print("IM 已断开")
    }
}

状态变更触发时机：

• 登录后 → .connecting → .connected
• 网络异常/断线 → .disconnected，内部自动重连 → .connecting → .connected
• 调用 disconnect() 或 logout() → .disconnected

4. 发送消息

// 发文本
let msg = ImSDK.shared.sendTextMessage(
    toId: "user_002",
    chatType: .single,
    content: "Hello!"
)

// 发图片
let imgContent = try JSONSerialization.data(withJSONObject: [
    "url": "https://cdn.example.com/img.jpg",
    "width": 800, "height": 600
])
let msg2 = try await ImSDK.shared.sendMessage(
    toId: "user_002", chatType: .single,
    msgType: .image, content: String(data: imgContent, encoding: .utf8)!
)

5. 撤回与编辑

// 撤回消息
let revoked = try await ImSDK.shared.revokeMessage(messageId: msg.id)

// 编辑消息
let edited = try await ImSDK.shared.editMessage(messageId: msg.id, content: "新内容")

6. 群聊

// 创建群组
let group = try await ImSDK.shared.createGroup(name: "我的群", memberIds: ["user_001", "user_002"])

// 订阅群消息
ImSDK.shared.subscribeGroup(group.id)

// 发送群消息
ImSDK.shared.sendTextMessage(toId: group.id, chatType: .group, content: "大家好")

// 群管理
 try await ImSDK.shared.addGroupMember(groupId: group.id, userId: "user_003")
 try await ImSDK.shared.leaveGroup(groupId: group.id)

7. 会话管理

// 会话列表
let conversations = try await ImSDK.shared.listConversations()

// 置顶 / 静音 / 已读 / 草稿 / 删除
try await ImSDK.shared.setConversationPinned(targetId: "user_002", chatType: .single, pinned: true)
try await ImSDK.shared.setConversationMuted(targetId: "user_002", chatType: .single, muted: true)
try await ImSDK.shared.markRead(targetId: "user_002", chatType: .single)
try await ImSDK.shared.setDraft(targetId: "user_002", chatType: .single, draft: "未完成")
try await ImSDK.shared.deleteConversation(targetId: "user_002", chatType: .single)

8. Push 设备注册（APNs + FCM）

import XuqmPush

// 请求通知授权并自动注册 APNs
let granted = try await PushSDK.shared.requestAuthorization(options: [.alert, .badge, .sound])

// 在 AppDelegate 中转发 deviceToken
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    XuqmSDK.shared.registerDeviceToken(deviceToken)
}

// 如需手动注册 FCM Token（若集成 FirebaseMessaging）
try await PushSDK.shared.registerFcmToken(fcmToken, userId: "user_001")

9. UserSig 过期检测

XuqmSDK 会在登录时解析 UserSig JWT 的 exp 字段，并在过期前 5 分钟触发 onUserSigExpired 回调。业务层应在此回调中重新获取 UserSig 并登录。

// 设置过期回调（建议在初始化后设置）
XuqmSDK.shared.onUserSigExpired = { [weak self] in
    Task {
        let newUserSig = await self?.yourBackend.refreshUserSig()
        try? await XuqmSDK.shared.login(userId: "user_001", userSig: newUserSig)
    }
}

注意：

• 回调触发时机为 exp - 300s（提前 5 分钟）。
• 调用 logout() 后内部 Timer 会被自动 invalidate。
• 若 UserSig 已过期（exp <= now），回调会立即触发。

10. 检查更新

import XuqmUpdate

// App 整包更新
let appInfo = try await UpdateSDK.shared.checkAppUpdate(currentVersionCode: 1)
if let info = appInfo, info.forceUpdate == true {
    UpdateSDK.shared.openAppStore(url: info.appStoreUrl ?? info.downloadUrl!)
}

消息类型

MsgType	说明	content 结构
.text	纯文本	String
.image	图片	{url, width, height, thumbnailUrl?}
.video	视频	{url, duration, thumbnailUrl, size}
.audio	语音	{url, duration, size}
.file	文件	{url, name, size, mimeType}
.location	位置	{lat, lng, address, title}
.custom	自定义	任意 JSON
.notify	系统通知	{title, content}
.richText	富文本	{html}
.callAudio	语音通话信令	{callId, action, callerName}
.callVideo	视频通话信令	{callId, action, callerName}
.forward	转发	{originalMsgId, originalContent, originalSender}
.quote	引用	{quotedMsgId, quotedContent, text}
.merge	合并转发	{title, msgList}
.revoked	撤回	系统内部填充