IM 即时通讯
Android
产品介绍
简介
产品优势
主要功能
功能介绍
帐号集成与登录
群组功能
聊天室功能
聊天室标签功能
圈组功能
多端登录与互踢策略
质量数据监控台
海外数据中心
IM平滑迁移方案
接口及业务限制
更新日志
IM UIKit 更新日志
NIM SDK 开发版更新日志
NIM SDK 稳定版更新日志
体验 Demo
下载 SDK 与 Demo 源码
快速开始
跑通 IM Demo 源码
实现单聊消息收发(不含 UI)
跑通圈组 Demo 源码
实现圈组消息收发(不含 UI)
含 UI 集成
什么是 IM UIKit
IM UIKit 功能概览
快速集成 IM UIKit
组件导入
初始化
界面跳转
自定义用户信息
全局配置
会话列表相关
集成会话列表界面
会话列表事件监听
自定义会话列表界面 UI
会话列表 API 概览
会话消息相关
集成会话界面
会话界面事件监听
实现音视频通话
实现地理位置消息功能(含 UI)
实现自定义消息发送(含 UI)
自定义会话界面 UI
会话消息 API 概览
通讯录相关
集成通讯录界面
自定义通讯录界面 UI
通讯录界面事件监听
通讯录 API 概览
IM UIKit 常见问题排查
IM UIKit API 概览
不含 UI 集成
集成 SDK
初始化
登录相关
登录 IM
多端登录与互踢
登出 IM
消息相关
消息概述
消息收发
自定义消息收发
消息配置选项
NOS 存储场景
广播消息收发
消息已读回执
消息撤回
消息重发与转发
消息更新
消息过滤
语音消息处理
插入本地消息
历史消息
最近会话
服务端会话服务
用户资料
用户关系
在线状态订阅
系统通知
系统通知概述
内置系统通知管理
内置系统通知未读数
自定义系统通知收发
Android 离线推送
实现离线推送
配置消息的推送属性
设置群消息强制推送
设置推送全局免打扰
设置多端推送策略
集成小米推送
集成华为推送
集成荣耀推送
集成 OPPO 推送
集成 vivo 推送
集成魅族推送
集成谷歌推送(FCM)
消息提醒
实现消息提醒
配置消息提醒功能
设置群消息强制提醒
设置消息提醒文案
定制通知栏显示信息
群组功能
群组概述
群组管理
群成员管理
群消息管理
超大群功能
聊天室
圈组功能
圈组概述
登录管理
服务器相关
服务器概述
服务器管理
服务器成员管理
游客功能
服务器未读数管理
频道相关
频道概述
频道管理
频道黑白名单
实时互动频道
频道分组
频道分组黑白名单
频道未读数管理
搜索服务器和频道
身份组相关
身份组概述
身份组应用场景
服务器身份组
频道身份组
用户定制权限
频道分组身份组
自定义权限项
成员权限查询与判定
身份组相关查询
圈组订阅机制
圈组消息相关
图解圈组消息流转
圈组消息收发
圈组消息撤回
圈组消息更新
圈组消息删除
消息正在输入
会话消息回复(Thread)
圈组快捷评论
获取频道最后一条消息
查询历史消息
查询@我的消息
圈组消息缓存
圈组消息搜索
圈组系统通知相关
圈组系统通知概述
圈组系统通知收发
圈组系统通知更新
圈组离线推送
圈组内容审核
圈组相关抄送
圈组第三方回调
圈组各端接口命名差异
反垃圾
聊天扩展
其他
最佳实践
IM 登录最佳实践
IM 应用隐私合规
聊天室重要消息投递
API 参考
Android SDK API
Android SDK 状态码
IM 控制台指南
创建应用
注册 IM 账号
升级服务
开通聊天室功能
配置应用客户端标识
常见问题
FAQ
错题集
Android 端推送问题排查
第三方推送厂商的限制说明
服务协议

实现离线推送

更新时间: 2023/03/27 15:05:17

为了提高消息送达率,云信引入手机系统厂商推送。手机系统级别的厂商推送(如小米、华为、vivo、OPPO、魅族等)的优势在于其拥有稳定的系统级长连接,可以做到随时接收推送。

功能概述

NIM SDK 支持离线推送消息功能。

当用户清理掉应用进程(被冻结、主动关闭)、网络不稳定等导致客户端 SDK 无法与云信服务器保持正常连接时,将使用手机厂商系统级推送来告知用户有消息需要接收。

您可以通过集成各手机厂商推送 SDK,与 NIM SDK 搭配使用,实现离线推送功能。

技术原理

云信 IM 实现离线推送的技术原理如下:

前提条件

在实现“离线推送”功能之前,请确保:

  • 开发环境满足如下要求:

    • Android 4.4 及以上版本。
    • 自 v6.9.0 起,改用 AndroidX 支持库,Target API 改为 28,不再支持 support 库。
  • 已创建云信 IM 账号

实现流程

步骤 1:集成第三方厂商离线推送服务

请参考具体厂商的推送集成文档,集成需要使用到的第三方厂商离线推送 SDK,接入各厂商的离线推送服务。

目前支持以下第三方推送厂商:

第三方推送厂商 当前兼容版本 集成指南
小米 MiPush_SDK_Client_5_1_0 集成小米推送
华为 com.huawei.hms:push: 6.5.0.300 集成华为推送
荣耀 com.hihonor.mcs:push:7.0.1.103
NIM SDK 稳定版暂不支持荣耀推送
集成荣耀推送
OPPO com.heytap.msp-push-3.1.0.aar 集成 OPPO 推送
vivo vivo_pushsdk_v3.0.0.4_484 集成 vivo 推送
魅族 com.meizu.flyme.internet:push-internal:4.1.0 集成魅族推送
谷歌 FCM firebase-bom:28.4.2
具体版本:firebase-messaging:23.0.0firebase-analytics: 20.0.0
集成谷歌推送

步骤 2:集成 NIM SDK

集成 NIM SDK 时,需要添加第三方厂商推送辅助包。

  • 若自动集成,则需要在 dependencies 中添加相关依赖。

    dependencies {
        compile fileTree(dir: 'libs', include: '*.jar')
        // 添加依赖。注意,版本号必须一致。
    
        // 基础功能 (必需)
        implementation "com.netease.nimlib:basesdk:${LATEST_VERSION}"
        // 通过云信来集成第三方厂商推送需要
        implementation "com.netease.nimlib:push:${LATEST_VERSION}"
    }
    
  • 若手动集成需要将下载的 nim-push-x.x.x.jar 文件拷贝到您的项目路径的 app/libs 目录下;然后在该 .jar 文件上右键添加为依赖。

步骤 3:初始化 NIM SDK

Application#onCreate 中,调用 NIMClient#init 方法进行初始化。初始化 NIM SDK 时,完成厂商的推送证书配置,并选择推送渠道。

  1. 需要将推送证书的信息配置到初始化参数 SDKOptions.mixPushConfig 中。

    小米
    MixPushConfig config = new MixPushConfig();
    // 传入从小米推送平台获取到的AppId与AppKey
    config.xmAppId = "xxxx";
    config.xmAppKey = "xxxx";
    // 传入云信控制台上小米推送对应的证书名
    config.xmCertificateName = "xxxx";
    ...
    options.mixPushConfig = config;
    
    华为
    MixPushConfig config = new MixPushConfig();
    // 传入华为推送的APP ID
    config.hwAppId = "xxxx";
    // 传入云信控制台上华为推送证书名
    config.hwCertificateName = "xxxx";
    ...
    options.mixPushConfig = config;
    
    荣耀
    MixPushConfig config = new MixPushConfig();
    // 传入荣耀推送证书名,荣耀推送的 appId请在 AndroidManifest.xml 文件中配置
    config.honorCertificateName = "xxxx";
    ...
    options.mixPushConfig = config;
    
    vivo
    MixPushConfig config = new MixPushConfig();
    // 传入云信控制台上配置的vivo推送证书名,vivo 推送的 appId appKey请在 AndroidManifest.xml 文件中配置
    config.vivoCertificateName = "xxxx"; 
    ...
    options.mixPushConfig = config;
    
    OPPO
    MixPushConfig config = new MixPushConfig();
    
    config.oppoAppId = "xxxx";
    config.oppoAppKey = "xxxxxx";
    // 注意区分AppSercet与MasterSecret
    config.oppoAppSercet = "xxxxxxx";
    // 传入云信控制台上配置的oppo推送证书名
    config.oppoCertificateName = "xxxx";
    ...
    options.mixPushConfig = config;
    
    魅族
    MixPushConfig config = new MixPushConfig();
    
    config.mzAppId = "xxx";
    config.mzAppKey = "xxxx";
    config.mzCertificateName = "xxxx";
    ...
    options.mixPushConfig = config;
    
    谷歌
    //传入云信控制台上配置的谷歌推送证书名,谷歌推送的  AppSecret 请在 AndroidManifest.xml 文件中配置
    MixPushConfig config = new MixPushConfig();
    
    config.fcmCertificateName = "xxxx";
    ...
    options.mixPushConfig = config;
    

    推送证书名长度不超过 32 个字符,否则登录时会报错 500。

  2. 选择推送渠道。

    • 如果SDKOptions.mixPushConfig.autoSelectPushType为 false(默认),则 SDK 直接选择服务端推荐的推送渠道。

    • 如果配置SDKOptions.mixPushConfig.autoSelectPushType为 true,则 SDK 根据实际的 token 的获取情况确定推送渠道,此时服务端推荐的推送渠道为最高优先级。需要确定推送渠道时,先进行本地支持性判断,然后将向所有可能支持的推送厂商申请 token,并在成功拿到的 token 中选择优先级更高的渠道。

    SDK 默认 Google FCM 推送的优先级最低,即如果同时接入了 FCM 和其他厂商推送,则会优先走其他厂商推送通道。但是如果您的应用用户主要分布在海外,在云信控制台已设置 FCM 推送优先控制台:应用详情 > 更多 > 证书管理),那么同时接入 FCM 和其他厂商推送 SDK 的场景下,优先走 FCM 推送通道。

  3. Application#onCreate 中启用华为、荣耀、OPPO 厂商的推送服务,即对华为、荣耀、OPPO 推送服务进行初始化。其他厂商推送服务无需额外初始化,可忽略该步骤。

    华为
    public class NimApplication extends Application {
        ...
        @Override
        public void onCreate() {
            ...
            if (NIMUtil.isMainProcess(this)) {
                ...
                // 在此处添加以下代码
                com.huawei.hms.support.common.ActivityMgr.INST.init(this);
                ...
            }
        }
    }
    
    荣耀
    public class NimApplication extends Application {
        ...
        @Override
        public void onCreate() {
            ...
            if (NIMUtil.isMainProcess(this)) {
                ...
                // 在此处添加以下代码
                HonorPushClient.getInstance().init(getApplicationContext(), true);
                ...
            }
        }
    }
    
    OPPO
    public class NimApplication extends Application {
        ...
        @Override
        public void onCreate() {
            ...
            if (NIMUtil.isMainProcess(this)) {
                ...
                // 在此处添加以下代码
                com.heytap.msp.push.HeytapPushManager.init(this, true);
                ...
            }
        }
    }
    

若您正确集成第三方推送(已传相关推送 token 至云信服务器),SDK 日志会打印以下相应记录。其中pushTypetype表示推送类型(5 小米、6 华为、7 魅族、8 谷歌FCM、9 vivo、10 OPPO、0 不支持),tokenName表示推送证书名称,token表示推送 token。

[ui]mix_push: after login, mix push state=MixPushState{pushType=5, hasPushed=0, lastDeviceId=''}
[ui]mix_push: commit mix push token:type 5 tokenName PUSH_CER_NAME token y7ssE..................sLxnU

步骤 4:测试离线推送

消息发送方:

发送消息或自定义系统通知给接收方(离线),具体的收发流程可参见消息收发自定义系统通知收发

这里以发送文本消息为例,通过调用 sendMessage 实现。发送的消息默认需要推送,如需设置推送文案,推送角标,推送文案前缀等,请参见配置消息的推送属性

// 该帐号为示例
String account = "testAccount";
// 以单聊类型为例
SessionTypeEnum sessionType = SessionTypeEnum.P2P;
String text = "this is an example";
// 创建一个文本消息
IMMessage textMessage = MessageBuilder.createTextMessage(account, sessionType, text);
// 发送给对方
NIMClient.getService(MsgService.class).sendMessage(textMessage, false).setCallback(new RequestCallback<Void>() {
                @Override
                public void onSuccess(Void param) {

                }

                @Override
                public void onFailed(int code) {
                    
                }

                @Override
                public void onException(Throwable exception) {

                }
            });

消息接收方:

接收方将会在登录后接收到离线推送。

(可选)步骤 5:关闭/开启离线推送服务

NIM SDK 的第三方推送服务功能默认开启,无需单独调用开启服务接口。若后续不想使用第三方推送服务,可调用 enable 方法进行关闭。

NIMClient.getService(MixPushService.class).enable(false).setCallback(...)

推送相关文档

常见问题

Q:触发离线推送的条件是什么?

A:Android 切换到后台并且等 app 被系统回收时,或者用户主动关闭 app,才能触发推送条件。因此,若要测试 Android 推送问题,请登录后关闭 app,确保满足推送条件。


Q:哪些场景下不会触发推送?

A: IM 账号未登录/已登出/被踢出,不会触发推送。App 在前台,也不会触发推送。用户登录 IM 账号,并且未主动登出或者没有被踢出,可能触发推送。

此文档是否对你有帮助?
有帮助
我要吐槽
  • 功能概述
  • 技术原理
  • 前提条件
  • 实现流程
  • 步骤 1:集成第三方厂商离线推送服务
  • 步骤 2:集成 NIM SDK
  • 步骤 3:初始化 NIM SDK
  • 步骤 4:测试离线推送
  • (可选)步骤 5:关闭/开启离线推送服务
  • 推送相关文档
  • 常见问题