XuqmGroup iOS SDK 文档

Swift 5.9 · iOS 16+ · macOS 13+ · async/await

模块结构

XuqmGroup-iOSSDK/
├── Package.swift            # SPM 包定义
├── XuqmSDK.podspec          # CocoaPods 发版描述
├── PUBLISH.md               # 发版操作手册
└── Sources/XuqmSDK/
    ├── Core/
    │   ├── XuqmSDK.swift    # 入口：init / setToken
    │   ├── SDKConfig.swift  # 配置结构体
    │   ├── ApiClient.swift  # HTTP 客户端（URLSession）
    │   └── TokenStore.swift # Keychain Token 存储
    ├── IM/
    │   └── ImClient.swift   # WebSocket IM 客户端
    ├── Push/
    │   └── PushSDK.swift    # APNs Token 注册
    └── Update/
        └── UpdateSDK.swift  # 版本检查 / App 更新

集成

Swift Package Manager（推荐）

在 Xcode → File → Add Package Dependencies，输入仓库地址：

https://xuqinmin.com/xuqinmin12/XuqmGroup-iOSSDK.git

选择版本规则 Up to Next Major: 0.1.0。

或在 Package.swift 中添加：

dependencies: [
    .package(url: "https://xuqinmin.com/xuqinmin12/XuqmGroup-iOSSDK.git", from: "0.1.0")
],
targets: [
    .target(name: "YourApp", dependencies: ["XuqmSDK"])
]

CocoaPods

# Podfile
source 'https://xuqinmin.com/xuqinmin12/xuqm-specs.git'
source 'https://cdn.cocoapods.org/'

pod 'XuqmSDK', '~> 0.1.0'

---

快速开始

1. 初始化（AppDelegate / @main）

import XuqmSDK

@main
struct MyApp: App {
    init() {
        XuqmSDK.initialize(
            appKey: "ak_your_app_key",
            appSecret: "as_your_app_secret",
            apiBaseUrl: "https://api.xuqm.com",
            imBaseUrl: "wss://im.xuqm.com",
            debug: true
        )
    }
}

2. 登录后存储 Token

// 调用你的业务登录接口获得 token
await XuqmSDK.setToken(token)

---

Core

ApiClient

基于 URLSession，async/await，自动附加 Bearer Token，统一解析 ApiResponse<T>。

// 定义响应模型
struct LoginResponse: Decodable {
    let token: String
}

// 发起请求
let response: LoginResponse = try await ApiClient.post(
    path: "/api/im/auth/login",
    body: ["appId": appId, "userId": userId]
)

TokenStore

基于 Keychain 存储（kSecClassGenericPassword），App 重启后自动恢复。

await XuqmSDK.setToken("eyJ...")    // 存储
let token = XuqmSDK.getToken()      // 读取（同步）
await XuqmSDK.setToken(nil)         // 清除（登出）

---

IM

ImClient

import XuqmSDK

class ChatViewController: UIViewController, ImEventDelegate {

    let imClient = ImClient()

    override func viewDidLoad() {
        super.viewDidLoad()
        imClient.delegate = self
        imClient.connect()
    }

    // 发送消息
    func sendMessage() throws {
        try imClient.send(SendMessageParams(
            toId: "user_002",
            chatType: .single,
            msgType: .text,
            content: "Hello!"
        ))
    }

    // 撤回消息
    func revokeMessage(msgId: String) throws {
        try imClient.revoke(msgId: msgId)
    }

    deinit { imClient.disconnect() }
}

// MARK: - ImEventDelegate
extension ChatViewController {
    func onConnected() { print("IM 连接成功") }
    func onDisconnected(code: Int, reason: String) { print("断开: \(code)") }
    func onMessage(_ msg: ImMessage) { /* 更新 UI */ }
    func onRevoke(msgId: String, operatorId: String) { /* 标记消息已撤回 */ }
    func onError(_ error: Error) { print("错误: \(error)") }
}

ImMessage 结构

public struct ImMessage: Decodable {
    public let id: String
    public let fromId: String
    public let toId: String
    public let chatType: ChatType      // single / group
    public let msgType: MsgType
    public let content: String
    public let extra: String?
    public let revoked: Bool
    public let createdAt: String
    public let editedAt: Int64?
}

消息类型（MsgType）

text / image / video / audio / file / custom / location / notify / richText / callAudio / callVideo / forward

自动重连

断线后指数退避重连，初始 3s，最大 30s。disconnect() 后停止。

---

Push

import XuqmSDK

// 在 didRegisterForRemoteNotificationsWithDeviceToken 中调用
func application(_ application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Task {
        try await PushSDK.registerToken(
            appId: "ak_xxx",
            userId: "user_001",
            token: deviceToken
        )
    }
}

PushSDK.registerToken 内部将 Data 转换为十六进制字符串，vendor 固定为 APNS。

---

Update

检查原生版本更新

import XuqmSDK

let result = try await UpdateSDK.checkAppUpdate(appId: "ak_xxx")
if result.needsUpdate, let info = result.info {
    print("最新版本: \(info.versionName)")
    // iOS 只能跳转 App Store
    if let url = URL(string: info.appStoreUrl) {
        await UIApplication.shared.open(url)
    }
}

UpdateSDK 这里只负责 iOS App 版本更新。RN 热更新如果需要，走独立的 RN SDK / RN 更新模块，不并入统一发版能力。

---

发版

SPM（推荐）

git add -A && git commit -m "release: 0.1.0"
git tag 0.1.0
git push origin main 0.1.0

Xcode 用户在 Package Dependencies 刷新即可获取新版本。

CocoaPods 私有 Spec

# 首次（只需一次）
pod repo add xuqm-specs https://xuqinmin.com/xuqinmin12/xuqm-specs.git

# 每次发版
pod spec lint XuqmSDK.podspec --allow-warnings
pod repo push xuqm-specs XuqmSDK.podspec --allow-warnings