原生移动开发 / 系统课时
接入华为 HMS Push
接入华为 HMS Push
本篇完成一条可验证的 HMS Push 链路:配置 AppGallery Connect 与 HMS Push,在 Android 客户端取得 Push Token,再通过 HmsMessageService 接收消息或 Token 更新,并把 Token 同步到业务服务端。([华为开发者][1])
学习目标
- 能完成 HMS Push 的项目级基础配置与 SDK 接入
- 能获取并上报 Push Token
- 能处理消息回调与 Token 更新
配置项目与 SDK
先在 AppGallery Connect 中创建应用并启用 Push Kit,再将对应的 agconnect-services.json 放入 Android 应用模块。客户端依赖使用官方 HMS Push SDK;具体版本应以当前 HMS Core 文档提供的版本为准,不要硬编码过时版本。([华为开发者][2])
这是片段示例,依赖声明位置为应用模块的 dependencies。
// app/build.gradle:版本号以当前 HMS Core 文档为准
implementation 'com.huawei.hms:push:<PUSH_SDK_VERSION>'预期结果
Gradle sync 完成,项目可以解析 HMS Push SDK;<PUSH_SDK_VERSION> 替换为官方当前可用版本。注册消息服务
HMS Push 的消息和 Token 回调可以由继承 HmsMessageService 的服务接收。服务必须声明在 AndroidManifest.xml 中;onNewToken 用于处理首次或后续 Token 更新,onMessageReceived 用于接收下行消息。([华为开发者][3])

下面是核心服务定义的片段示例。
package com.example.push;
import android.util.Log;
import com.huawei.hms.push.HmsMessageService;
import com.huawei.hms.push.RemoteMessage;
public class AppPushService extends HmsMessageService {
private static final String TAG = "AppPushService";
@Override
public void onNewToken(String token) {
super.onNewToken(token);
// Token 变化后重新登记,服务端不要假设旧 Token 永久有效。
Log.d(TAG, "push token updated: " + token);
reportTokenToServer(token);
}
@Override
public void onMessageReceived(RemoteMessage message) {
super.onMessageReceived(message);
Log.d(TAG, "push message received");
// 这里进入业务分发,不应把耗时操作直接堆在回调中。
}
private void reportTokenToServer(String token) {
// 片段示例:实际项目应调用自己的 HTTPS API。
}
}预期结果
客户端可以编译通过;服务注册后,Token 更新进入 onNewToken,收到下行消息时进入 onMessageReceived。获取 Token 并上报
HMS 官方文档说明,应用可以通过 HmsInstanceId 获取 Push Token;若当前请求没有立即返回,也可能随后通过 onNewToken 得到。Token 与应用标识相关,获取后应交给自己的服务端保存,用于后续推送。不要在后台高频重复请求 Token。([华为开发者][1])
片段示例:
import android.os.Bundle;
import android.util.Log;
import com.huawei.hms.common.ApiException;
import com.huawei.hms.push.HmsInstanceId;
public void requestPushToken(String appId) {
try {
String token = HmsInstanceId.getInstance(this)
.getToken(appId, "HCM");
if (token != null && !token.isEmpty()) {
Log.d("Push", "token received");
reportTokenToServer(token);
}
} catch (ApiException e) {
Log.e("Push", "getToken failed: " + e.getMessage(), e);
}
}预期结果
成功时得到非空 Push Token,并进入 reportTokenToServer;失败时出现可定位的 HMS API 异常日志。处理接入中的常见问题
先确认 AppGallery Connect 中 Push Kit 已启用,再确认 agconnect-services.json 与当前应用包名、项目配置对应。Token 为空时优先检查初始化、App ID 与 HMS Core 环境,而不是立即反复调用 getToken。([华为开发者][1])
还要把“拿到 Token”和“消息能到达”分开验证:前者证明注册链路工作,后者还需要服务端发送链路、消息类型以及设备侧接收逻辑共同成立。