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

```groovy
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：

```xml
<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` 中添加：

```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. 在 [华为开发者联盟](https://developer.huawei.com/) 创建应用
2. 下载 `agconnect-services.json`
3. 放置到 `android/app/` 目录

### 1.4 Google FCM 配置

FCM 需要 `google-services.json` 文件：

1. 在 [Firebase Console](https://console.firebase.google.com/) 创建项目
2. 下载 `google-services.json`
3. 放置到 `android/app/` 目录
4. 确保 `android/build.gradle` 添加了 Google Services 插件：

```groovy
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 依赖。

```objective-c
// 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 检查厂商检测

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

### 5.2 检查 Token 注册

```typescript
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 配置 |