简介本资源是一份面向Android应用开发者与物联网初学者的MQTT消息推送实战示例聚焦在移动终端实现轻量级远程通信的核心能力——连接MQTT服务器、订阅主题、接收消息并实时展示于系统通知栏。项目基于Eclipse Paho Android客户端库构建已集成完整服务生命周期管理、断线自动重连、消息回调处理及NotificationCompat通知封装逻辑可直接编译运行或作为模块嵌入现有工程。压缩包共607个文件含134个flat资源、121个json配置、188个xml布局与清单文件、8个核心Java业务类及APK安装包等结构清晰便于理解Android后台服务与MQTT协议协同机制整体大小为15.58MB。已有1142人学习下载提供开箱即用的可运行代码框架、关键注释说明及典型错误处理范式助开发者快速掌握物联网消息推送落地的关键链路。1. Android端MQTT消息推送落地从连接服务器、订阅主题到通知栏实时显示为什么90%的初学者卡在权限配置和后台保活在某高校物联网课程设计中A同学花三天时间跑通了MQTT服务器通信却始终收不到通知栏提醒——不是代码没写而是NotificationChannel未创建、ForegroundService未启动、AndroidManifest.xml里漏了uses-permission android:nameandroid.permission.POST_NOTIFICATIONS /Android 13强制要求。这并非个例实际项目中MQTT客户端能连上、能收包、但消息“静默消失”根本原因往往不在协议栈而在Android系统级行为约束。本文聚焦一个最小可运行闭环用Eclipse Paho Android Client连接公开MQTT测试服务器如broker.hivemq.com:1883订阅指定主题如test/android收到消息后立即在通知栏弹出带图标、渠道、点击跳转Activity的完整通知。不依赖任何第三方推送SDK纯原生实现覆盖Android 8.0Oreo至14UpsideDownCake全版本适配要点。适合正在做毕业设计、IoT设备配套App或需要轻量级消息通道的开发者——你不需要懂MQTT协议细节但必须清楚Android如何“允许”一条消息从网络层抵达用户眼前。2. 环境准备与依赖接入选Paho而非MQTTX SDK因为它的轻量性与可控性更适配通知场景2.1 为什么是Eclipse Paho Android Client不是Mosquitto Java版也不是自研Netty封装MQTT客户端库在Android生态有三类主流选择Mosquitto官方Java绑定需JNI编译APK体积膨胀明显且对Android生命周期无感知自研基于OkHttp/Netty的MQTT over WebSocket灵活性高但重试逻辑、离线缓存、QoS 1/2状态管理极易出错Eclipse Paho Android Client专为Android优化内置MqttAndroidClient自动处理主线程调用阻塞、后台服务绑定、广播接收器注册等胶水逻辑且支持setCallback()回调直接在主线程更新UI——这对通知栏触发至关重要。提示Paho Android Client已停止维护最后更新2021年但其稳定性和API简洁性仍远超多数新库。我们使用org.eclipse.paho:org.eclipse.paho.android.service:1.1.1该版本兼容AndroidX且无反射报错风险。2.2 Gradle依赖与混淆规则配置含AndroidX迁移关键项在模块级build.gradle中添加dependencies { implementation org.eclipse.paho:org.eclipse.paho.android.service:1.1.1 implementation androidx.core:core:1.12.0 // 必须≥1.10.0否则NotificationCompat.Builder构造失败 implementation androidx.work:work-runtime-ktx:2.9.0 // 后台任务保活基础 }若启用ProGuard/R8混淆必须保留Paho核心类否则MqttAndroidClient初始化时抛ClassNotFoundException# Paho MQTT for Android -keep class org.eclipse.paho.client.mqttv3.** { *; } -keep class org.eclipse.paho.android.service.** { *; } -dontwarn org.eclipse.paho.client.mqttv3.**2.3 权限声明从Android 6.0到14的渐进式适配清单AndroidManifest.xml中需声明以下权限按最低目标版本动态增减!-- 基础网络 -- uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE / !-- 通知栏必备Android 8.0强制渠道 -- uses-permission android:nameandroid.permission.POST_NOTIFICATIONS / !-- 后台保活Android 9限制前台服务需显式声明 -- uses-permission android:nameandroid.permission.FOREGROUND_SERVICE / !-- 可选WiFi状态监听用于网络切换时重连 -- uses-permission android:nameandroid.permission.ACCESS_WIFI_STATE /注意POST_NOTIFICATIONS权限在Android 13API 33起为运行时权限必须在首次订阅前动态申请而FOREGROUND_SERVICE是安装时权限无需运行时请求但必须在service标签中显式声明android:foregroundServiceType属性见3.2节。3. 核心代码实现从MQTT连接、主题订阅到通知构建的四步链路3.1 初始化MqttAndroidClient并建立连接用connectOptions控制超时与心跳private MqttAndroidClient mqttClient; private String brokerUrl tcp://broker.hivemq.com:1883; // 公共测试Broker无认证 private String clientId android_ System.currentTimeMillis(); // 唯一客户端ID private void initMqttClient() { mqttClient new MqttAndroidClient(this.getApplicationContext(), brokerUrl, clientId); MqttConnectOptions options new MqttConnectOptions(); options.setCleanSession(true); // 设为true断开后丢弃服务器未投递消息false则保留QoS1/2消息 options.setConnectionTimeout(30); // 单位秒避免Connect阻塞过久 options.setKeepAliveInterval(60); // 心跳间隔单位秒低于30秒可能被某些Broker拒绝 try { IMqttToken token mqttClient.connect(options); token.setActionCallback(new IMqttActionListener() { Override public void onSuccess(IMqttToken asyncActionToken) { Log.d(MQTT, Connected to broker); subscribeToTopic(test/android); // 连接成功后立即订阅 } Override public void onFailure(IMqttToken asyncActionToken, Throwable exception) { Log.e(MQTT, Connection failed, exception); // 此处应加入指数退避重连逻辑见4.1节 } }); } catch (MqttException e) { Log.e(MQTT, MqttException on connect, e); } }参数说明cleanSessiontrue是通知场景推荐值用户关闭App后不期望收到历史消息避免通知堆积connectionTimeout30防止弱网下connect()卡死主线程keepAliveInterval60是HiveMQ公共Broker接受的最大值设为120会返回CONNECTION_REFUSED。3.2 创建前台服务承载MQTT长连接解决Android 9后台执行限制Android 9Pie起禁止应用在后台启动ServiceMQTT必须运行在前台服务中。新建MqttForegroundService.javapublic class MqttForegroundService extends Service { private static final int NOTIFICATION_ID 1001; private MqttAndroidClient mqttClient; Override public void onCreate() { super.onCreate(); createNotificationChannel(); // 必须先创建渠道否则startForeground失败 startForeground(NOTIFICATION_ID, buildForegroundNotification()); } Override public int onStartCommand(Intent intent, int flags, int startId) { // 初始化MQTT客户端复用Application单例或此处new initMqttClient(); return START_STICKY; // 系统内存不足杀掉后会尝试重启 } private void initMqttClient() { mqttClient new MqttAndroidClient(this, tcp://broker.hivemq.com:1883, svc_ System.currentTimeMillis()); mqttClient.setCallback(new MqttCallbackExtended() { Override public void connectComplete(boolean reconnect, String serverURI) { try { mqttClient.subscribe(test/android, 0); // QoS 0最多一次通知场景足够 } catch (MqttException e) { Log.e(MQTT-SVC, Subscribe failed, e); } } Override public void connectionLost(Throwable cause) { Log.w(MQTT-SVC, Connection lost, cause); // 触发重连见4.1节 } Override public void messageArrived(String topic, MqttMessage message) throws Exception { String payload new String(message.getPayload()); Log.d(MQTT-SVC, Received: payload); showNotification(topic, payload); // 关键收到即通知 } Override public void deliveryComplete(IMqttDeliveryToken token) {} }); } private void showNotification(String topic, String content) { Intent intent new Intent(this, MainActivity.class); intent.putExtra(topic, topic); intent.putExtra(content, content); intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK); PendingIntent pendingIntent PendingIntent.getActivity(this, 0, intent, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_ONE_SHOT); NotificationCompat.Builder builder new NotificationCompat.Builder(this, mqtt_channel) .setSmallIcon(R.drawable.ic_notification) // 必须是alpha通道清晰的白底图标 .setContentTitle(MQTT消息) .setContentText(content) .setPriority(NotificationCompat.PRIORITY_HIGH) .setAutoCancel(true) .setContentIntent(pendingIntent) .setStyle(new NotificationCompat.DecoratedCustomViewStyle()); NotificationManagerCompat notificationManager NotificationManagerCompat.from(this); notificationManager.notify(System.currentTimeMillis(), builder.build()); } private void createNotificationChannel() { if (Build.VERSION.SDK_INT Build.VERSION_CODES.O) { CharSequence name MQTT消息通道; String description 接收设备状态、告警等实时通知; int importance NotificationManager.IMPORTANCE_HIGH; NotificationChannel channel new NotificationChannel(mqtt_channel, name, importance); channel.setDescription(description); channel.enableLights(true); channel.setLightColor(Color.RED); channel.enableVibration(true); NotificationManager notificationManager getSystemService(NotificationManager.class); notificationManager.createNotificationChannel(channel); } } private Notification buildForegroundNotification() { Intent notificationIntent new Intent(this, MainActivity.class); PendingIntent pendingIntent PendingIntent.getActivity(this, 0, notificationIntent, PendingIntent.FLAG_IMMUTABLE); return new NotificationCompat.Builder(this, mqtt_channel) .setContentTitle(MQTT服务运行中) .setContentText(正在监听主题test/android) .setSmallIcon(R.drawable.ic_service) .setContentIntent(pendingIntent) .build(); } Override public IBinder onBind(Intent intent) { return null; } }关键点说明startForeground()必须在onCreate()中调用且NotificationChannel必须提前创建PendingIntent.FLAG_IMMUTABLE是Android 12强制要求否则getActivity()抛异常R.drawable.ic_notification图标尺寸必须为24×24 dp且背景透明系统会自动染色为白色START_STICKY并非100%保证服务存活需配合JobIntentService或WorkManager做兜底见4.2节。3.3 在Activity中启动服务并处理通知点击解耦UI与后台逻辑在MainActivity.java的onCreate()中启动服务Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // 检查并申请通知权限Android 13 if (Build.VERSION.SDK_INT Build.VERSION_CODES.TIRAMISU) { if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ! PackageManager.PERMISSION_GRANTED) { ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.POST_NOTIFICATIONS}, 100); } } // 启动MQTT前台服务 Intent serviceIntent new Intent(this, MqttForegroundService.class); if (Build.VERSION.SDK_INT Build.VERSION_CODES.O) { startForegroundService(serviceIntent); } else { startService(serviceIntent); } } // 处理通知栏点击传入的数据 Override protected void onNewIntent(Intent intent) { super.onNewIntent(intent); if (intent.hasExtra(content)) { String content intent.getStringExtra(content); Toast.makeText(this, 收到消息 content, Toast.LENGTH_LONG).show(); } }注意onNewIntent()仅在launchModesingleTop或singleTask时生效务必在AndroidManifest.xml中为MainActivity设置activity android:name.MainActivity android:launchModesingleTop !-- 关键否则点击通知无法触发onNewIntent -- ... /4. 避坑指南Android MQTT通知场景最常踩的5个深坑及血泪修复方案4.1 现象MQTT连接成功但messageArrived()从不触发原因订阅主题时未指定QoS等级subscribe(topic, qos)第二个参数为0/1/2Paho默认QoS0但部分Broker如EMQX要求显式传参主题名含空格或特殊字符如test/ androidBroker拒绝订阅客户端ID重复同一clientId在多个设备登录后登录者踢掉前者导致旧连接失效。解决强制指定QoSmqttClient.subscribe(test/android, 0)主题名只用ASCII字母、数字、/、_、-clientId拼接设备唯一标识android_ Settings.Secure.getString(getContentResolver(), Settings.Secure.ANDROID_ID)。4.2 现象通知栏无反应Log显示NotificationManager: Ignoring notification原因NotificationChannel创建时importance设为IMPORTANCE_NONE或IMPORTANCE_MINsetSmallIcon()传入的资源ID不存在或不是drawable类型误用mipmapAndroid 12未设置setPriority()系统降级为低优先级。解决渠道重要性必须≥IMPORTANCE_DEFAULT推荐IMPORTANCE_HIGH图标资源放res/drawable/下命名如ic_notification.xmlVectorDrawable显式调用.setPriority(NotificationCompat.PRIORITY_HIGH)。4.3 现象App退到后台后10分钟内MQTT断连且不再自动重连原因Android 9限制后台应用的网络访问前台服务被系统回收MqttCallbackExtended.connectionLost()中未实现重连逻辑或重连未在主线程外执行导致ANR。解决在connectionLost()中启动HandlerThread执行重连new HandlerThread(MqttReconnect).start(); Handler reconnectHandler new Handler(reconnectThread.getLooper()); reconnectHandler.post(() - { try { mqttClient.connect(options); } catch (MqttException e) { /* 重试计数1指数退避 */ } });4.4 现象点击通知后Activity黑屏或闪退原因PendingIntent未设置FLAG_IMMUTABLEAndroid 12MainActivity未设置android:exportedtrueAndroid 12强制要求Intent携带的content字符串含不可见控制字符如\u202E解析时报BadParcelableException。解决PendingIntent.getActivity()必须加FLAG_IMMUTABLEAndroidManifest.xml中activity标签添加android:exportedtrue发送前对payload做TextUtils.htmlEncode()过滤。4.5 现象Android 14设备上通知完全不显示Log无错误原因Android 14API 34新增NotificationManager.canNotify()检查需在showNotification()前调用NotificationChannel未设置setSound()而用户系统设置中关闭了“无声通知”。解决if (Build.VERSION.SDK_INT Build.VERSION_CODES.UPSIDE_DOWN_CAKE) { if (!notificationManager.canNotify(mqtt_channel)) { // 引导用户去设置页开启通知 Intent intent new Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS) .putExtra(Settings.EXTRA_APP_PACKAGE, getPackageName()); startActivity(intent); return; } }5. 进阶技巧让MQTT通知真正可靠——离线消息缓存、多主题分级与点击归因追踪5.1 用Room数据库缓存离线消息避免网络抖动丢失关键通知当设备断网时MQTT Broker会根据QoS等级缓存消息但Android端若未及时处理messageArrived()消息将丢失。解决方案在messageArrived()中先存入本地数据库再构建通知。定义EntityEntity(tableName mqtt_message_cache) public class MqttMessageCache { PrimaryKey(autoGenerate true) public long id; public String topic; public String payload; public long timestamp; public boolean isRead; }在MqttForegroundService.messageArrived()中Override public void messageArrived(String topic, MqttMessage message) throws Exception { String payload new String(message.getPayload()); MqttMessageCache cache new MqttMessageCache(); cache.topic topic; cache.payload payload; cache.timestamp System.currentTimeMillis(); cache.isRead false; // 插入Room数据库异步 new InsertMessageAsyncTask(mqttDatabase.messageDao()).execute(cache); // 同时发通知不阻塞 showNotification(topic, payload); }优势用户打开App时可查询isReadfalse的消息列表实现“未读消息中心”即使通知被清除数据仍在。5.2 多主题分级通知用不同渠道区分告警、状态、调试消息单一通知渠道易被用户关闭。按主题前缀动态创建渠道主题模式渠道ID重要性声音alert/#alert_channelIMPORTANCE_HIGH自定义铃声status/#status_channelIMPORTANCE_DEFAULT无声音debug/#debug_channelIMPORTANCE_MIN仅震动在showNotification()中String channelId; if (topic.startsWith(alert/)) { channelId alert_channel; createChannelIfNotExists(channelId, 告警通知, NotificationManager.IMPORTANCE_HIGH, R.raw.alert_sound); } else if (topic.startsWith(status/)) { channelId status_channel; createChannelIfNotExists(channelId, 状态通知, NotificationManager.IMPORTANCE_DEFAULT, 0); } else { channelId debug_channel; createChannelIfNotExists(channelId, 调试通知, NotificationManager.IMPORTANCE_MIN, 0); }5.3 通知点击归因记录每次点击的原始主题与消息ID用于效果分析在showNotification()构建PendingIntent时注入唯一追踪IDlong traceId System.currentTimeMillis(); // 或UUID.randomUUID().getMostSignificantBits() Intent intent new Intent(this, MainActivity.class); intent.putExtra(trace_id, traceId); intent.putExtra(topic, topic); intent.putExtra(content, content); // 记录到数据库供后续分析点击率 MqttClickLog log new MqttClickLog(); log.traceId traceId; log.topic topic; log.timestamp System.currentTimeMillis(); new InsertClickLogAsyncTask(mqttDatabase.clickLogDao()).execute(log);这样当用户点击通知进入App即可在onNewIntent()中捕获trace_id上报埋点“用户对alert/fire主题的点击率为73%”。我带过的三个模拟项目X都验证过把MQTT通知拆成“连接-订阅-缓存-渠道-归因”五层比堆砌SDK更可控。尤其在教育类、工控类轻量App中Paho前台服务Room的组合既满足功能又规避了厂商推送SDK的审核风险和唤醒限制。现在我的习惯是每次写MQTT逻辑第一行先敲createNotificationChannel()第二行写startForegroundService()第三行才碰connect()——顺序错了后面全是玄学。希望帮到你。本文还有配套的精品资源点击获取
简介本资源是一份面向Android应用开发者与物联网初学者的MQTT消息推送实战示例聚焦在移动终端实现轻量级远程通信的核心能力——连接MQTT服务器、订阅主题、接收消息并实时展示于系统通知栏。项目基于Eclipse Paho Android客户端库构建已集成完整服务生命周期管理、断线自动重连、消息回调处理及NotificationCompat通知封装逻辑可直接编译运行或作为模块嵌入现有工程。压缩包共607个文件含134个flat资源、121个json配置、188个xml布局与清单文件、8个核心Java业务类及APK安装包等结构清晰便于理解Android后台服务与MQTT协议协同机制整体大小为15.58MB。已有1142人学习下载提供开箱即用的可运行代码框架、关键注释说明及典型错误处理范式助开发者快速掌握物联网消息推送落地的关键链路。1. Android端MQTT消息推送落地从连接服务器、订阅主题到通知栏实时显示为什么90%的初学者卡在权限配置和后台保活在某高校物联网课程设计中A同学花三天时间跑通了MQTT服务器通信却始终收不到通知栏提醒——不是代码没写而是NotificationChannel未创建、ForegroundService未启动、AndroidManifest.xml里漏了uses-permission android:nameandroid.permission.POST_NOTIFICATIONS /Android 13强制要求。这并非个例实际项目中MQTT客户端能连上、能收包、但消息“静默消失”根本原因往往不在协议栈而在Android系统级行为约束。本文聚焦一个最小可运行闭环用Eclipse Paho Android Client连接公开MQTT测试服务器如broker.hivemq.com:1883订阅指定主题如test/android收到消息后立即在通知栏弹出带图标、渠道、点击跳转Activity的完整通知。不依赖任何第三方推送SDK纯原生实现覆盖Android 8.0Oreo至14UpsideDownCake全版本适配要点。适合正在做毕业设计、IoT设备配套App或需要轻量级消息通道的开发者——你不需要懂MQTT协议细节但必须清楚Android如何“允许”一条消息从网络层抵达用户眼前。2. 环境准备与依赖接入选Paho而非MQTTX SDK因为它的轻量性与可控性更适配通知场景2.1 为什么是Eclipse Paho Android Client不是Mosquitto Java版也不是自研Netty封装MQTT客户端库在Android生态有三类主流选择Mosquitto官方Java绑定需JNI编译APK体积膨胀明显且对Android生命周期无感知自研基于OkHttp/Netty的MQTT over WebSocket灵活性高但重试逻辑、离线缓存、QoS 1/2状态管理极易出错Eclipse Paho Android Client专为Android优化内置MqttAndroidClient自动处理主线程调用阻塞、后台服务绑定、广播接收器注册等胶水逻辑且支持setCallback()回调直接在主线程更新UI——这对通知栏触发至关重要。提示Paho Android Client已停止维护最后更新2021年但其稳定性和API简洁性仍远超多数新库。我们使用org.eclipse.paho:org.eclipse.paho.android.service:1.1.1该版本兼容AndroidX且无反射报错风险。2.2 Gradle依赖与混淆规则配置含AndroidX迁移关键项在模块级build.gradle中添加dependencies { implementation org.eclipse.paho:org.eclipse.paho.android.service:1.1.1 implementation androidx.core:core:1.12.0 // 必须≥1.10.0否则NotificationCompat.Builder构造失败 implementation androidx.work:work-runtime-ktx:2.9.0 // 后台任务保活基础 }若启用ProGuard/R8混淆必须保留Paho核心类否则MqttAndroidClient初始化时抛ClassNotFoundException# Paho MQTT for Android -keep class org.eclipse.paho.client.mqttv3.** { *; } -keep class org.eclipse.paho.android.service.** { *; } -dontwarn org.eclipse.paho.client.mqttv3.**2.3 权限声明从Android 6.0到14的渐进式适配清单AndroidManifest.xml中需声明以下权限按最低目标版本动态增减!-- 基础网络 -- uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE / !-- 通知栏必备Android 8.0强制渠道 -- uses-permission android:nameandroid.permission.POST_NOTIFICATIONS / !-- 后台保活Android 9限制前台服务需显式声明 -- uses-permission android:nameandroid.permission.FOREGROUND_SERVICE / !-- 可选WiFi状态监听用于网络切换时重连 -- uses-permission android:nameandroid.permission.ACCESS_WIFI_STATE /注意POST_NOTIFICATIONS权限在Android 13API 33起为运行时权限必须在首次订阅前动态申请而FOREGROUND_SERVICE是安装时权限无需运行时请求但必须在service标签中显式声明android:foregroundServiceType属性见3.2节。3. 核心代码实现从MQTT连接、主题订阅到通知构建的四步链路3.1 初始化MqttAndroidClient并建立连接用connectOptions控制超时与心跳private MqttAndroidClient mqttClient; private String brokerUrl tcp://broker.hivemq.com:1883; // 公共测试Broker无认证 private String clientId android_ System.currentTimeMillis(); // 唯一客户端ID private void initMqttClient() { mqttClient new MqttAndroidClient(this.getApplicationContext(), brokerUrl, clientId); MqttConnectOptions options new MqttConnectOptions(); options.setCleanSession(true); // 设为true断开后丢弃服务器未投递消息false则保留QoS1/2消息 options.setConnectionTimeout(30); // 单位秒避免Connect阻塞过久 options.setKeepAliveInterval(60); // 心跳间隔单位秒低于30秒可能被某些Broker拒绝 try { IMqttToken token mqttClient.connect(options); token.setActionCallback(new IMqttActionListener() { Override public void onSuccess(IMqttToken asyncActionToken) { Log.d(MQTT, Connected to broker); subscribeToTopic(test/android); // 连接成功后立即订阅 } Override public void onFailure(IMqttToken asyncActionToken, Throwable exception) { Log.e(MQTT, Connection failed, exception); // 此处应加入指数退避重连逻辑见4.1节 } }); } catch (MqttException e) { Log.e(MQTT, MqttException on connect, e); } }参数说明cleanSessiontrue是通知场景推荐值用户关闭App后不期望收到历史消息避免通知堆积connectionTimeout30防止弱网下connect()卡死主线程keepAliveInterval60是HiveMQ公共Broker接受的最大值设为120会返回CONNECTION_REFUSED。3.2 创建前台服务承载MQTT长连接解决Android 9后台执行限制Android 9Pie起禁止应用在后台启动ServiceMQTT必须运行在前台服务中。新建MqttForegroundService.javapublic class MqttForegroundService extends Service { private static final int NOTIFICATION_ID 1001; private MqttAndroidClient mqttClient; Override public void onCreate() { super.onCreate(); createNotificationChannel(); // 必须先创建渠道否则startForeground失败 startForeground(NOTIFICATION_ID, buildForegroundNotification()); } Override public int onStartCommand(Intent intent, int flags, int startId) { // 初始化MQTT客户端复用Application单例或此处new initMqttClient(); return START_STICKY; // 系统内存不足杀掉后会尝试重启 } private void initMqttClient() { mqttClient new MqttAndroidClient(this, tcp://broker.hivemq.com:1883, svc_ System.currentTimeMillis()); mqttClient.setCallback(new MqttCallbackExtended() { Override public void connectComplete(boolean reconnect, String serverURI) { try { mqttClient.subscribe(test/android, 0); // QoS 0最多一次通知场景足够 } catch (MqttException e) { Log.e(MQTT-SVC, Subscribe failed, e); } } Override public void connectionLost(Throwable cause) { Log.w(MQTT-SVC, Connection lost, cause); // 触发重连见4.1节 } Override public void messageArrived(String topic, MqttMessage message) throws Exception { String payload new String(message.getPayload()); Log.d(MQTT-SVC, Received: payload); showNotification(topic, payload); // 关键收到即通知 } Override public void deliveryComplete(IMqttDeliveryToken token) {} }); } private void showNotification(String topic, String content) { Intent intent new Intent(this, MainActivity.class); intent.putExtra(topic, topic); intent.putExtra(content, content); intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK); PendingIntent pendingIntent PendingIntent.getActivity(this, 0, intent, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_ONE_SHOT); NotificationCompat.Builder builder new NotificationCompat.Builder(this, mqtt_channel) .setSmallIcon(R.drawable.ic_notification) // 必须是alpha通道清晰的白底图标 .setContentTitle(MQTT消息) .setContentText(content) .setPriority(NotificationCompat.PRIORITY_HIGH) .setAutoCancel(true) .setContentIntent(pendingIntent) .setStyle(new NotificationCompat.DecoratedCustomViewStyle()); NotificationManagerCompat notificationManager NotificationManagerCompat.from(this); notificationManager.notify(System.currentTimeMillis(), builder.build()); } private void createNotificationChannel() { if (Build.VERSION.SDK_INT Build.VERSION_CODES.O) { CharSequence name MQTT消息通道; String description 接收设备状态、告警等实时通知; int importance NotificationManager.IMPORTANCE_HIGH; NotificationChannel channel new NotificationChannel(mqtt_channel, name, importance); channel.setDescription(description); channel.enableLights(true); channel.setLightColor(Color.RED); channel.enableVibration(true); NotificationManager notificationManager getSystemService(NotificationManager.class); notificationManager.createNotificationChannel(channel); } } private Notification buildForegroundNotification() { Intent notificationIntent new Intent(this, MainActivity.class); PendingIntent pendingIntent PendingIntent.getActivity(this, 0, notificationIntent, PendingIntent.FLAG_IMMUTABLE); return new NotificationCompat.Builder(this, mqtt_channel) .setContentTitle(MQTT服务运行中) .setContentText(正在监听主题test/android) .setSmallIcon(R.drawable.ic_service) .setContentIntent(pendingIntent) .build(); } Override public IBinder onBind(Intent intent) { return null; } }关键点说明startForeground()必须在onCreate()中调用且NotificationChannel必须提前创建PendingIntent.FLAG_IMMUTABLE是Android 12强制要求否则getActivity()抛异常R.drawable.ic_notification图标尺寸必须为24×24 dp且背景透明系统会自动染色为白色START_STICKY并非100%保证服务存活需配合JobIntentService或WorkManager做兜底见4.2节。3.3 在Activity中启动服务并处理通知点击解耦UI与后台逻辑在MainActivity.java的onCreate()中启动服务Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // 检查并申请通知权限Android 13 if (Build.VERSION.SDK_INT Build.VERSION_CODES.TIRAMISU) { if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ! PackageManager.PERMISSION_GRANTED) { ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.POST_NOTIFICATIONS}, 100); } } // 启动MQTT前台服务 Intent serviceIntent new Intent(this, MqttForegroundService.class); if (Build.VERSION.SDK_INT Build.VERSION_CODES.O) { startForegroundService(serviceIntent); } else { startService(serviceIntent); } } // 处理通知栏点击传入的数据 Override protected void onNewIntent(Intent intent) { super.onNewIntent(intent); if (intent.hasExtra(content)) { String content intent.getStringExtra(content); Toast.makeText(this, 收到消息 content, Toast.LENGTH_LONG).show(); } }注意onNewIntent()仅在launchModesingleTop或singleTask时生效务必在AndroidManifest.xml中为MainActivity设置activity android:name.MainActivity android:launchModesingleTop !-- 关键否则点击通知无法触发onNewIntent -- ... /4. 避坑指南Android MQTT通知场景最常踩的5个深坑及血泪修复方案4.1 现象MQTT连接成功但messageArrived()从不触发原因订阅主题时未指定QoS等级subscribe(topic, qos)第二个参数为0/1/2Paho默认QoS0但部分Broker如EMQX要求显式传参主题名含空格或特殊字符如test/ androidBroker拒绝订阅客户端ID重复同一clientId在多个设备登录后登录者踢掉前者导致旧连接失效。解决强制指定QoSmqttClient.subscribe(test/android, 0)主题名只用ASCII字母、数字、/、_、-clientId拼接设备唯一标识android_ Settings.Secure.getString(getContentResolver(), Settings.Secure.ANDROID_ID)。4.2 现象通知栏无反应Log显示NotificationManager: Ignoring notification原因NotificationChannel创建时importance设为IMPORTANCE_NONE或IMPORTANCE_MINsetSmallIcon()传入的资源ID不存在或不是drawable类型误用mipmapAndroid 12未设置setPriority()系统降级为低优先级。解决渠道重要性必须≥IMPORTANCE_DEFAULT推荐IMPORTANCE_HIGH图标资源放res/drawable/下命名如ic_notification.xmlVectorDrawable显式调用.setPriority(NotificationCompat.PRIORITY_HIGH)。4.3 现象App退到后台后10分钟内MQTT断连且不再自动重连原因Android 9限制后台应用的网络访问前台服务被系统回收MqttCallbackExtended.connectionLost()中未实现重连逻辑或重连未在主线程外执行导致ANR。解决在connectionLost()中启动HandlerThread执行重连new HandlerThread(MqttReconnect).start(); Handler reconnectHandler new Handler(reconnectThread.getLooper()); reconnectHandler.post(() - { try { mqttClient.connect(options); } catch (MqttException e) { /* 重试计数1指数退避 */ } });4.4 现象点击通知后Activity黑屏或闪退原因PendingIntent未设置FLAG_IMMUTABLEAndroid 12MainActivity未设置android:exportedtrueAndroid 12强制要求Intent携带的content字符串含不可见控制字符如\u202E解析时报BadParcelableException。解决PendingIntent.getActivity()必须加FLAG_IMMUTABLEAndroidManifest.xml中activity标签添加android:exportedtrue发送前对payload做TextUtils.htmlEncode()过滤。4.5 现象Android 14设备上通知完全不显示Log无错误原因Android 14API 34新增NotificationManager.canNotify()检查需在showNotification()前调用NotificationChannel未设置setSound()而用户系统设置中关闭了“无声通知”。解决if (Build.VERSION.SDK_INT Build.VERSION_CODES.UPSIDE_DOWN_CAKE) { if (!notificationManager.canNotify(mqtt_channel)) { // 引导用户去设置页开启通知 Intent intent new Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS) .putExtra(Settings.EXTRA_APP_PACKAGE, getPackageName()); startActivity(intent); return; } }5. 进阶技巧让MQTT通知真正可靠——离线消息缓存、多主题分级与点击归因追踪5.1 用Room数据库缓存离线消息避免网络抖动丢失关键通知当设备断网时MQTT Broker会根据QoS等级缓存消息但Android端若未及时处理messageArrived()消息将丢失。解决方案在messageArrived()中先存入本地数据库再构建通知。定义EntityEntity(tableName mqtt_message_cache) public class MqttMessageCache { PrimaryKey(autoGenerate true) public long id; public String topic; public String payload; public long timestamp; public boolean isRead; }在MqttForegroundService.messageArrived()中Override public void messageArrived(String topic, MqttMessage message) throws Exception { String payload new String(message.getPayload()); MqttMessageCache cache new MqttMessageCache(); cache.topic topic; cache.payload payload; cache.timestamp System.currentTimeMillis(); cache.isRead false; // 插入Room数据库异步 new InsertMessageAsyncTask(mqttDatabase.messageDao()).execute(cache); // 同时发通知不阻塞 showNotification(topic, payload); }优势用户打开App时可查询isReadfalse的消息列表实现“未读消息中心”即使通知被清除数据仍在。5.2 多主题分级通知用不同渠道区分告警、状态、调试消息单一通知渠道易被用户关闭。按主题前缀动态创建渠道主题模式渠道ID重要性声音alert/#alert_channelIMPORTANCE_HIGH自定义铃声status/#status_channelIMPORTANCE_DEFAULT无声音debug/#debug_channelIMPORTANCE_MIN仅震动在showNotification()中String channelId; if (topic.startsWith(alert/)) { channelId alert_channel; createChannelIfNotExists(channelId, 告警通知, NotificationManager.IMPORTANCE_HIGH, R.raw.alert_sound); } else if (topic.startsWith(status/)) { channelId status_channel; createChannelIfNotExists(channelId, 状态通知, NotificationManager.IMPORTANCE_DEFAULT, 0); } else { channelId debug_channel; createChannelIfNotExists(channelId, 调试通知, NotificationManager.IMPORTANCE_MIN, 0); }5.3 通知点击归因记录每次点击的原始主题与消息ID用于效果分析在showNotification()构建PendingIntent时注入唯一追踪IDlong traceId System.currentTimeMillis(); // 或UUID.randomUUID().getMostSignificantBits() Intent intent new Intent(this, MainActivity.class); intent.putExtra(trace_id, traceId); intent.putExtra(topic, topic); intent.putExtra(content, content); // 记录到数据库供后续分析点击率 MqttClickLog log new MqttClickLog(); log.traceId traceId; log.topic topic; log.timestamp System.currentTimeMillis(); new InsertClickLogAsyncTask(mqttDatabase.clickLogDao()).execute(log);这样当用户点击通知进入App即可在onNewIntent()中捕获trace_id上报埋点“用户对alert/fire主题的点击率为73%”。我带过的三个模拟项目X都验证过把MQTT通知拆成“连接-订阅-缓存-渠道-归因”五层比堆砌SDK更可控。尤其在教育类、工控类轻量App中Paho前台服务Room的组合既满足功能又规避了厂商推送SDK的审核风险和唤醒限制。现在我的习惯是每次写MQTT逻辑第一行先敲createNotificationChannel()第二行写startForegroundService()第三行才碰connect()——顺序错了后面全是玄学。希望帮到你。本文还有配套的精品资源点击获取
