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. 添加依赖

// 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：

<!-- 小米 -->
<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() 中调用：

PushSDK.initializeVendors(context)

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

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

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

---

4. 手动上报 Token

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

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

// 小米示例
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)
        }
    }
}

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

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

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

// 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. 开启或关闭推送

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

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

---

7. 多模块统一登录

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

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

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