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

# iOS 版本更新接入指南

**模块**：`XuqmUpdate` · **功能**：App 版本检查、App Store 跳转

---

## 1. 添加依赖

在 `Package.swift` 中按需引入：

```swift
.target(
    name: "MyApp",
    dependencies: [
        .product(name: "XuqmUpdate", package: "XuqmGroup-iOSSDK"),
    ]
)
```

---

## 2. 检查更新

```swift
import XuqmUpdate

let appInfo = try await UpdateSDK.shared.checkAppUpdate(currentVersionCode: 1)
if let info = appInfo, info.needsUpdate {
    print("发现新版本: \(info.versionName ?? "")")
    print("更新日志: \(info.changeLog ?? "")")
    
    if info.forceUpdate == true {
        // 强制更新
        showForceUpdateAlert(info)
    } else {
        // 可选更新
        showOptionalUpdateAlert(info)
    }
}
```

---

## 3. 跳转 App Store

```swift
if let url = appInfo?.appStoreUrl {
    UpdateSDK.shared.openAppStore(url: url)
}
```

`openAppStore` 会调用 `UIApplication.shared.open()` 打开 App Store 页面，引导用户前往商店更新。

---

## 4. 强制更新处理

当服务端返回 `forceUpdate = true` 时，建议业务层：

1. 弹出 `UIAlertController`，设置 `isUserInteractionEnabled = false` 禁止关闭
2. 只允许用户点击「前往更新」
3. 调用 `UpdateSDK.shared.openAppStore(url:)` 跳转 App Store

```swift
func showForceUpdateAlert(_ info: AppUpdateInfo) {
    let alert = UIAlertController(
        title: "发现重要更新",
        message: "当前版本已不可用，请升级至 \(info.versionName ?? "最新版")",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(title: "前往更新", style: .default) { _ in
        if let url = info.appStoreUrl ?? info.downloadUrl {
            UpdateSDK.shared.openAppStore(url: url)
        }
    })
    present(alert, animated: true)
}
```

---

## 5. 多模块统一登录

Update 模块与 IM、Push 模块共享同一套登录态：

```swift
// 初始化
XuqmSDK.shared.initialize(config: config)

// 登录（业务登录成功后调用一次）
try await XuqmSDK.shared.login(userId: "user_001", userSig: userSig)
// UpdateSDK 在 checkAppUpdate 时自动携带 appKey，无需额外登录操作
```

---

## 6. 一键打包上传

SDK 提供 Fastlane `xuqm_release` lane，可一键完成 Archive、导出并上传至 XuqmGroup 版本管理服务：

```bash
fastlane xuqm_release
```

`Fastfile` 示例配置：

```ruby
lane :xuqm_release do
  gym(
    scheme: "MyApp",
    export_method: "app-store",
    output_directory: "build"
  )
  
  xuqm_upload(
    ipa_path: "build/MyApp.ipa",
    release_notes: File.read("CHANGELOG.md"),
    force_update: false
  )
end
```

任务执行流程：
1. 执行 `gym` 构建 Release IPA
2. 自动提取版本号、build 号、更新日志
3. 上传 IPA 到 XuqmGroup 后台
4. 返回发布结果