离线推送概述
离线推送概述
功能说明
环信即时通讯 IM 支持通过 Apple Push Notification service(APNs)向 iOS 离线用户发送消息通知。用户重新上线并恢复 IM 连接后,SDK 会拉取离线期间的消息,应用可以据此更新会话和消息界面。
推送通知与 IM 消息同步是两个过程,收到推送通知不代表 SDK 已收到对应的完整消息。通知角标中的离线消息数也不等同于会话的实际未读消息数。
你可以在 环信官网 下载即时通讯 IM Demo,体验离线推送功能。
前提条件
开始接入前,请确认以下条件:
SDK 与运行环境
- 已 开启和配置即时通讯服务,获取有效的 App Key,并完成 iOS SDK 导入。
- 开发环境满足 iOS SDK 的要求,并已了解即时通讯 IM API 的 使用限制。
- 准备 iOS 真机,用于验证实际推送效果,详见 测试 APNs 推送。
APNs 与控制台配置
准备具备推送配置权限的 Apple 开发者账号,为应用配置 APNs 推送,并在 环信控制台 上传和配置对应的推送证书。确认 Bundle ID、签名及描述文件中的推送配置与应用一致,控制台配置的推送环境与安装包匹配。具体步骤见 创建推送证书 和 上传推送证书。
控制台的推送证书配置属于接入准备工作。客户端需在 SDK 初始化时通过 EMOptions.apnsCertName 设置控制台配置的证书名称,并将获取的 device token 传递给 SDK。若传入 token 时尚未登录,SDK 会在登录成功后尝试上传已保存的 token,应在登录后确认服务器端的绑定结果;收到新的 token 后,需及时传递给 SDK。具体步骤见 将证书名称传递给 SDK 和 获取 device token 并传递给 SDK。
完整客户端接入步骤见 在客户端集成 APNs。完成接入后,按 测试 APNs 推送 验证;未收到通知时,可按 故障排除 检查。
系统通知权限
在 Xcode 中为应用开启 Push Notifications 能力。如需展示横幅、声音或角标,还应向用户申请相应的通知授权,并确认系统设置中已允许该应用展示对应通知。具体配置见 在 app 中开启推送权限。
获取 APNs device token、将 token 绑定到环信服务器和获得通知展示权限是不同环节。获取 token 或完成绑定,不代表系统已允许应用展示通知。
推送通知方式、免打扰模式和推送模板属于可选的高级功能,其开通要求详见 开通功能。
工作原理
推送证书与 device token
APNs 推送依赖推送证书和 device token:
| 内容 | 作用 |
|---|---|
| 推送证书 | 用于环信服务器向 APNs 发起推送请求。需要在环信控制台上传并配置,客户端设置的证书名称应与控制台保持一致。 |
| device token | APNs 为设备上的应用提供的推送标识,用于确定通知的目标设备和应用。客户端获取后,需通过 SDK 将其绑定到环信服务器。 |
证书创建、上传及 token 绑定的具体步骤见 APNs 推送集成。
消息推送流程

以用户 A 向用户 B 发送消息为例:
- 用户 B 向 APNs 推送服务注册,获取推送 token。
- APNs 返回推送 token。
- 用户 B 向环信服务器上传推送证书名称和推送 token。
- 用户 A 向 用户 B 发送消息。
- 环信服务器检查用户 B 是否在线。若在线,环信服务器直接将消息发送给用户 B。
- 若用户 B 离线,环信服务器判断该用户是否使用了 APNs 推送。
- 环信服务器将消息发送给 APNs 推送服务器。
- APNs 推送服务器将消息发送给用户 B。
推送触发条件
用户离线与连接状态
环信服务器根据接收方的在线状态、证书和 token 绑定、多设备推送策略、推送通知方式及免打扰等配置,决定是否发送离线推送,不以客户端是否收到断开回调为依据。应用进入后台、设备锁屏或应用进程未运行,都应结合实际连接情况和服务端状态判断,不能仅根据应用界面状态认定用户已离线。
如果设备仍保持 IM 长连接,且服务器仍将用户判定为在线,则不会向该设备发送离线推送通知。多设备登录时,还需结合下文的 多设备离线推送策略 判断。
聊天室不支持离线消息推送;设置 EMChatMessage.deliverOnlineOnly = YES 的消息仅向在线用户投递,不触发离线推送。
提示
SDK 4.26.0 提供的 EMOptions.disconnectNotifyThreshold 只影响相关断线回调的通知时机,不延迟实际连接状态的变化,也不控制 APNs 的发送时间。具体配置见 断线通知宽限期;当前连接状态的判断见 查询连接状态。
应用前后台切换
完成 SDK 初始化后,需要将应用的前后台生命周期事件传递给 SDK,使后台断连、前台重连与 APNs 推送配合工作。
| 应用状态变化 | 调用的 SDK 接口 | SDK 行为及推送关系 |
|---|---|---|
| 进入后台 | -[EMClient applicationDidEnterBackground:] | 已登录时,SDK 在收到后台生命周期调用后主动断开 IM 长连接,并通知未连接状态。服务端判定用户离线且满足推送条件后,通过 APNs 下发通知。 |
| 回到前台 | -[EMClient applicationWillEnterForeground:] | 已登录时,SDK 在收到前台生命周期调用后检查连接或尝试重连,连接恢复后接收离线期间的消息。若已退出登录或被强制下线,需要按业务流程重新登录。 |
SDK 在收到后台生命周期调用后,已登录时直接执行断连,不以 token 是否绑定成功作为前提。验证后台接收通知前,应先完成证书配置和 token 绑定。
具体接口调用和生命周期接入示例见 处理应用前后台切换。
多设备离线推送策略
同一账号在多台设备登录时,可以在 环信控制台 的 证书管理 页面配置推送策略。该配置对所有推送通道生效:
- 所有设备离线时,才发送推送消息。
- 任一设备离线时,都发送推送消息。
多端登录时,若某台设备被踢下线,即使该设备已接入 IM 离线推送,也收不到该账号的离线推送消息。

退出登录后的推送
主动退出 IM 登录时,是否解除账号与 device token 的绑定,会影响该设备后续是否接收该账号的离线推送。调用 logout:completion: 时,通过 aIsUnbindDeviceToken 参数控制:
| 参数值 | 行为 |
|---|---|
YES | 解除绑定。成功解绑后,该设备不再收到该账号的离线推送;若解绑失败,应处理完成回调返回的错误。 |
NO | 保留绑定。在证书和 token 有效且满足推送条件时,该设备仍可收到该账号的离线推送。 |
推送高级功能
开通功能
推送通知方式、免打扰模式和推送模板属于推送高级功能,使用前需在 环信控制台 免费开通。
- 登录环信控制台,选择页面上方的 应用管理。
- 在应用列表中,点击目标应用 操作 栏中的 管理。
- 选择 增值服务 > 消息推送 > 离线推送。
- 点击 免费开通。
激活后,如需关闭推送高级功能,必须联系商务,因为关闭操作会删除高级功能相关的所有配置。

推送通知方式
推送通知方式用于控制哪些离线消息可以触发通知,支持以下三种类型:
- 接收所有离线消息的推送通知。
- 仅接收提及用户的消息的推送通知。
- 不接收离线消息的推送通知。
可以在应用级别或单聊、群聊会话级别设置,会话级别的设置优先于应用级别。具体配置见 推送通知方式。
免打扰模式
完成 SDK 初始化并登录后,可以在应用级别或单聊、群聊会话级别设置免打扰,关闭相应范围内的离线推送通知,支持以下配置:
- 设置免打扰时间段,例如 08:00 至 10:00。
- 设置免打扰时长,例如 30 分钟。
- 开启全天免打扰,或关闭免打扰模式。
若需在免打扰模式下向指定用户推送消息,需配置强制推送。具体规则和配置见 免打扰模式 和 强制推送。
推送模板
推送模板用于自定义通知标题和内容,支持默认模板 default、detail 和自定义模板。可以在环信控制台配置,以满足默认通知内容之外的业务需求。
支持 发送消息时指定推送模板,也支持 接收方配置所用模板。具体配置见 推送模板。
