本文详细介绍如何在 android 客户端代码中，使用 firebase cloud messaging（fcm）api 向单个设备（基于注册 token）安全、可靠地发送推送通知，涵盖请求构造、http 客户端配置、json 体格式及关键注意事项。
本文详细介绍如何在 android 客户端代码中，使用 firebase cloud messaging（fcm）api 向单个设备（基于注册 token）安全、可靠地发送推送通知，涵盖请求构造、http 客户端配置、json 体格式及关键注意事项。
在 Android 应用中实现服务端能力（如直接调用 FCM 发送通知）需格外注意：FCM 的 https://fcm.googleapis.com/fcm/send 接口属于服务端 API，应由可信后端（如 Node.js/Python/Java 服务）调用；若因调试或原型开发需要在 Android 客户端临时发起请求，必须严格规避密钥硬编码与主线程阻塞，并仅用于学习验证——生产环境严禁将 Server Key 植入客户端 APK。
以下为符合现代 Android 开发规范的客户端调用示例（基于 OkHttp），适用于测试场景：
✅ 正确实现：使用 OkHttp 异步发送 FCM 消息
首先，在 app/build.gradle 中添加依赖（推荐 OkHttp 而非过时的 Apache HttpClient）：
implementation 'com.squareup.okhttp3:okhttp:4.12.0'
然后，封装一个安全的发送方法（务必在后台线程执行）：
private void sendFcmNotification(String targetToken, String serverKey) {
// ⚠️ 生产中 serverKey 必须由后端提供，绝不可写死或泄露
String url = "https://fcm.googleapis.com/fcm/send";
// 构建 JSON 请求体：支持 notification（系统弹窗）和 data（静默数据）字段
String jsonPayload = String.format(
"{\n" +
" \"to\": \"%s\",\n" +
" \"notification\": {\n" +
" \"title\": \"Hello from Android\",\n" +
" \"body\": \"This is a test push notification.\"\n" +
" },\n" +
" \"data\": {\n" +
" \"click_action\": \"FLUTTER_NOTIFICATION_CLICK\",\n" +
" \"custom_key\": \"custom_value\"\n" +
" }\n" +
"}",
targetToken
);
OkHttpClient client = new OkHttpClient();
RequestBody body = RequestBody.create(
jsonPayload,
MediaType.get("application/json; charset=utf-8")
);
Request request = new Request.Builder()
.url(url)
.post(body)
.addHeader("Authorization", "key=" + serverKey) // ✅ 使用 Server Key（Legacy HTTP API）
.addHeader("Content-Type", "application/json")
.build();
// 异步执行，避免 ANR
client.newCall(request).enqueue(new Callback() {
@Override
public void onFailure(Call call, IOException e) {
Log.e("FCM_SEND", "Request failed", e);
}
@Override
public void onResponse(Call call, Response response) throws IOException {
if (response.isSuccessful()) {
String result = response.body().string();
Log.d("FCM_SEND", "Success: " + result);
} else {
Log.e("FCM_SEND", "Error: " + response.code() + " " + response.message());
}
}
});
}
⚠️ 关键注意事项
密钥安全：serverKey 是高危凭证，对应 Firebase 项目设置中的 Server key（位于 Firebase Console → Project Settings → Cloud Messaging）。绝对不可硬编码在客户端代码中，也不可提交至 Git。调试时建议通过本地配置文件（.gitignore 排除）或环境变量注入。
API 版本选择：上述示例使用的是 Legacy HTTP API（/fcm/send），已标记为 deprecated。生产环境应迁移至 FCM HTTP v1 API（需 OAuth 2.0 认证 + Access Token），安全性更高、功能更全（如主题/条件发送、消息优先级控制等）。
Token 有效性：FCM Token 可能因应用重装、系统清理或用户禁用通知而失效。发送前建议服务端维护 Token 状态（通过 FCM 响应中的 "error": "InvalidRegistration" 或 "NotRegistered" 判断并清理）。
-
网络与权限：确保 AndroidManifest.xml 中已声明互联网权限：
<uses-permission android:name="android.permission.INTERNET"></uses-permission>
替代方案推荐：对于真实业务场景，强烈建议将推送逻辑移至自有服务器。客户端仅负责上报 Token，由后端统一管理设备、构建消息、调用 FCM v1 API，并处理失败重试、日志审计与用户行为联动。
✅ 总结
虽然技术上可在 Android 客户端直接调用 FCM 接口，但其本质是服务端行为。本文提供的 OkHttp 示例仅作原理演示与快速验证之用。真正的健壮推送系统，应遵循「客户端轻量上报、服务端集中调度」的设计原则——既保障安全合规，也便于灰度发布、A/B 测试与全链路监控。
