离线推送概述

大约 11 分钟

离线推送概述

功能说明

即时通讯 IM 支持通过第三方推送服务，在用户离线时向设备发送消息通知。目前支持 Google FCM、华为、荣耀、小米、OPPO、vivo 和魅族推送。

离线推送通知用于提醒用户有新消息。用户重新打开应用并登录成功后，SDK 会拉取离线期间的消息。推送通知与 IM 消息同步是两个过程，收到推送通知不等于 SDK 已收到对应的完整消息。推送中的离线消息数也不等同于会话实际未读数。

要体验离线推送功能，请在 环信官网open in new window 下载即时通讯 IM 的 Demo。

前提条件

SDK 与运行环境

推送通道设备与运行环境要求
Google FCM设备支持并启用 Google Play 服务，且可以连接 Google 服务器。
小米使用支持小米推送的小米设备。
华为使用支持华为推送的华为设备。
魅族使用支持魅族推送的魅族设备。
OPPO使用支持 OPPO 推送的 OPPO 设备。
vivo使用支持 vivo 推送的 vivo 设备。
荣耀使用支持荣耀推送的荣耀设备。

厂商推送与控制台配置

在对应的厂商开发者平台注册应用并开通推送服务，获取所需的应用标识、密钥或证书，然后在 环信控制台open in new window 配置对应的推送证书信息。

控制台的推送证书配置属于接入准备工作；客户端 Token 与 IM 账号的绑定在 SDK 初始化并登录成功后完成，Token 更新后需及时同步。例如，FCM 的配置和绑定要求见 上传推送证书 和 FCM 推送集成。其他厂商见 厂商集成文档入口。

系统通知权限

确保应用已按 Android 系统版本和目标 SDK 版本配置、申请所需的通知权限，并确认系统设置中已允许应用及对应通知渠道展示通知。Android 13 及以上版本需按系统要求处理通知运行时权限。

设备已获取 Token 或完成 Token 绑定，不代表通知展示权限已开启。

厂商集成文档入口

根据目标设备及业务覆盖区域选择推送通道，依照对应文档完成厂商项目注册、证书配置、推送 SDK 依赖及清单配置、客户端初始化和 Token 绑定。

推送通道集成文档
Google FCM集成 FCM 推送
小米集成小米推送
华为集成华为 HMS 推送
魅族集成魅族推送
OPPO集成 OPPO 推送
vivo集成 vivo 推送
荣耀集成荣耀推送

如果应用有海外使用场景，建议接入 FCM；若需覆盖多个品牌设备，建议按业务需要集成多个厂商通道。

在 SDK 初始化前，通过 EMPushConfig.Builder 启用所需通道，并调用 EMOptions#setPushConfig(EMPushConfig) 设置推送配置。通用初始化要求见 初始化 SDK，各通道的配置示例见上表中的厂商集成文档。

若项目开启代码混淆，通用规则见 防止代码混淆，并按厂商集成文档补充对应推送 SDK 的规则。

推送通知方式、免打扰模式和推送模板属于可选的高级功能，其开通要求详见 开通功能。

工作原理

推送证书与推送 Token

概念作用
推送证书环信服务器调用厂商推送服务所需的配置。不同厂商可能要求应用标识、密钥或证书文件等信息；客户端配置或上传的证书名称需与环信控制台中的配置一致。
推送 Token（device token）厂商推送服务为设备上的应用实例生成的标识，用于确定通知的目标。客户端需将 Token 上传至环信服务器，并与 IM 登录账号绑定。

推送通道选择

SDK 默认按 FCM、小米、华为、魅族、OPPO、vivo、荣耀的顺序，检查已启用且设备支持的通道，并选择首个满足条件的通道。未配置厂商推送或没有可用通道时，SDK 会通过保活机制尽可能维持 IM 长连接；这不等于已接入厂商离线推送。

消息推送流程

Android 离线推送流程

以用户 A 向用户 B 发送消息为例：

  1. 用户 B（消息接收者）根据已配置的推送通道和设备支持情况，选择可用的厂商推送服务。
  2. 用户 B 通过已配置的第三方推送 SDK 向第三方推送服务器请求获取推送 token。
  3. 第三方推送服务器向用户 B 返回推送 token。
  4. 用户 B 向环信服务器上传推送证书名称及推送 token。
  5. 用户 A 向用户 B 发送消息。
  6. 环信服务器检查用户 B 的在线状态。若用户 B 在线，服务器直接将消息投递给用户 B。
  7. 若用户 B 离线，环信服务器判断该用户设备所使用的推送服务类型。
  8. 环信服务器将消息转发至第三方推送服务器。
  9. 第三方推送服务器将消息最终投递至用户 B 的设备。

推送触发条件与消息接收策略

在线状态与应用前后台状态

应用进入后台或手机锁屏本身并不表示用户已离线。若客户端与服务器仍保持 IM 长连接，用户仍为在线状态，不会仅因应用进入后台而触发离线推送。

是否发送离线推送，由环信服务器根据用户在线状态、多设备推送策略、推送通知方式及免打扰等配置决定，不以客户端是否收到断开回调为依据。聊天室不支持离线消息推送。

配置后台消息接收策略

自 SDK 5.2.1 起，支持通过 EMOptions#setUsePushInBackground(boolean usePushInBackground) 配置应用进入后台后的消息接收策略，通过 EMOptions#isUsePushInBackground() 查询开关值。该开关必须在调用 EMClient#init 初始化 SDK 前设置。

usePushInBackground行为
false（默认）SDK 不会因应用进入后台而主动断开 IM 长连接。后台连接能否持续保持，还受系统后台限制和应用保活策略影响。
true切入后台时，若推送 Token 已成功绑定、厂商推送通道有效，SDK 会在约 10 秒后断开 IM 长连接。持续处于后台且连接仍可用时，执行断连；后续消息满足服务端离线推送条件时，通过推送通道发送通知。切入后台时通道条件不满足，则不安排该断连任务。

该策略统一适用于 FCM、华为、荣耀、小米、OPPO、vivo 和魅族等厂商推送通道。

应用回到前台时，SDK 会取消尚未执行的后台断连任务。如果应用已处于后台，连接成功时该开关已开启且通道有效，SDK 会直接断开连接，不再等待约 10 秒。因此，约 10 秒并非所有后台连接都能保持的时长。

该开关只控制后台连接策略，不会自动完成厂商推送集成或 Token 绑定。推送配置和 SDK 初始化要求见 初始化 SDK 及对应的 厂商集成文档。后台断连所需的通道条件见 确认推送通道有效。

确认推送通道有效

自 SDK 5.2.1 起，支持通过 EMPushHelper#isPushTokenBound() 查询当前是否已建立有效的厂商推送通道。该方法无参数，返回 boolean：

  • true：当前推送类型非空、非 EMPushType.NORMAL，且本地保存的对应 Token 非空，SDK 据此判断通道有效。
  • false：不满足上述条件，SDK 尚未确认有效的厂商推送通道。

Token 绑定是异步过程，登录成功后立即查询可能返回 false。可在 PushListener#onBindTokenSuccess(EMPushType type, String token) 回调后查询；监听设置及 Token 上传方式见 FCM 推送集成 和其他厂商集成文档。

该方法根据 SDK 当前推送类型和本地保存的 Token 判断，不会实时请求服务器，也不表示每条通知都能送达。仅开启 usePushInBackground 不代表通道已有效。

后台断连与断线通知宽限期

自 SDK 5.2.1 起，后台断连等待时间与断线通知宽限期是两项独立机制：

机制作用与配置
后台断连等待时间切入后台时，若 usePushInBackground 已开启且通道有效，SDK 安排约 10 秒后断连；回到前台则取消尚未执行的任务。后台连接成功且满足上述条件时，会直接断连。详见 配置后台消息接收策略。
断线通知宽限期本次登录已成功建立连接后，发生网络异常等可恢复断线时，SDK 可暂缓触发 onDisconnected(int errorCode)。默认 10 秒，可通过 EMOptions#setDisconnectNotifyThreshold(int seconds) 配置。

断线通知宽限期只影响断开回调的触发时机，不会延迟实际连接状态的变化。未收到 onDisconnected 不代表长连接仍然可用；如需查询客户端当前连接状态，请使用 EMClient#getConnectionState()，详见 查看连接状态。

断线通知宽限期不是离线推送的额外等待时间，不能将其与后台断连等待时间简单相加来推算推送触发或送达时间。宽限期的适用范围及完整规则，详见 配置断线通知宽限期。

多设备离线推送策略

同一账号登录多个设备时，可在 环信控制台open in new window 的 证书管理 页面配置以下推送策略。该配置对所有推送通道生效：

  • 所有设备离线时，才发送推送消息。
  • 任一设备离线时，都发送推送消息。

因此，多设备场景下，判断某台设备是否会收到推送，还需结合账号的多设备推送策略，不能仅查看其中一个客户端的连接状态。

多端登录时，被踢下线的设备即使已接入离线推送，也不会再收到该账号的离线推送通知。

多设备离线推送策略配置

退出登录与 Token 解绑

调用 EMClient#logout 退出 IM 登录时，unbindToken 参数控制是否解绑推送 Token，接口用法见 退出登录：

unbindToken行为
true退出登录时解绑推送 Token，解绑成功后不再通过该绑定接收此账号的离线推送通知。
false退出登录时保留推送 Token 绑定；推送证书和 Token 有效且满足推送条件时，设备仍可收到该账号的离线推送通知。

退出登录与被踢下线是不同场景，不能直接套用相同的推送行为。

推送高级功能

开通功能

推送通知方式、免打扰模式 和 推送模板 属于推送的高级功能。使用前需在 环信控制台open in new window 免费开通。

开通入口及操作步骤见 开通推送高级功能。

激活后，如需关闭推送高级功能，必须联系商务；关闭操作会删除高级功能相关的所有配置。

推送通知方式

支持接收所有离线消息的通知、仅接收提及用户的消息通知，或不接收通知。可在应用级别和单聊、群聊会话级别设置，会话级别设置优先于应用级别设置。

详见 推送通知方式。

免打扰模式

完成 SDK 初始化并成功登录应用后，你可以设置应用级别和单聊、群聊会话级别的免打扰功能，可配置免打扰时间段、时长或全天免打扰。业务需要在免打扰期间通知指定用户时，可使用强制推送。

详见 免打扰模式 和 强制推送。

推送模板

当服务器提供的默认离线推送配置无法满足业务需求时，可通过推送模板设置全局范围的推送标题和推送内容。

支持默认模板 default、detail 及自定义模板，用于配置推送标题和内容。可在环信控制台配置模板，并在消息发送或接收侧按需使用。

详见 推送模板。

上次编辑于:
环信 IM 文档
© 环信 2026