XuqmGroup-RNSDK/docs/PushSDK-厂商集成.md

PushSDK Android 厂商推送集成指南

最后更新：2026-06-15

---

概述

PushSDK 支持 Android 多厂商推送 SDK，通过反射机制自动检测设备厂商并调用对应的推送注册 API。宿主应用只需配置 AndroidManifest.xml 中的 meta-data，无需编写额外的 Java/Kotlin 代码。

支持的厂商：

厂商	SDK	自动检测条件
华为	HMS Push (HmsInstanceId)	Build.MANUFACTURER == "HUAWEI"
小米	MiPush (MiPushClient)	Build.MANUFACTURER == "XIAOMI" | "REDMI"
OPPO	Heytap Push (PushManager)	Build.MANUFACTURER == "OPPO" | "REALME"
vivo	PushClient	Build.MANUFACTURER == "VIVO" | "IQOO"
荣耀	HonorPush	Build.MANUFACTURER == "HONOR"
Google	FCM (FirebaseMessaging)	其他厂商
Apple	APNs	iOS 自动

---

一、集成步骤

1.1 添加依赖

宿主应用的 android/app/build.gradle：

dependencies {
    // 华为 HMS Push（可选）
    implementation 'com.huawei.hms:push:6.12.0.300'
    
    // 小米 MiPush（可选）
    implementation 'com.xiaomi.mipush:mipush-sdk:5.9.9'
    
    // OPPO Heytap Push（可选）
    implementation 'com.heytap.mcssdk:mcssdk:3.0.2'
    
    // vivo Push（可选）
    implementation 'com.vivo.push:push:3.0.0.4'
    
    // 荣耀 Push（可选）
    implementation 'com.hihonor.push:honor-push:7.0.3.300'
    
    // Google FCM（推荐作为兜底）
    implementation 'com.google.firebase:firebase-messaging:23.4.0'
}

注意：只需添加目标设备对应的依赖。PushSDK 通过反射调用，不添加对应依赖时该厂商注册会静默跳过。

1.2 配置 AndroidManifest.xml

在 android/app/src/main/AndroidManifest.xml 的 <application> 标签内添加 meta-data：

<application>
    <!-- 小米 MiPush -->
    <meta-data
        android:name="XUQM_XIAOMI_APP_ID"
        android:value="@string/xiaomi_app_id" />
    <meta-data
        android:name="XUQM_XIAOMI_APP_KEY"
        android:value="@string/xiaomi_app_key" />
    
    <!-- OPPO Heytap Push -->
    <meta-data
        android:name="XUQM_OPPO_APP_KEY"
        android:value="@string/oppo_app_key" />
    <meta-data
        android:name="XUQM_OPPO_APP_SECRET"
        android:value="@string/oppo_app_secret" />
    
    <!-- 华为 HMS Push（从 agconnect-services.json 自动读取，无需额外配置） -->
    
    <!-- vivo Push（从 AndroidManifest 自动读取，无需额外配置） -->
    
    <!-- 荣耀 Push（从 AndroidManifest 自动读取，无需额外配置） -->
    
    <!-- FCM（从 google-services.json 自动读取，无需额外配置） -->
</application>

在 android/app/src/main/res/values/strings.xml 中添加：

<resources>
    <!-- 小米 -->
    <string name="xiaomi_app_id">YOUR_XIAOMI_APP_ID</string>
    <string name="xiaomi_app_key">YOUR_XIAOMI_APP_KEY</string>
    
    <!-- OPPO -->
    <string name="oppo_app_key">YOUR_OPPO_APP_KEY</string>
    <string name="oppo_app_secret">YOUR_OPPO_APP_SECRET</string>
</resources>

1.3 华为 HMS 配置

华为推送需要 agconnect-services.json 文件：

1. 在 华为开发者联盟 创建应用
2. 下载 agconnect-services.json
3. 放置到 android/app/ 目录

1.4 Google FCM 配置

FCM 需要 google-services.json 文件：

1. 在 Firebase Console 创建项目
2. 下载 google-services.json
3. 放置到 android/app/ 目录
4. 确保 android/build.gradle 添加了 Google Services 插件：

buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.4.0'
    }
}

---

二、工作流程

App 启动
  → PushSDK.onPushToken(callback)    ← 注册监听器
  → PushSDK.requestNativeRegistration()
    → XuqmPushModule.registerPush()
      → 检测厂商 (detectVendor)
      → 调用对应厂商 SDK 注册
      → 厂商 SDK 返回 token
      → emitToken(token, vendor)     ← 通过事件发送给 JS
  → callback(token, vendor) 被调用
    → PushSDK.setDeviceToken(token, vendor)
      → 注册到服务器

用户登录
  → PushSDK.initialize(userId)
    → 将 pending token 绑定到 userId

用户登出
  → PushSDK.logout(userId)
    → 从服务器注销 token

---

三、厂商 SDK 详细说明

3.1 华为 HMS Push

注册方式：HmsInstanceId.getInstance(context).getToken(appId, "HCM")

AppID 来源：AGConnectServicesConfig.fromContext(context).getString("client/app_id")

Token 事件：HMS 6.x 版本 token 通过 getToken() 同步返回。如果返回空，需要实现 HmsMessageService.onNewToken() 异步接收。

ProGuard 规则：

-keep class com.huawei.hms.** { *; }
-dontwarn com.huawei.hms.**

3.2 小米 MiPush

注册方式：MiPushClient.registerPush(context, appId, appKey)

配置来源：AndroidManifest.xml 中的 XUQM_XIAOMI_APP_ID 和 XUQM_XIAOMI_APP_KEY

Token 事件：通过 MiPushMessageReceiver.onReceiveRegisterResult() 回调。PushSDK 通过反射监听。

ProGuard 规则：

-keep class com.xiaomi.mipush.** { *; }
-dontwarn com.xiaomi.mipush.**

3.3 OPPO Heytap Push

注册方式：PushManager.getInstance().register(context, appKey, appSecret, pushCallback)

配置来源：AndroidManifest.xml 中的 XUQM_OPPO_APP_KEY 和 XUQM_OPPO_APP_SECRET

Token 事件：通过 PushCallback.onRegister(regId) 回调。PushSDK 使用 Proxy.newProxyInstance 动态代理。

ProGuard 规则：

-keep class com.heytap.mcssdk.** { *; }
-dontwarn com.heytap.mcssdk.**

3.4 vivo Push

注册方式：PushClient.getInstance().initialize(context)

配置来源：AndroidManifest.xml 中的 com.vivo.push.api_key 和 com.vivo.push.app_id

Token 事件：通过 PushClientReceiver.onReceiveRegId() 回调。

ProGuard 规则：

-keep class com.vivo.push.** { *; }
-dontwarn com.vivo.push.**

3.5 荣耀 Honor Push

注册方式：HonorPushClient.getInstance().getToken()

配置来源：AndroidManifest.xml 中的 com.hihonor.push.app_id

Token 事件：通过 HonorPushService.onNewToken() 回调。

ProGuard 规则：

-keep class com.hihonor.push.** { *; }
-dontwarn com.hihonor.push.**

3.6 Google FCM

注册方式：FirebaseMessaging.getInstance().getToken()

配置来源：google-services.json

Token 事件：通过 FirebaseMessagingService.onNewToken() 回调。

ProGuard 规则：

-keep class com.google.firebase.** { *; }
-dontwarn com.google.firebase.**

---

四、iOS APNs 配置

iOS 推送使用原生 APNs，无需额外 SDK 依赖。

// ios/YourApp/AppDelegate.mm
#import <UserNotifications/UserNotifications.h>

- (void)application:(UIApplication *)application
    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    // PushSDK 自动处理
}

在 Xcode 中：

1. 打开 Capabilities → Push Notifications
2. 启用 Push Notifications
3. 配置 APNs Auth Key（在 Apple Developer Portal）

---

五、调试

5.1 检查厂商检测

import { PushSDK } from '@xuqm/rn-push';
// 或通过 NativeModules
const vendor = await NativeModules.XuqmPushModule.detectVendor();
console.log('Detected vendor:', vendor);

5.2 检查 Token 注册

PushSDK.onPushToken((token, vendor) => {
  console.log('Push token:', token);
  console.log('Vendor:', vendor);
});

await PushSDK.requestNativeRegistration();

5.3 常见问题

问题	原因	解决方案
Token 为空	厂商 SDK 未正确配置	检查 meta-data / json 文件
注册失败	网络问题或 SDK 版本不兼容	检查 Logcat 错误日志
华为 token 获取失败	HMS Core 版本过低	更新 HMS Core 到最新版
小米注册无反应	appId/appKey 错误	检查 strings.xml 配置