跳到主要内容

iOS SDK 快速集成 (QXJIMSDK)

QXJIMSDK 是专为全新重写版 qxj-ios 打造的 100% 纯 Swift IM SDK，基于 Apache-2.0 协议的 OpenIMCore.xcframework (3.8.3+3) 构建，完全消除了旧版 Objective-C OpenIMSDK 与 MJExtension 依赖。

1. 环境要求​

  • iOS 部署目标：iOS 15.0+
  • Swift 版本：Swift 5.9+ (Xcode 15.0+)
  • 架构支持：
    • 真机：arm64 (ios-arm64)
    • 模拟器：arm64 (Apple Silicon Mac) & x86_64 (Intel Mac) (ios-arm64_x86_64-simulator)

2. 使用 Swift Package Manager 安装​

方式一：通过公司 Nexus 原生 Swift Package Registry（推荐）​

公司测试服 Nexus 已开启原生 Swift Package Registry (SE-0292) 仓库（https://nexus.test.qxjapp.com/repository/qxj-swift/），并将 QXJIMSDK 发布为标准 Registry 包 qxj.QXJIMSDK。使用该方式无需 clone 庞大的 Go 源码仓库，SwiftPM 仅拉取纯 Swift 源码归档与 OpenIMCore.xcframework.zip 二进制产物。

1) 配置本地或 CI 的 Swift Registry 源（首次执行一次）​

swift package-registry set https://nexus.test.qxjapp.com/repository/qxj-swift/

2) 在 Package.swift 中直接按 Registry ID (qxj.QXJIMSDK) 声明依赖​

dependencies: [
    .package(id: "qxj.QXJIMSDK", from: "3.8.3")
],
targets: [
    .target(
        name: "QXJChatFeature",
        dependencies: [
            .product(name: "QXJIMSDK", package: "qxj.QXJIMSDK")
        ]
    )
]

方式二：在 qxj-ios/Packages/QXJIMSDK 中作为本地模块 + Nexus 远程 XCFramework​

若希望在 qxj-ios 工程内直接调试 QXJIMSDK 的 Swift 源码，可保留 qxj-ios/Packages/QXJIMSDK 目录（仅含 7 个纯 Swift 文件），并在其 Package.swift 中从 Nexus 拉取 OpenIMCore.xcframework.zip：

// qxj-ios/Packages/QXJIMSDK/Package.swift
// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "QXJIMSDK",
    platforms: [.iOS(.v15)],
    products: [
        .library(name: "QXJIMSDK", targets: ["QXJIMSDK"])
    ],
    targets: [
        .binaryTarget(
            name: "OpenIMCore",
            url: "https://nexus.test.qxjapp.com/repository/qxj-raw/im-core/ios/3.8.3-patch.3/OpenIMCore.xcframework.zip",
            checksum: "b7d383a58ec52ce25bdc013038a4c831aa4280391ec92511c95c3091f3c64a7d"
        ),
        .target(
            name: "QXJIMSDK",
            dependencies: ["OpenIMCore"],
            path: "Sources/QXJIMSDK",
            linkerSettings: [
                .linkedLibrary("resolv"),
                .linkedFramework("SystemConfiguration"),
                .linkedFramework("CoreTelephony")
            ]
        )
    ]
)

在业务 Feature 模块中引用该本地 Package 时，package 名称为 "QXJIMSDK"：

dependencies: [
    .package(path: "../QXJIMSDK")
],
targets: [
    .target(
        name: "QXJChatFeature",
        dependencies: [
            .product(name: "QXJIMSDK", package: "QXJIMSDK")
        ]
    )
]

方式三：直接通过 Git URL 引用 qxj-im-core 仓库​

若直接通过 Git URL 引用本仓库（注意：SwiftPM 会根据 Git URL 末尾仓库名将 package 标识解析为 "qxj-im-core"）：

dependencies: [
    .package(url: "https://git.home.qxjapp.com/JCTX/qxj-im-core.git", branch: "main")
],
targets: [
    .target(
        name: "QXJChatFeature",
        dependencies: [
            .product(name: "QXJIMSDK", package: "qxj-im-core")
        ]
    )
]
零额外 Linker Flag 配置

QXJIMSDK 的 Package.swift 已自动声明 .linkedLibrary("resolv")、SystemConfiguration 与 CoreTelephony，且完全不依赖 Objective-C Category 动态反射，因此无需在 Xcode Build Settings 中手动配置 -ObjC 或 -lresolv。

3. 五分钟上手流程​

import Foundation
import QXJIMSDK

@MainActor
final class IMBootstrapService {
    func startIM(userID: String, token: String) async throws {
        // 1. 准备本地 SQLite 与日志存储目录
        let docDir = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true).first!
        let config = IMConfig(
            platform: .iOS,
            apiAddr: "https://im-api.qxj.com",
            wsAddr: "wss://im-ws.qxj.com",
            dataDir: "\(docDir)/qxj_im_data",
            logLevel: 4
        )

        // 2. 初始化 SDK（自动挂载全部 7 大实时事件流）
        try QXJIMClient.shared.initSDK(config: config)

        // 3. 启动后台协程监听连接状态与新消息
        listenToEvents()

        // 4. 登录账号
        try await QXJIMClient.shared.login(userID: userID, token: token)
    }

    private func listenToEvents() {
        Task {
            for await connEvent in QXJIMClient.shared.connectionEvents.stream() {
                print("[IM 连接状态]: \(connEvent)")
            }
        }

        Task {
            for await msgEvent in QXJIMClient.shared.messageEvents.stream() {
                if case .receivedNewMessage(let message) = msgEvent {
                    print("[收到新消息]: \(message.clientMsgID ?? "") - \(message.textElem?.content ?? "")")
                }
            }
        }
    }
}