XuqmGroup-Web/docs-site/docs/android/push.md

# Android 推送接入指南

**模块**：`com.xuqm:sdk-push` · **支持厂商**：华为、小米、OPPO、vivo、荣耀、FCM

SDK 在 `XuqmSDK.login()` 成功后会自动检测手机厂商、初始化对应 Push SDK、获取 Token 并上报到 Push 服务端。业务层**无需手动调用**任何 Push 注册 API。

如需主动控制，可参考以下独立接入方式。

---

## 1. 添加依赖

```kotlin
// app/build.gradle.kts
dependencies {
    implementation("com.xuqm:sdk-push:0.4.0")
}
```

各厂商需要额外添加对应 Push SDK 依赖（按需）：

| 厂商 | 依赖 |
|------|------|
| 华为 | `com.huawei.hms:push:6.x.x.xxx` |
| 小米 | `com.xiaomi.mipush:mipush:5.x.x` |
| OPPO | `com.heytap.mcs:push:3.x.x` |
| vivo | `com.vivo.pushsdk:pushsdk:3.x.x` |
| 荣耀 | `com.hihonor.mcs:push:7.x.x.xxx` |
| FCM | `com.google.firebase:firebase-messaging` |

---

## 2. AndroidManifest.xml 配置

在 `<application>` 下添加各厂商对应的 `meta-data`：

```xml
<!-- 小米 -->
<meta-data android:name="XUQM_XIAOMI_APP_ID"
           android:value="288230376xxxxxxxx" />
<meta-data android:name="XUQM_XIAOMI_APP_KEY"
           android:value="xxxxxxxxxxxx" />

<!-- OPPO -->
<meta-data android:name="XUQM_OPPO_APP_KEY"
           android:value="xxxxxxxx" />
<meta-data android:name="XUQM_OPPO_APP_SECRET"
           android:value="xxxxxxxx" />
```

> 华为、荣耀、vivo、FCM 无需在 `AndroidManifest.xml` 中配置 `meta-data`，其配置方式如下：
> - **华为**：通过 `agconnect-services.json` 自动读取 `app_id`
> - **荣耀**：在 `Application.onCreate()` 中调用 `HonorPushClient.getInstance().init(context, true)`
> - **vivo**：在 `Application.onCreate()` 中调用 `PushClient.getInstance(context).initialize()`
> - **FCM**：通过 `google-services.json` 自动集成

---

## 3. 初始化

在 `Application.onCreate()` 中调用：

```kotlin
PushSDK.initializeVendors(context)
```

SDK 会自动检测当前设备厂商（`HUAWEI / XIAOMI / OPPO / VIVO / HONOR / FCM`），并初始化对应的推送服务。

如需查询当前检测到的厂商：

```kotlin
val vendor = PushSDK.detectVendor()
// 返回：HUAWEI / XIAOMI / OPPO / VIVO / HONOR / FCM
```

---

## 4. 手动上报 Token

如果业务层自定义了厂商推送服务（如自定义 `HmsMessageService`、`MiPushMessageReceiver` 等），需在收到 Token 回调后手动上报：

```kotlin
// 华为 HMS 示例
class MyHmsService : HmsMessageService() {
    override fun onNewToken(token: String) {
        super.onNewToken(token)
        PushSDK.updateNativePushToken(context, PushVendor.HUAWEI, token)
    }
}
```

```kotlin
// 小米示例
class MyMiPushReceiver : PushMessageReceiver() {
    override fun onReceiveRegisterResult(context: Context, miPushCommandMessage: MiPushCommandMessage) {
        val token = miPushCommandMessage.commandArguments?.getOrNull(0)
        if (!token.isNullOrBlank()) {
            PushSDK.updateNativePushToken(context, PushVendor.XIAOMI, token)
        }
    }
}
```

```kotlin
// OPPO 示例（在 PushCallback.onRegister 中）
PushSDK.updateNativePushToken(context, PushVendor.OPPO, regId)
```

```kotlin
// vivo 示例（在 OpenClientPushMessageReceiver.onReceiveRegId 中）
PushSDK.updateNativePushToken(context, PushVendor.VIVO, regId)
```

```kotlin
// 荣耀示例（在 HonorMessageService.onNewToken 中）
PushSDK.updateNativePushToken(context, PushVendor.HONOR, token)
```

```kotlin
// FCM 示例（在 FirebaseMessagingService.onNewToken 中）
class MyFcmService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        super.onNewToken(token)
        PushSDK.updateNativePushToken(this, PushVendor.FCM, token)
    }
}
```

---

## 5. 接收推送消息

各厂商推送消息通过各自的 SDK 回调接收，SDK 不负责解析消息内容，业务层需自行实现：

- **华为**：`HmsMessageService.onMessageReceived(RemoteMessage)`
- **小米**：`PushMessageReceiver.onReceivePassThroughMessage()` / `onNotificationMessageClicked()`
- **OPPO**：`PushCallback.onGetPushMessage()`
- **vivo**：`OpenClientPushMessageReceiver.onTransmissionMessage()`
- **荣耀**：`HonorMessageService.onMessageReceived()`
- **FCM**：`FirebaseMessagingService.onMessageReceived(RemoteMessage)`

> 建议在收到推送消息后，调用业务层的通知管理器展示本地通知，或跳转至对应会话页面。

---

## 6. 开启或关闭推送

```kotlin
// 关闭推送接收
PushSDK.setReceivePush(context, enabled = false)

// 开启推送接收
PushSDK.setReceivePush(context, enabled = true)
```

---

## 7. 多模块统一登录

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

```kotlin
// 登录成功后自动触发
XuqmSDK.login(userId = "user_001", userSig = "jwt_token")
// ↓ 自动触发
//   · PushSDK.onSdkLogin → 初始化厂商 Push 并注册 Token
```

无需业务层手动调用 `PushSDK.initializeVendors()` 或 `bindImUser()`。