# iOS 推送接入指南

**模块**：`XuqmPush` · **支持**：APNs（默认）、FCM（可选）

---

## 1. 添加依赖

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

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

如需 FCM 支持，额外在 Xcode 中集成 `FirebaseMessaging`。

---

## 2. 申请通知权限

在应用启动时请求用户授权：

```swift
import XuqmPush

let granted = try await PushSDK.shared.requestAuthorization(options: [.alert, .badge, .sound])
if granted {
    print("用户已授权通知")
}
```

`requestAuthorization` 内部会自动调用 `UIApplication.shared.registerForRemoteNotifications()`，无需额外处理。

---

## 3. 注册 APNs Token

在 `AppDelegate` 中转发系统回调：

```swift
import XuqmSDK

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    // 将 deviceToken 转发生给 SDK
    XuqmSDK.shared.registerDeviceToken(deviceToken)
}

func application(
    _ application: UIApplication,
    didFailToRegisterForRemoteNotificationsWithError error: Error
) {
    print("注册远程通知失败: \(error.localizedDescription)")
}
```

> `XuqmSDK.shared.login()` 成功后会自动将 APNs Token 上报到 Push 服务端，业务层无需手动调用 `PushSDK.shared.registerDeviceToken()`。

---

## 4. FCM 支持（可选）

如需集成 Firebase Cloud Messaging：

1. 在 Xcode 中添加 `FirebaseMessaging` 依赖
2. 配置 `GoogleService-Info.plist`
3. 在获取到 FCM Token 后手动注册：

```swift
import XuqmPush

// 在 Firebase Messaging 回调中获取 FCM Token
func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
    guard let token = fcmToken else { return }
    try await PushSDK.shared.registerFcmToken(token, userId: "user_001")
}
```

可通过 `PushSDK.shared.isFcmAvailable` 检查当前是否编译了 FCM：

```swift
if PushSDK.shared.isFcmAvailable {
    print("FCM 模块已集成")
}
```

---

## 5. 接收推送消息

实现 `PushMessageDelegate` 处理推送消息：

```swift
import XuqmPush

class MyPushHandler: NSObject, PushMessageDelegate {
    func pushSDK(_ sdk: PushSDK, didReceiveMessage message: PushMessage) {
        // 应用在前台时收到通知
        print("收到推送: \(message.title ?? "") - \(message.body ?? "")")
        print("Payload: \(message.payload)")
    }
    
    func pushSDK(_ sdk: PushSDK, didTapNotification message: PushMessage) {
        // 用户点击通知栏消息
        print("用户点击了通知: \(message.title ?? "")")
        // 可在此跳转至对应会话页面
    }
}

// 设置代理
PushSDK.shared.delegate = MyPushHandler()
```

`PushSDK` 内部已实现 `UNUserNotificationCenterDelegate`，会自动处理前台展示和点击事件。业务层只需设置 `delegate` 即可接收回调。

---

## 6. 多模块统一登录

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

```swift
// 登录成功后自动触发
try await XuqmSDK.shared.login(userId: "user_001", userSig: userSig)
// ↓ 自动触发
//   · PushSDK 注册 APNs Token 并上报
```

---

## 7. 登出时注销 Token

```swift
try await PushSDK.shared.unregisterToken(userId: "user_001")
```