离线推送概述

大约 9 分钟

离线推送概述

功能说明

环信即时通讯 IM 支持通过 Apple Push Notification service(APNs)向 iOS 离线用户发送消息通知。用户重新上线并恢复 IM 连接后,SDK 会拉取离线期间的消息,应用可以据此更新会话和消息界面。

推送通知与 IM 消息同步是两个过程,收到推送通知不代表 SDK 已收到对应的完整消息。通知角标中的离线消息数也不等同于会话的实际未读消息数。

你可以在 环信官网open in new window 下载即时通讯 IM Demo,体验离线推送功能。

前提条件

开始接入前,请确认以下条件:

SDK 与运行环境

APNs 与控制台配置

准备具备推送配置权限的 Apple 开发者账号,为应用配置 APNs 推送,并在 环信控制台open in new window 上传和配置对应的推送证书。确认 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 tokenAPNs 为设备上的应用提供的推送标识,用于确定通知的目标设备和应用。客户端获取后,需通过 SDK 将其绑定到环信服务器。

证书创建、上传及 token 绑定的具体步骤见 APNs 推送集成。

消息推送流程

APNs 离线消息推送流程

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

  1. 用户 B 向 APNs 推送服务注册,获取推送 token。
  2. APNs 返回推送 token。
  3. 用户 B 向环信服务器上传推送证书名称和推送 token。
  4. 用户 A 向 用户 B 发送消息。
  5. 环信服务器检查用户 B 是否在线。若在线,环信服务器直接将消息发送给用户 B。
  6. 若用户 B 离线,环信服务器判断该用户是否使用了 APNs 推送。
  7. 环信服务器将消息发送给 APNs 推送服务器。
  8. 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 绑定。

具体接口调用和生命周期接入示例见 处理应用前后台切换。

多设备离线推送策略

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

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

多端登录时,若某台设备被踢下线,即使该设备已接入 IM 离线推送,也收不到该账号的离线推送消息。

多设备离线推送策略

退出登录后的推送

主动退出 IM 登录时,是否解除账号与 device token 的绑定,会影响该设备后续是否接收该账号的离线推送。调用 logout:completion: 时,通过 aIsUnbindDeviceToken 参数控制:

参数值行为
YES解除绑定。成功解绑后,该设备不再收到该账号的离线推送;若解绑失败,应处理完成回调返回的错误。
NO保留绑定。在证书和 token 有效且满足推送条件时,该设备仍可收到该账号的离线推送。

推送高级功能

开通功能

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

  1. 登录环信控制台,选择页面上方的 应用管理。
  2. 在应用列表中,点击目标应用 操作 栏中的 管理。
  3. 选择 增值服务 > 消息推送 > 离线推送。
  4. 点击 免费开通。

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

开通推送高级功能

推送通知方式

推送通知方式用于控制哪些离线消息可以触发通知,支持以下三种类型:

  • 接收所有离线消息的推送通知。
  • 仅接收提及用户的消息的推送通知。
  • 不接收离线消息的推送通知。

可以在应用级别或单聊、群聊会话级别设置,会话级别的设置优先于应用级别。具体配置见 推送通知方式。

免打扰模式

完成 SDK 初始化并登录后,可以在应用级别或单聊、群聊会话级别设置免打扰,关闭相应范围内的离线推送通知,支持以下配置:

  • 设置免打扰时间段,例如 08:00 至 10:00。
  • 设置免打扰时长,例如 30 分钟。
  • 开启全天免打扰,或关闭免打扰模式。

若需在免打扰模式下向指定用户推送消息,需配置强制推送。具体规则和配置见 免打扰模式 和 强制推送。

推送模板

推送模板用于自定义通知标题和内容,支持默认模板 default、detail 和自定义模板。可以在环信控制台配置,以满足默认通知内容之外的业务需求。

支持 发送消息时指定推送模板,也支持 接收方配置所用模板。具体配置见 推送模板。

上次编辑于: