iOS 集成方式

iOS 端提供四种集成方式，任选其一即可，产物与公开符号完全一致：CocoaPods 远程 framework（推荐，依赖管理最省心）、CocoaPods IMKit 源码集成（需要改 UI 源码 / 二次定制时）、Swift Package Manager（Xcode 原生、版本锁定清晰）、手动导入 XCFramework（完全离线 / 定制构建）。包名 ImpIaaSIM（Swift Package），最低 iOS 13。

选型建议

已有 CocoaPods 工程：直接 `pod` 集成，升级用 `pod update`。

纯 SPM 工程或希望 Xcode 内管理版本：用 Swift Package，支持按 target 精确依赖。

需要改 IMKit 源码做深度定制：用 CocoaPods 源码集成（IMKit 以源码形式编进工程）。

不能访问包管理源 / 需要裁剪架构：用手动 XCFramework，注意同时导入 `.dSYM` 便于崩溃符号化。

方式一：CocoaPods

# Podfile
platform :ios, '13.0'
use_frameworks!

target 'YourApp' do
  pod 'ImpIaaSIM', '~> 1.0'       # IMLib：连接、消息、会话、群组、好友、聊天室、上传
  pod 'ImpIaaSIMKit', '~> 1.0'    # IMKit：可选，UI 组件
end

cd YourApp
pod repo update
pod install --repo-update
open YourApp.xcworkspace      # 之后一律打开 workspace，不要打开 .xcodeproj

Objective-C 工程同样使用这两个 pod：`use_frameworks!` 后 `#import `。
升级：修改 Podfile 版本后 `pod update ImpIaaSIM ImpIaaSIMKit`，并回归连接 / 收发 / 本地历史。
组件化工程：把 `ImpIaaSIM` 依赖放在通信层模块，`ImpIaaSIMKit` 只被 UI 模块依赖。

方式二：CocoaPods IMKit 源码集成

IMKit 需要二次开发（改消息气泡、会话列表、输入区实现）时，可以用源码方式集成：把 IMKit 以源码 pod 加入工程，IMLib 仍用远程 framework。适合深度定制，但升级时需要自行合并上游改动。

# Podfile：IMKit 源码 + IMLib framework
platform :ios, '13.0'
use_frameworks!

target 'YourApp' do
  pod 'ImpIaaSIM', '~> 1.0'                       # IMLib：远程 framework
  pod 'ImpIaaSIMKit', :path => './ImpIaaSIMKit'   # IMKit：本地源码 pod
end

同一 Podfile 不能混用 framework 与源码

同一个组件只能用一种形态：不要同时声明 `pod 'ImpIaaSIMKit'`（远程 framework）与本地源码 pod，否则会出现重复符号或两份实现。

源码集成后升级 IMKit 需要手动合并；建议把定制点收敛到子类 / 协议实现，减少与上游的 diff。

IMLib 仍建议用远程 framework，避免把通信层源码混进业务工程。
源码集成需要把 IMKit 依赖的图片、颜色、本地化资源加入 Copy Bundle Resources。
确认 `use_frameworks!` 与 Swift / Objective-C 混编设置一致，避免 module 找不到。

方式三：Swift Package Manager

// Package.swift（库工程）
dependencies: [
    .package(url: "https://example.com/ImpIaaSIM.git", from: "1.0.0"),
    .package(url: "https://example.com/ImpIaaSIMKit.git", from: "1.0.0"),
],
targets: [
    .target(
        name: "YourFeature",
        dependencies: [
            .product(name: "ImpIaaSIM", package: "ImpIaaSIM"),
            .product(name: "ImpIaaSIMKit", package: "ImpIaaSIMKit"),
        ]
    ),
]

Xcode 工程：File → Add Package Dependencies… → 输入仓库地址 → 选择版本规则（建议 `Up to Next Major`）→ 勾选 `ImpIaaSIM` 与 `ImpIaaSIMKit`。

SPM 与 CocoaPods 不要混用

同一工程里只保留一种集成方式；混用会出现同名模块重复链接（`Multiple commands produce ...`）。

方式四：手动导入 XCFramework

下载 `ImpIaaSIM.xcframework`、`ImpIaaSIMKit.xcframework` 与对应 `.dSYM`。
把 `.xcframework` 拖入 Xcode 工程（Copy items if needed）。
Target → General → Frameworks, Libraries, and Embedded Content：设为 Embed & Sign。
Target → Build Settings → Framework Search Paths 指向 xcframework 所在目录。
若工程是 Objective-C：在 Build Settings 打开 `Defines Module = YES`，用 `#import `。

# 校验 xcframework 架构与签名
lipo -info ImpIaaSIM.xcframework/ios-arm64/ImpIaaSIM.framework/ImpIaaSIM
codesign -dv --verbose=4 ImpIaaSIM.xcframework/ios-arm64/ImpIaaSIM.framework

# 校验 dSYM（崩溃符号化必备）
dwarfdump --uuid ImpIaaSIM.xcframework/ios-arm64/ImpIaaSIM.framework/ImpIaaSIM
dwarfdump --uuid ImpIaaSIM.xcframework/ios-arm64/dSYMs/ImpIaaSIM.framework.dSYM

本仓库本地集成（未发布 / 联调）

SDK 未发布到包管理源时，用本地路径集成；以下命令按本仓库实际产物给出（模拟器 x86_64）。

# 方式 A：SPM 本地路径（Package.swift）
.package(path: "../sdk/ios")

# 方式 B：CocoaPods 本地 podspec
pod 'ImpIaaSIM', :path => '../sdk/ios'
pod 'ImpIaaSIMKit', :path => '../sdk/ios'

# 方式 C：手工链接 framework / XCFramework（模拟器）
FW="../sdk/ios/build/ImpIaaSIM.framework"
SDK=$(xcrun --sdk iphonesimulator --show-sdk-path)
xcrun swiftc -sdk "$SDK" -target x86_64-apple-ios18.0-simulator   -F ../sdk/ios/build -I "$FW/Modules"   -framework ImpIaaSIM -framework UIKit -framework Foundation   -Xlinker -rpath -Xlinker @executable_path/Frameworks   -o MyApp main.swift
# 注意：只给 -F 时 Swift 编译器看不到 Swift 声明，必须同时加 -I "$FW/Modules"

当前 XCFramework 仅含 Intel 模拟器 slice

仓库内 ImpIaaSIM.xcframework 目前只有 ios-x86_64-simulator 一个 slice：Apple Silicon 模拟器链接会失败，这是已知环境限制（arm64 slice 待补）。在 Apple Silicon 上请改用 SPM 源码 / 本地 framework 构建，或使用 x86_64 模拟器（Rosetta）。

手工集成后把 framework 设为 **Embed & Sign**，并确认 rpath 为 `@executable_path/Frameworks`。
Objective-C 工程需 `Defines Module = YES`，`#import `。
IMKit / Global UIKit 的本地集成方式相同（替换 framework 名称即可）。

四种方式对照

维度	CocoaPods framework	CocoaPods 源码	Swift Package Manager	手动 XCFramework
接入成本	低（Podfile 两行）	中（本地 pod + 资源）	低（Xcode 内添加依赖）	中（拖入 + Embed & Sign + 搜索路径）
版本管理	`Podfile.lock` 锁定	自行维护源码版本	`Package.resolved` 锁定	人工记录版本与哈希
离线可用	需本地 podspec 仓库	完全离线（源码在本地）	需可访问包仓库或本地路径依赖	完全离线
定制能力	低（仅配置）	高（可改实现）	低（仅配置）	低（仅配置）
Objective-C	开箱可用	开箱可用	开箱可用	需 `Defines Module`
升级	`pod update`	手动合并上游	Xcode 更新依赖	替换 xcframework 并重新 Embed

接入后自检

import ImpIaaSIM

Task { @MainActor in
    // 1) 版本与初始化（不建立连接）
    let version = ImpIaaSIM.contractVersion
    let client = ImpIaaSIM.client(options: IMPClientOptions(
        appkey: "YOUR_APP_KEY",
        serverUrl: "https://im.example.com"
    ))
    print("ImpIaaSIM", version, client)

    // 2) 连接并在回调里打印错误码
    let res = await client.connect(token: "TOKEN")
    print("connect code:", res.code, res.msg ?? "")
}

下一步：工程配置（Info.plist / ATS / 后台模式）→ 快速开始 → Objective-C 接入。

iOS 集成方式

方式一：CocoaPods​

方式二：CocoaPods IMKit 源码集成​

方式三：Swift Package Manager​

方式四：手动导入 XCFramework​

本仓库本地集成（未发布 / 联调）​

四种方式对照​

接入后自检​