推送相关 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

推送相关

更新时间： 2024/03/14 16:36:34

移动端全局关闭通知栏消息提醒 [注意] 如果开发者在实现@群成员功能的时候，对群消息配置了强制推送，那么即使按照下列方法关闭消息提醒，依然会收到通知栏提醒。

Android
iOS
当初始化SDK配置的StatusBarNotificationConfig不为空时，可以通过接口NIMClient.toggleNotification(false)关闭通知栏消息提醒。
[注意] 此处提到的关闭通知栏消息提醒，是指关闭由SDK触发的通知栏消息提醒。不会影响系统推送的通知栏消息提醒。
通过[[[NIMSDK sharedSDK] apnsManager] updateApnsSetting:setting completion:^(NSError *error) {}]更新全局APNs推送免打扰设置，[NIMPushNotificationSetting](https://dev.yunxin.163.com/docs/interface/%E5%8D%B3%E6%97%B6%E9%80%9A%E8%AE%AFiOS%E7%AB%AF/NIMSDK-iOS/Classes/NIMPushNotificationSetting.html)的属性noDisturbing为YES表示开启免打扰（需要配置开始和结束时间，免打扰才会生效）。

IM怎么关闭特定用户的消息提醒 [注意1] 各端配置的消息提醒会相互同步，主要影响移动端通知栏提醒，UI方面的提醒需要开发者根据[取消消息提醒/静音]列表自行实现。
[注意2] 消息提醒不影响未读数。

Windows (C)
Android
iOS
Web
- 取消提醒
  调用接口nim_user_set_mute (const char *accid, bool set_mute, const char *json_extension, nim_user_opt_cb_func cb, const void *user_data)，其中accid参数传入对方accid，set_mute参数设置为1或true。
- 获取列表
  调用接口nim_user_get_mute_blacklist获取已取消消息提醒列表，回调函数nim_user_sync_muteandblacklist_cb_func的black_list_json中，kNIMSpecialRelationKeyIsMute = "is_mute"表示已取消消息提醒。
- 取消提醒
  调用接口NIMClient.getService(FriendService.class).setMessageNotify(account, checkState).setCallback(new RequestCallback<Void>() {...})，其中account参数传入对方accid，notify参数设置为false。
- 获取列表
  通过List<String> accids = NIMClient.getService(FriendService.class).getMuteList()获取取消消息提醒的账号列表。
- 取消提醒
  调用NIMUserManager中的–updateNotifyState:forUser:completion:方法，其中notify参数设置为NO，userId参数传入对方accid。
- 获取列表
  调用NIMUserManager中的-myMuteUserList方法，返回取消消息提醒的NIMUser列表。
- 取消提醒
  调用接口nim.addToMutelist({account: 'accid', done: addToMutelistDone})，其中account参数传入对方accid。
- 获取列表
  调用接口nim.getRelations({done: getRelationsDone})，回调的对象属性obj.mutelist表示取消消息提醒的列表。
  
  关于消息推送
触发消息推送的条件
- IM账号未登录、已登出、被踢出，是不会触发推送的。
- 用户登录了IM账号，并且没有主动登出或者没有被踢出，才可能触发推送。
- app在前台，是不会触发推送的。
- iOS切换到后台，或者用户主动杀死app，才能触发推送条件。因此，要测试iOS推送问题，请登录后杀死app，或将其切换到后台。
- Android切换到后台并且等到app被系统回收时，或者用户主动杀死app，才能触发推送条件。因此，若要测试Android推送问题，请登录后杀死app，确保满足推送条件。
  对于Android通知栏提醒，当app被杀死后，或者切后台并且被系统回收后，弹出的通知栏提醒是由系统推送产生的。而app存活期间(在前台、以及在后台但是尚未被系统回收之前)弹出的通知栏提醒是由SDK或app调用系统方法弹出的(不属于系统推送)。
- [注意] 如果配置了多端登录，满足推送条件的各个客户端都会收到推送。如果不希望多个客户端同时收到推送，请关闭多端登录。
推送相关信息
- Android
- iOS
- 从3.2.0版本开始支持小米推送，从4.0.0版本开始支持华为推送，从4.6.0版本开始支持魅族推送和Google FCM(海外)推送，从6.3.0版本开始支持VIVO推送，从6.7.0版本开始支持OPPO推送。
  Google FCM(海外)推送的优先级最低，如果同时接入了FCM和厂商推送，则会走厂商推送。
  关于Android推送详细配置，请参考官方开发指南。如果无法收到推送，请点此查看排查指南。
- 通过APNs (Apple Push Notification service)推送，关于APNs原理，请参考Apple官网：APNs Overview。
  关于IM iOS SDK的APNs推送详细配置，请参考官方开发指南。
  [注意] 如果遇到iOS无法收到推送，可以点此查看排查指南。
关于推送的token

云信使用设备厂商的推送，SDK会将设备相关的推送token发送到服务器，以便设备厂商确定接收推送的设备。
开发者正确集成的话，SDK日志会打印相应记录。
- Android
- iOS
- [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
  其中，pushType和type表示推送类型：5 小米、6 华为、7 魅族、8 谷歌FCM、9 VIVO、10 OPPO、0 不支持
  tokenName表示推送证书名称，token表示推送token。
- file:NIMAppTokenManager.mm line: 115)<<<<send push token and cername 2bce0................90e27 CERNAME 0
  其中，长字符串表示token，CERNAME表示推送证书名称，0表示ApnsToken (1表示PushKitToken)。
  
  关于配置推送证书的注意事项
关于推送证书名称

推送证书名称不区分大小写，但是强烈建议开发者在代码中配置的证书名称和上传到云信控制台配置的证书名称保持一致。
- 云信控制台配置推送证书的位置为：「应用」(选择应用) - 证书管理 - iOS推送证书 或 安卓推送证书 - 添加证书。
  对于iOS，需要注意的是，上传到云信控制台的证书是p12文件格式，具体请点此查看。
- 代码中配置推送证书的位置为：
  - iOS: [[NIMSDK sharedSDK] registerWithAppID:你的APPKEY cerName:你的推送证书名称];
  - Android: 点此查看
关于推送证书更换
- 更换证书时，先删除云信控制台的旧证书，再添加新证书。新旧证书必须保持相同的证书名称。
- 新证书半小时内生效，期间可以继续使用旧证书推送。证书更换是平滑的，例如对于Apple来说，旧证书过期之前，新旧两本证书都是有效的。但是仍然建议在业务低峰期更换证书。
- 云信后台对推送证书数量有限制，具体限制为：iOS+Android推送证书的数量最多为5000本。
关于iOS推送证书的过期提醒
- 网易云信服务器每月都会检测开发者上传到网易云信控制台的iOS推送证书的有效期，如果过期时间在当前时间+62天的范围内，会收到邮件和短信提醒。
- 可以通过控制台概览页面的「信息接收管理」功能，编辑「证书相关通知」的「订阅信息接收人」来「新增信息接收人」(默认仅通知主账号，即注册账号)。
- 也可以查看控制台「应用」(选择应用) - 证书管理 - iOS推送证书 或 iOS PushKit推送证书 - 「证书有效期/有效期剩余时间」。
关于华为推送的指纹证书

使用华为推送，还需要在华为后台配置正确的指纹证书，否则SDK日志会报错，类似于：[ui]mix_push: HuaweiApiClient onConnectionFailed, result=907135702

华为推送的SercetKey对应云信控制台配置证书时的AppSecret，SercetKey可参考获取华为应用的AppID和AppSecret
关于魅族推送的AppId和AppKey

获取方法：魅族集成推送服务（注意：不是Flyme推送服务） - 推送后台 - 选择你的应用（若无应用请新建应用） - 打开应用 - 配置管理 - 应用配置 - 渠道（若无渠道请添加多渠道） - App ID/App Key
关于Google FCM的AppSecret

在云信控制台添加Google FCM推送证书时，需要填写AppSecret，获取方法：
Firebase控制台/Console > 点击你的项目/Project > 点击(左上角Project Overview右边的)齿轮/Settings > 项目设置/Project settings > 点击「云消息传递/ Cloud Messaging」 > 页面中显示的「服务器密钥/Server Key」即为所需的AppSecret。
关于OPPO推送的MasterSecret

在云信控制台添加OPPO推送证书时，需要填写MasterSecret，获取方法：OPPO推送运营平台 > 配置管理 > 应用配置 > MasterSecret。

关于APNs合并推送通知
背景介绍
- APNs支持合并推送通知，当请求头中存在apns-collapse-id键时，APNs会合并键值相同的请求。
- 网易云信从2020年3月11日发布的7.4.0版本开始支持该功能。
- 开发者可以基于该功能，在消息对象的payload中设置键apns-collapse-id，并传入消息ID等uuid做为值，实现推送内容覆盖。
示例场景

在撤回消息时配置与原消息相同的apns-collapse-id值，以合并原消息产生的推送通知。
示例代码：``` NSDictionary *payload = @{@"apns-collapse-id": message.messageId}; [[NIMSDK sharedSDK].chatManager revokeMessage:message apnsContent:@"撤回" apnsPayload:payload shouldBeCounted:... completion:...];
```
除消息撤回以外，所有支持`payload`参数的情况下，例如发送消息等，都可以相应配置。  
**\[注意\]** Web SDK比较特殊，因为消息发送后才会生成消息ID，所以对于Web发送消息的场景，开发者需在发送前设置uuid等作为键值。
```
相关链接
- 关于消息撤回接口，请点此查看。
- 关于payload等IM推送参数，请点此查看。

Android推送问题排查

检查打包和设备配置
- 只有签名发布包(Signed)才可以收到推送，不要尝试用测试包接收推送。
- 检查设备是否配置允许应用推送通知。
  - 以小米手机MIUI 10.0为例：设置 > 通知和状态栏 > 通知管理 > 选择应用 > 允许通知。
  - 以华为手机EMUI 9.1.0为例：设置 > 通知中心 > 选择应用 > 允许通知。
- 安装网易云信官方即时通讯Demo进行对比，查看Demo是否可以收到推送。
如果已经正确配置允许通知，并且Demo可以收到推送，那么请继续按后文排查。
厂商推送SDK版本
- 开发者集成推送功能时，除了导入网易云信提供的 basesdk 和 push 包之外，还需要导入各系统厂商的推送SDK，并且请特别注意，网易云信SDK对于系统厂商的推送SDK是有版本要求的，具体内容请查看不同厂商推送文档。
- 如果使用非指定的版本，将出现无法推送的情况甚至可能造成应用崩溃，例如出现下列报错：
  java.lang.ClassCastException: com.xxx.pushservice.MessageReceiver cannot be cast to com.netease.nimlib.sdk.mixpush.VivoPushMessageReceiver
代码接入
- 网易云信推送，使用的是系统厂商的推送通道，因此接入云信推送后，不需要再重复接入系统厂商的推送。如果开发者自身业务中确实需要同时接入系统厂商推送，请查看开发指南页面介绍的「推送兼容性配置」。
- 检查SDK日志中是否生成推送token
  获取SDK日志的方法请单击查看。
  如果正确集成，SDK日志中会打印token记录，请单击查看「关于推送的token」部分介绍的示例。
  如果没有生成推送token，请根据开发指南页面介绍的「接入流程」检查核对。
SDK其它日志片段
- [ui]mix_push: check Google Play Service status = 2
  集成Google FCM推送时，此处表示检查Google Play服务状态：-1 默认值、0 缺失服务、1 服务不可用、2 服务可用
- [ui]InvocationMgr: execution result: Transaction: [id: 4, method: MixPushService/enable, result: 1]
  其中，result表示推送开启出错：
  1: 当前未在线，无法操作
  2: 当前不支持的操作
  3: 注册第三方推送SDK获取token失败
证书配置

请单击查看。
系统厂商推送错误码
- 小米
- 华为
- 魅族
- VIVO
- OPPO
- 服务端错误码参考
- 通用错误码。例如，SDK日志记录[ui]mix_push: HuaweiApiClient onConnectionFailed, result=6003，查询华为文档，6003表示证书指纹校验：证书指纹错误，处理方式请点击上方链接查看华为文档。
- 推送接入文档页面、Api returnCode定义。
- 错误码参考
- 服务端API - 下载页面、服务端API - 公共返回码定义、SDK接口文档 - 错误码定义说明。
其它注意事项

对于Google FCM，通知消息默认是高优先级，系统可能会在收到第一条推送后自动从后台唤醒app，导致不能再继续接收消息推送。
- 8.6.2版本以下：SDK会先查看是否有配置厂商推送，如果有就走厂商推送，如果没有，再去尝试获取fcm的token，如果获取成功，再去走fcm的推送。如果清除数据或者重装后，会优先根据服务端后台的选项去走，如果是FCM则走FCM。注意：如果清除数据或者重装后，服务端后台选择的是厂商推送，那在此之后切换成FCM推送后也会一直走厂商推送。
- 8.6.2版本及以上：会一直根据云信后台的选择去优先选择通道。
对于oppo推送：

集成2.1.0及以上的oppo推送SDK的时候，如果没有在application的oncreate配置com.heytap.msp.push.HeytapPushManager.init(this, true);的初始化代码，会提示java.lang.NullPointerException: Attempt to invoke virtual method 'android.content.pm.PackageManager android.content.Context.getPackageManager()' on a null object reference
集成oppo推送SDK的时候，对应的在云信后台配置的secret需要配置oppo推送的mastersecret的值，mastersecret的获取参考OPPO开放平台消息推送申请教程。
其它推送问题

A账号登录后，下载新包覆盖安装（新包的appkey已经更换），B再登录该设备，还能收到推送给A的消息。
原因：用户没改包名导致安卓厂商的推送token是一致的，但是对于云信是两个应用所以都推送。解决方法：登出A账号后再安装或者修改应用不同包名。

Android通知栏提醒相关问题
启动时收到通知栏提醒，但是没有未读数

当SDK启动时，如果收到了漫游消息，根据设置可能触发通知栏提醒，但是漫游消息是已读消息，所以没有未读数。
关于漫游消息，另请点此查看。
即时通讯Android Demo在启动时调用NIMClient.getService(MsgService.class).setChattingAccount(MsgService.MSG_CHATTING_ACCOUNT_ALL, SessionTypeEnum.None)来清除通知栏提醒。
通知栏非折叠状态，收到N条提醒，点击其中一条，其余N-1条也消失了
- 点击该条通知栏提醒之后，如果开发者业务层调用了SDK MsgService中clearUnreadCount或者clearAllUnreadCount接口，SDK会调用Android系统API，清除应用的所有通知栏提醒。
- 如果没有调用上述接口，则取决于系统行为，有些手机的操作系统会自动清理该应用其它提醒。
通知栏折叠状态，通过系统界面清除通知栏提醒后，通知条数不对

通知栏折叠状态，如果app此时对应的通知栏提醒显示为N条，然后通过系统界面清除了app对应的通知栏提醒(注意是清除通知栏而不是点击通知栏)，或者一键清除了所有应用的通知栏提醒之后，再收到一条新的消息提醒时，通知栏提醒会显示为N+1条，而不是1条。
这是因为通过系统界面清除通知栏提醒时，系统不会通知app，所以app/SDK无法感知和处理。
只有当下次点击通知栏打开app后，并且开发者调用了SDK MsgService中setChattingAccount、clearUnreadCount、clearAllUnreadCount等方法清除通知栏提醒的情况下，才会恢复正常。
关于UserInfoProvider接口

开发者可以实现UserInfoProvider接口来处理通知栏显示的头像和名称。该接口具有以下方法：
- getAvatarForMessageNotifier方法：为通知栏提醒提供头像
- getDisplayNameForMessageNotifier方法：为通知栏提醒提供消息发送者的显示名称
具体的接口说明请查看API文档，示例代码请下载即时通讯Demo源码，查看 NimUserInfoProvider.java 文件。
登录后不断收到通知栏消息提醒

账号登录成功后，SDK会自动同步离线消息。在7.4.0(不含)之前的版本中，每条离线消息都会触发通知栏消息提醒，如果离线消息较多，就会不断收到消息提醒。
从2020年3月9日发布的7.4.0版本开始，SDK进行了优化，对于离线情况下被推送过的消息，在线时不会再触发消息提醒通知栏，因此请升级到最新版本SDK。

Android推送配置简介
主要配置流程

第三方推送的主要配置流程：
- 流程一、配置AndroidManifest.xml
- 流程二、配置推送证书等信息
  1. 初始化mixPushConfig对象并配置相关参数
  2. 将上一步的mixPushConfig对象作为SDKOption的mixPushConfig参数
  3. SDK初始化时将SDKOption对象作为参数传入

流程二步骤1的配置示例

以下介绍各种推送流程二步骤1的主要配置(摘自官网即时通讯Demo源码)。``` private static MixPushConfig buildMixPushConfig() { // 第三方推送配置 MixPushConfig config = new MixPushConfig();

// 小米推送
config.xmAppId = "xxxxxx";
config.xmAppKey = "xxxxxx";
config.xmCertificateName = "xxxxxx";

// 华为推送
config.hwAppId = "xxxxxx";
config.hwCertificateName = "xxxxxx";

// 魅族推送
// \[注意\] 请使用魅族推送后台「渠道」中的AppId和AppKey，详请查看：https://faq.yunxin.163.com/#KB0074
config.mzAppId = "xxxxxx";
config.mzAppKey = "xxxxxx";
config.mzCertificateName = "xxxxxx";

// 谷歌FCM推送 (只适用于海外网络)
config.fcmCertificateName = "xxxxxx";

// VIVO推送
config.vivoCertificateName = "xxxxxx";  // VIVO推送的api\_key和app\_id在AndroidManifest.xml中配置

// OPPO推送
config.oppoAppId = "xxxxxx";
config.oppoAppKey = "xxxxxx";
config.oppoAppSercet = "xxxxxx";
config.oppoCertificateName = "xxxxxx";

return config;

}

注意事项

调用NIMClient.getService(MixPushService.class).enable(true).setCallback(...)开启推送，调用NIMClient.getService(MixPushService.class).enable(false).setCallback(...)关闭推送。

关于IM提供的推送配置apsField字段 [注意1] 开发者无法在推送参数payload中配置aps字段，IM提供推送配置payload - apsField字段，对应APNs的payload - aps字段。
该字段仅适用于iOS接收，Android无法解析此字段。
下面展示通过IM配置的带有apsField字段的payload示例代码：``` { "key1": "value1", "apsField": { "mutable-content": 1, "sound": "abc.wav", "alert": { "title": "推送标题", "body": "推送内容" }, "key2": "value2" } }

**\[注意2\]** 上述示例代码出于展示目的进行了格式化，实际发送的时候不要进行格式化，例如Web端发送，应参考配置：`pushPayload: '{"key1": "value1", "apsField": {"mutable-content": 1, "sound": "abc.wav", "alert": {"title": "推送标题", "body": "推送内容"}, "key2": "value2"}}'`  
上述示例代码发送后，会被IM服务器转换为：```
 {     "nim": "1",     "key1": "value1",     "aps": {         "alert": {             "title": "推送标题",             "body": "推送内容"         },         "badge": 1,         "sound": "abc.wav",         "mutable-content": 1,         "key2": "value2"     } }

[注意3] 一旦配置了apsField的alert字段，那么APNs将以此配置显示，而忽略IM配置参数中推送标题和推送文案。特别地，如果配置了apsField的alert字段，但是title为空或没有配置将没有推送标题，body为空或没有配置将没有推送文案，两者都为空或都没有配置则推送标题和推送文案都没有。
[注意4] apsField中可以配置badge字段来控制角标数字（不影响会话未读数）。例如配置："apsField": { "badge": 0 }，在iOS收到这条推送后，会重置之前已经累计的角标，并将其设置为0（0为示例，开发者可以按需设置任意数字）。

关于自定义推送文案 [注意] 此功能需要联系商务顾问申请开通后才能正常使用。
如果开发者配置了「不显示推送详情」(配置方法请见下面"客户端配置")，默认的推送文案是：“你收到一条新消息”。
这种情况下，开发者还可以自定义推送文案(例如基于系统语言等场景)。

配置自定义推送文案的内容

登录云信控制台 - 选择应用 - 证书管理 - 自定义推送文案
可以配置最多 100 种自定义文案，每种自定义文案用一个自定义类型来标识。
[注意] 当客户端配置为「不显示推送详情」时，自定义推送文案才会生效。
客户端配置
- Android
- iOS
- - 设置SDKOptions - statusBarNotificationConfig - hideContent为true表示不显示推送详情。
  - 设置SDKOptions - customPushContentType来指定需要使用的自定义推送文案类型。传入空字符串取消设置。
  - 调用NIMClient.init(Context context, LoginInfo info, SDKOptions options)或者NIMClient.config(Context context, LoginInfo info, SDKOptions options)时，传入设置后的SDKOptions对象。
- - NIMPushNotificationSetting对象的type属性设置为NIMPushNotificationDisplayTypeNoDetail表示不显示推送详情。调用[NIMSDK sharedSDK] apnsManager的– updateApnsSetting:completion:方法来更新推送设置。
  - 调用[NIMSDK sharedSDK]的– updateApnsToken:customContentKey:方法来指定需要使用的自定义推送文案类型，传入空字符串取消设置，传入nil表示不进行更改。
  Android SDK怎么定制通知栏提醒文案 [注意1] 以下提到的内容，都是指app存活期间收到消息进行通知栏提醒。如果app被系统回收，则属于系统推送，不适用于下列内容。
  [注意2] 关于以下提到的3种方式，还可以参考开发指南，打开该链接页面后，搜索：接收消息时定制提醒内容。
  Android SDK通知栏提醒文案显示的优先级如下：
发送方配置的推送文案

如果发送方配置了消息的推送文案，那么通知栏提醒将显示该推送文案。关于推送文案的配置，请点此查看。
Android是否实现MessageNotifierCustomization接口

SDK会在收到消息时回调MessageNotifierCustomization接口，开发者可以根据昵称和消息来定制提醒文案。
默认的提醒文案

Android SDK提供NimStrings类，用于开发者定制默认的新消息通知栏提醒文案，以及对应的多语言支持。
具体使用方式，可以参考：即时通讯Demo > NIMInitManager.java > updateLocale方法 > 配置的NimStrings相关字段。
注意调用NIMClient.updateStrings(NimStrings strings)方法来更新文案配置。
具体的文案字符串定义在：res > values > strings > strings.xml中(Demo配置了中文和英文两种语言示例)。
关于Android支持不同语言的配置，另请参考Android官方文档。

iOS推送问题排查在开发集成过程中，如果遇到使用网易云信iOS SDK无法收到APNs推送的情况，请查看下列介绍。
原理介绍

经由网易云信实现APNs推送的过程如下：
- 开发者app配置为注册APNs的情况下，当app启动时，会将Bundle Identifier发送给Apple服务器，返回deviceToken给app，回调-application:didRegisterForRemoteNotificationsWithDeviceToken:系统方法。
- 当开发者代码调用–updateApnsToken:或–updateApnsToken:customContentKey:方法时，SDK会将证书名称、deviceToken等传递给网易云信服务器(服务器会通过登录的accid识别出对应的AppKey)。
- 网易云信服务器根据开发者配置的Bundle Identifier、deviceToken、证书名称、证书环境，将相应信息发送给Apple服务器。
- Apple服务器将消息推送到deviceToken对应的设备上。
SDK版本

确保使用最新版本SDK，以免过旧的版本尚未适配最新iOS系统。例如，iOS13更改了DeviceToken的格式，6.9.0版SDK开始兼容。
SDK的最新版本可点此查看。
证书制作与上传

请点此查看开发指南中关于创建推送证书、导出证书文件、上传证书到网易云信控制台(以下简称控制台)等步骤的相关介绍。
此步骤的相关注意事项：
- 上传的推送证书文件大小应为3K左右，如果差异较大，请检查核对相应步骤。建议您上传证书前，先将其安装到本地MAC，在钥匙链里查看，检查bundleID是否正确，如果证书bundleID与实际打包的应用bundleID不对应，苹果服务器会返回400。
- 开发者代码中初始化SDK时，在NIMSDKOption中配置的两个参数：
  - appKey参数必须和控制台「证书管理」页面显示的「App Key」一致。
  - apnsCername参数必须和控制台「iOS推送证书」中填写的「证书名称」一致。
- 客户端运行环境必须和控制台对应证书选择的「证书环境」一致
  xcode直接跑的是测试环境，打包成adhoc或者上线appstore的是生产环境
- [注意] Xcode - 你的工程 - Signing & Capabilities，必须添加Push Notifications。
推送条件

当app在前台运行时，是不会触发推送的。测试通过网易云信进行APNs推送时，请先登录IM账号成功后，将app切换到后台，或者杀死app，或者锁屏，才会触发推送。
利用第三方推送工具测试 token 和证书的有效性（需要MacOS）
下载安装Knuff
补充说明

目前云信控制台 iOS APNS P12/P8 推送证书区分了正式环境和测试环境。但 P12 的正式环境的证书是可以用于测试环境的，如果用户只申请一个正式环境的证书上传至云信控制台，云信目前还不支持上传一个证书支持不同环境的推送，就有可能出现用户上传选择的环境正常，另外一个环境推送失败的疑问。此时可以再次上传同一个证书选择另一个环境或者再申请另外测试环境的证书上传，注意，证书名称不能一样，用户可以自己在代码做区分不同环境。
注：1、P8 的证书不区分正式环境和测试环境，同一个开发者帐号可以使用不同的环境和不同的 APP。
2、证书有效期大致为 1 年。
请求协助

如果经过上述步骤，仍然无法定位到问题原因，请提交工单并提供下列信息给技术支持以便协助分析：
应用AppKey、消息收发双方的accid、消息发送时间、控制台iOS推送证书信息(截图)、项目代码中配置的appKey和apnsCername参数(截图)、Pusher测试截图。

关于IM推送的主要配置参数目前IM关于推送的配置参数较多，主要参数有：推送文案(推送内容)、推送前缀(昵称)、payload。各端对应的属性如下。
[注意1] 如果消息发送者未设置昵称，即使配置了推送前缀(昵称)选项，推送也是无法携带昵称的。
[注意2] 除了下表内容外，另请注意查看表格后面的各项说明。

	Server	Windows (C)	Android
IMMessage	iOS
NIMMessage	Web
是否推送	option字段push	kNIMMsgKeyPushEnable = "push_enable"	CustomMessageConfig
属性enablePush	NIMMessageSetting
属性apnsEnabled	isPushable
推送文案
(推送内容)	pushcontent	kNIMMsgKeyPushContent	setPushContent(String pushContent)	apnsContent	pushContent
payload	payload	kNIMMsgKeyPushPayload	setPushPayload(Map pushPayload)	apnsPayload	pushPayload
推送前缀
(昵称)	option字段needPushNick	kNIMMsgKeyNeedPushNick	enablePushNick	NIMMessageSetting
属性apnsWithPrefix	needPushNick

推送文案
推送标题
payload
apsField
- 开发者可以通过IM的"推送文案"来指定APNs的推送内容。
  例如，在服务端API中配置pushcontent为“测试信息”，则iPhone收到的推送内容为：“昵称：测试信息”。
  如果配置了needPushNick为false（表示不需要推送前缀/昵称），则iPhone收到的推送内容为：“测试信息”。
- 如果开发者没有配置推送文案，则默认的推送文案为：
  - 文本消息：显示文本消息具体内容
  - 图片消息：发来了一张图片
  - 语音消息：发来了一段语音
  - 视频消息：发来了一段视频
  - 地理位置消息：发来了一个地理位置
  - 文件消息：发来了一个文件
  - 自定义消息：你收到一条新消息
  - 音视频通话：一条来电
- 如果开发者配置了「不显示推送详情」，默认的推送文案是：“你收到一条新消息”。这种情况下，还可以自定义推送文案，详细内容请点此查看。
- 当您调用https://api.netease.im/nimserver/msg/sendMsg.action发送自定义消息或者文本消息的时候，如果body字段里面配置了msg字段，那么在没有配置pushcontent和payload的推送文案的情况下，推送文案的内容会被替换成msg字段的内容。
  示例：body字段传参{msg:"111999",tt:"1232131"}，并且没有配置pushcontent和payload的情况下，接收方的推送文案会替换成111999。
- 对于iOS：
  - 如果配置了apsField - alert，则以其中的title字段显示推送标题(优先级最高)。
  - 如果没有在apsField中配置，但是通过payload配置了"pushTitle": "标题内容"，则以此显示。
  - 如果都没有配置，则不会显示推送标题。
- 对于Android：
  - Android推送会忽略apsField字段。
  - 如果通过payload配置了"pushTitle": "标题内容"，则以此显示(优先级最高)。
  - 如果没有配置，则点对点消息推送标题为用户昵称，群消息推送标题为群名称。
    [注意1] 如果用户资料没有设置昵称，或者即使有昵称但是设置了不需要推送前缀(昵称)，则点对点消息推送标题为新消息。
    [注意2] 如果发送的是自定义系统通知，即使有昵称，推送通知栏显示的标题也为新消息，建议设置pushTitle。
- 该参数与APNs的payload含义不同，是网易云信定义的JSON对象，可以用来配置推送铃声(通过sound字段配置)、推送标题(通过pushTitle字段配置)，以及开发者自定义的键值对。如果传入任何Apple预留的key，例如aps、alert、title、badge等，都会被IM服务器丢弃。
  [注意] 根据Apple官方文档，推送铃声只支持aiff、wav、caf这3种文件格式，Apple不支持aac、mp3等格式）
- Android端支持配置payload字段传入空的JSON字符串(即：{})，其它端不支持。
- 根据小米推送自身的推送限制，payload的json字段里面最多包含10个自定义的字段内容。
正如前面在payload部分提到的，IM推送的payload参数与APNs的payload参数含义不同，开发者无法在IM推送的payload中配置aps字段，IM提供一个对应的apsField字段。
也就是说，IM推送的payload - apsField字段，对应APNs的payload - aps字段。详细内容请点此查看。

关于强制推送群消息支持设置强制推送(以下简称强推)，例如@功能。
强推的优先级最高，设置强推后，即使关闭消息提醒，或者打开了免打扰设置，或者设置了桌面端在线时不推送，仍然会收到通知栏提醒(但是声音和振动跟随本机设置不受强推影响)。
可以在强推列表设置需要强推的群成员，并为其设置专用的强推内容/文案(不在强推列表的群成员将收到普通推送，如果不设置强推内容则和普通推送内容一致)。
[注意1] 客户端如果设置了需要强推，但是强推列表为空，则表示对群内所有成员强推(当然发送者除外)。
[注意2] 如果在系统层面设置了不允许应用通知，或者通过SDK接口NIMClient.getService(MixPushService.class).enable(false).setCallback(...)关闭了推送，则无法收到任何推送通知(包括普通推送和强推)。

以下为发送群消息时，各端配置项介绍。

Server
Windows (C)
Android
iOS
Web
调用https://api.netease.im/nimserver/msg/sendMsg.action「发送普通消息」时，forcepushall表示对群内所有成员强推，forcepushlist表示指定强推列表，forcepushcontent表示强推内容。
发送消息时，通过kNIMMsgKeyIsForcePush字段设置是否强推，kNIMMsgKeyForcePushList字段设置强推列表，kNIMMsgKeyForcePushContent字段设置强推内容。详细介绍请单击查看。
通过MemberPushOption的setForcePush(boolean forcePush)方法设置是否强推，通过其setForcePushList(List<String> forcePushList)方法设置强推列表，通过其setForcePushContent(String forcePushContent)方法设置强推内容。
再通过IMMessage对象的setMemberPushOption(MemberPushOption pushOption)方法将上述强推选项配置到消息上，代码示例请单击查看。
通过NIMMessageApnsMemberOption的forcePush字段设置是否强推，userIds字段设置强推列表，apnsContent字段设置强推内容。再通过NIMMessage对象的apnsMemberOption字段将上述强推选项配置到消息上，详细介绍请单击查看。
发送消息时，通过apns.forcePush属性设置是否强推，apns.accounts属性设置强推列表，apns.content属性设置强推内容。详细介绍请单击查看。
强推所有人写法如下：``` var msg = nim.sendText(\{ scene: 'team', to: 'xxxx', text:'hello', apns:\{ content:"有人@你", forcePush:true }, done: sendMsgDone });
```
关于Android通知栏的点击跳转 app存活时，IM消息可以经由SDK触发通知栏消息提醒(称为SDK内置消息提醒)。  
```

app被系统回收后，IM消息只能通过设备厂商的推送触发通知栏消息提醒。

SDK内置消息提醒
Google FCM推送
其它推送
可以通过StatusBarNotificationConfig的notificationEntrance参数来设置通知栏提醒的响应Intent的Activity，通过NIMClient.updateStatusBarNotificationConfig(StatusBarNotificationConfig config)来更新通知栏消息提醒设置。
对于即时通讯Demo来说，存在以下逻辑：
- 在NimApplication.java中调用了NIMClient.init(..., ..., NimSDKOptionConfig.getSDKOptions(this))
- 在NimSDKOptionConfig.java的getSDKOptions(Context context)中调用了initStatusBarNotificationConfig(options)
- 在initStatusBarNotificationConfig(SDKOptions options)中配置了StatusBarNotificationConfig config = loadStatusBarNotificationConfig()
- 在loadStatusBarNotificationConfig()中配置了config.notificationEntrance = WelcomeActivity.class
- 在WelcomeActivity.java的onIntent中判断if (intent.hasExtra(NimIntent.EXTRA_NOTIFY_CONTENT))调用parseNotifyIntent(intent)，具体代码请参考Demo。
  [注意] 关于EXTRA_NOTIFY_CONTENT的含义请参考API文档。
- 请参考Android开发指南 - 谷歌推送FCM。
- 即时通讯Demo中，在WelcomeActivity.java的onIntent中判断if (NIMClient.getService(MixPushService.class).isFCMIntent(intent))，具体代码请参考Demo。
- 国内厂商推送(除OPPO外)，点击通知栏会触发SDK回调(MixPushMessageHandler - onNotificationClicked(context, payload))。
  - 开发者如需自定义推送时的通知栏点击跳转行为，请参考Android开发指南 - 第三方推送自定义接口，实现MixPushMessageHandler接口，在onNotificationClicked(Context context, Map<String, String> payload)中实现自己的代码逻辑并return true，详细内容请参考开发指南页面介绍。
  - 示例代码请参考即时通讯Demo的DemoMixPushMessageHandler.java。按照Demo的配置，如果配置了StatusBarNotificationConfig的notificationEntrance参数，则跳转到配置的Activity；如果没有配置，则跳转到app的LAUNCHER Activity。
  - 关于payload等推送参数配置，请点此查看。
- 如果开发者没有实现该接口，则默认行为如下：``` Intent notifyIntent = new Intent(); notifyIntent.setComponent(getComponent(context)); notifyIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_SINGLE_TOP); notifyIntent.setAction(Intent.ACTION_VIEW); notifyIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); context.startActivity(notifyIntent);
```
关于消息提醒和推送的区别 消息提醒走SDK内置的消息提醒模块，而推送则是走厂商的推送通道，如Android推送是走华为、vivo、oppo、小米、FCM等通道，iOS推送是APNS。  
```

消息提醒触发时机：

Android：应用进程在存活的情况下，应用退后台或者收到非当前会话的消息会触发消息提醒。
iOS：没有消息提醒。

推送触发时机：

Android：应用被杀死的情况。
iOS：应用退后台或被杀死。

iOS 收到推送时，角标badge数值显示逻辑云信服务器会记录角标 badge 数值，不支持发消息的时候携带 badge（带了badge，云信服务器也不会使用）。
1、APP 后台运行或杀进程后，收到推送时角标会 +1。如果某些会话设置了免打扰，这些会话的消息不会收到推送，对应的角标也不会增加。
2、APP 打开后，SDK 同步免打扰会话的未读数给云信服务器，此时云信服务器记录的badge 数值也会加上免打扰会话的未读数。即 APP 打开后，云信服务器的角标 badge 数值 = APP 总未读数。
3、APP 再次后台运行或杀进程后，再次收到推送，角标数值会从总未读数 +1 进行显示。
举例说明：
1、APP 后台运行或杀进程后，收到正常推送 5 条，免打扰 5 条，此时显示角标 badge = 5。
2、APP 打开后，云信服务器记录的 badge 数值：5 + 5 = 10。 3、APP 再次后台运行或杀进程后，再次收到一条推送，此时显示角标 badge：10 + 1 = 11。
默认逻辑下，使用下面方法设置角标 badge 数值不再包含免打扰会话的未读数。
1、调用[[[NIMSDK sharedSDK] conversationManager] allUnreadCount:YES];获取不包含免打扰会话的未读数。
2、调用[[[NIMSDK sharedSDK] apnsManager] registerBadgeCountHandler:^NSUInteger{ return allUnreadCount;}];修改云信服务器的角标 badge 数值。

安卓推送报错：query token with exception must not refer to a null object 可能原因：没有在 Application 主进程里面注册推送。
解决方法：建议检查下推送 SDK 的初始化时机，也可以参考 Demo 示例代码。

【角标】华为角标配置方法华为推送文档里是有专门的推送字段控 add_num 制角标数的。
需要先在云信的管理后台配置推送证书时，设好入口 Activity，然后发送方发消息时，pushPayload 的信息可以设置为 { // 华为推送，可以自定义 https://developer.huawei.com/consumer/cn/doc/development/HMS-References/push- sendapi#androidnotification 中的参数 "hwField":{ "badge": { "add_num": 1, "class": "com.huawei.codelabpush.MainActivity", "set_num": 10 }, "title":"friend", "body":"heolo" } }

华为推送返回 6003 code 码如果推送日志中出现query token with exception 6003: certificate fingerprint error，可能原因如下：

指纹证书配置不一致
检查方法：https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/android-config-agc-0000001050170137
没有清掉数据缓存

如果以上两个方法还是无法处理6003报错，需要用adb logcat ->push.log
如果看到如下报错
需要查看json文件是否放入正确位置

如果已经正确配置还是报错，需要看下build.gradle中 apply plugin: 'com.huawei.agconnect'是否有配置

关于单个用户推送不可达问题排查如果其他账号推送正常，只是个别账号推送异常可能原因是：
1，两个账号是否是好友关系，控制台是否有设置非好友关系是否允许发送消息。
2，双方是否有拉黑情况。
3，接收方是否有设置发送免打扰，如果是强制推送的情况下可忽略。

在线咨询

微信咨询

电话咨询

此文档是否对你有帮助？

有帮助

去反馈

触发消息推送的条件
推送相关信息
关于推送的token
关于推送证书名称
关于推送证书更换
关于iOS推送证书的过期提醒
关于华为推送的指纹证书
关于魅族推送的AppId和AppKey
关于Google FCM的AppSecret
关于OPPO推送的MasterSecret
检查打包和设备配置
厂商推送SDK版本
代码接入
SDK其它日志片段
证书配置
系统厂商推送错误码
其它注意事项
其它推送问题
启动时收到通知栏提醒，但是没有未读数
通知栏非折叠状态，收到N条提醒，点击其中一条，其余N-1条也消失了
通知栏折叠状态，通过系统界面清除通知栏提醒后，通知条数不对
关于UserInfoProvider接口
登录后不断收到通知栏消息提醒
主要配置流程
流程二步骤1的配置示例
注意事项
配置自定义推送文案的内容
客户端配置
发送方配置的推送文案
Android是否实现MessageNotifierCustomization接口
默认的提醒文案

触发消息推送的条件

推送相关信息

关于推送的token

关于推送证书名称

关于推送证书更换

关于iOS推送证书的过期提醒

关于华为推送的指纹证书

关于魅族推送的AppId和AppKey

关于Google FCM的AppSecret

关于OPPO推送的MasterSecret

检查打包和设备配置

厂商推送SDK版本

代码接入

SDK其它日志片段

证书配置

系统厂商推送错误码

其它注意事项

其它推送问题

启动时收到通知栏提醒，但是没有未读数

通知栏非折叠状态，收到N条提醒，点击其中一条，其余N-1条也消失了

通知栏折叠状态，通过系统界面清除通知栏提醒后，通知条数不对

关于UserInfoProvider接口

登录后不断收到通知栏消息提醒

主要配置流程

流程二步骤1的配置示例

注意事项

配置自定义推送文案的内容

客户端配置

发送方配置的推送文案

Android是否实现MessageNotifierCustomization接口

默认的提醒文案