消息提醒

集成网易云通信 Android SDK 的 APP 运行起来时,会有个后台进程(push 进程),该进程保持了与网易云通信 Server 的长连接。只要这个 push 进程活着(网易云通信提供安卓保活机制),就能接收网易云通信 Server 推过来的消息,进行通知栏提醒。

消息提醒场景

1. APP 在后台时。

2. 在前台与 A 聊天但收到非 A 的消息时(与 iOS 不一样)。

3. 在非聊天界面且非最近会话界面时。

1. 如果用户正在与某一个人聊天,当这个人的消息到达时,是不应该有通知栏提醒的。

2. 如果用户停留在最近联系人列表界面,收到消息也不应该有通知栏提醒(但会有未读数变更通知)。

网易云通信 SDK 提供内置的消息提醒功能,如需使用,开发者需要在进出聊天界面以及最近联系人列表界面时,通知 SDK。相关接口如下:

// 进入聊天界面,建议放在onResume中
NIMClient.getService(MsgService.class).setChattingAccount(account, sessionType);

// 进入最近联系人列表界面,建议放在onResume中
NIMClient.getService(MsgService.class).setChattingAccount(MsgService.MSG_CHATTING_ACCOUNT_ALL, SessionTypeEnum.None);

// 退出聊天界面或离开最近联系人列表界面,建议放在onPause中
NIMClient.getService(MsgService.class).setChattingAccount(MsgService.MSG_CHATTING_ACCOUNT_NONE, SessionTypeEnum.None);

内置消息提醒定制

网易云通信 SDK 提供内置的消息提醒(通知栏提醒)功能。

开关通知栏消息提醒

只有 StatusBarNotificationConfig 配置不为空时才有效。

/**
 * 通知栏消息提醒开关控制。只有StatusBarNotificationConfig配置不为空时才有效
 *
 * @param on 开关
 */
public static void toggleNotification(boolean on);
// 开启/关闭通知栏消息提醒
NIMClient.toggleNotification(enable);

更新本地通知栏消息提醒配置(不可漫游)

/**
 * 更新状态栏通知提醒设置
 *
 * @param config 设置
 */
public static void updateStatusBarNotificationConfig(StatusBarNotificationConfig config);
StatusBarNotificationConfig 参数 说明
notificationSmallIconId 状态栏提醒的小图标的资源ID。
如果不提供,使用 app 的 icon
ring 是否需要响铃提醒。
默认为 true
notificationSound 响铃提醒的声音资源,如果不提供,使用系统默认提示音
vibrate 是否需要振动提醒。
默认为 true
ledARGB 呼吸灯的颜色。
建议尽量使用绿色、蓝色、红色等基本颜色,不要去用混合色
ledOnMs 呼吸灯亮时的持续时间(毫秒)
ledOffMs 呼吸灯熄灭时的持续时间(毫秒)
hideContent 不显示消息详情开关。
默认为 false
downTimeToggle 免打扰设置开关。默认为关闭
downTimeBegin 免打扰的开始时间, 格式为HH:mm(24小时制)。
downTimeEnd 免打扰的结束时间, 格式为HH:mm(24小时制)。
如果结束时间小于开始时间,免打扰时间为开始时间-24:00-结束时间。
notificationEntrance 通知栏提醒的响应intent的activity类型。
可以为null。如果未提供,将使用包的launcher的入口intent的activity。
titleOnlyShowAppName 通知栏提醒的标题是否只显示应用名。
默认是 false,当有一个会话发来消息时,显示会话名;
当有多个会话发来时,显示应用名。
修改为true,那么无论一个还是多个会话发来消息,标题均显示应用名。
应用名称请在 AndroidManifest 的 application 节点下设置 android:label
notificationFolded 消息通知栏展示样式是否折叠。默认是true,这样云信消息端内消息提醒最多之占一栏。
由于端外推送消息为展开模式,可以设置为false达到端内、端外表现一致。
notificationColor 消息通知栏颜色,将应用到 NotificationCompat.Builder 的 setColor 方法。
对Android 5.0 以后机型会影响到smallIcon
// 更新消息提醒配置 StatusBarNotificationConfig,以设置不响铃为例。
StatusBarNotificationConfig config = UserPreferences.getStatusConfig();
config.ring = false;
NIMClient.updateStatusBarNotificationConfig(config);

StatusBarNotificationConfig 中的notificationEntrance 字段指明了点击通知需要跳转到的Activity,Activity启动后可以获取收到的消息:

ArrayList<IMMessage> messages = (ArrayList<IMMessage>)
getIntent().getSerializableExtra(NimIntent.EXTRA_NOTIFY_CONTENT); // 可以获取消息的发送者,跳转到指定的单聊、群聊界面。

个人消息提醒配置(支持漫游)

支持对用户开启或关闭消息提醒,关闭后,收到该用户发来的消息时,不再进行SDK内置的通知栏消息提醒。

/**
 * 设置消息提醒/静音
 *
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用,如果出错,会有具体的错误代码。
 */
InvocationFuture<Void> setMessageNotify(String account, boolean notify);
参数 说明
account 要设置消息提醒的帐号
notify 是否提醒该用户发来的消息,false 为静音(不提醒)
// 以不接收testAccount帐号消息为例
NIMClient.getService(FriendService.class).setMessageNotify("testAccount", false).setCallback(new RequestCallback<Void>() {});

群消息提醒配置(支持漫游)

群聊消息提醒可以单独打开或关闭,关闭提醒之后,用户仍然会收到这个群的消息,但是SDK内置的通知栏提醒将不会触发。如果开发者自行实现通知栏提醒,可通过 Team 的 mute 接口获取是否开启消息提醒,并决定是不是要显示通知。

/**
 * 设置指定群消息通知类型
 *
 * @param teamId 群组ID
 * @param notifyType   通知类型枚举
 * @return InvocationFuture 可以设置回调函数,监听操作结果
 */
InvocationFuture<Void> muteTeam(String teamId, TeamMessageNotifyTypeEnum notifyType);
参数 说明
teamId 群组ID
TeamMessageNotifyTypeEnum 消息提醒类型枚举,分别为全部提醒、仅管理员消息提醒、全部不提醒
// 以设置 “仅管理员消息提醒” 为例

TeamMessageNotifyTypeEnum type = TeamMessageNotifyTypeEnum.Manager;
NIMClient.getService(TeamService.class).muteTeam(teamId, type).setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void param) {
        // 设置成功
    }

    @Override
    public void onFailed(int code) {
        // 设置失败
    }

    @Override
    public void onException(Throwable exception) {
        // 错误
    }
});

接收消息时定制提醒内容

针对不同的消息类型,通知栏显示不同的提醒内容。按照以下优先级显示:

1. 发送方可以设置了推送文案,如果设置,那么通知栏显示该推送文案。

对于 SDK 1.7.0 及以上版本,开发者可以调用 IMMessage 的 setPushContent 接口设置推送文案;

对于低于 1.7.0 的早期版本,开发者可以调用 IMMessage 的 setContent 接口设置推送文案:对于文本消息,该接口会同时修改消息内容和提醒内容,对于其他格式消息,该接口仅修改提醒内容。如果接收方是 iOS 客户端,消息推送的内容遵从相同的规则:如果设置了 setContent 字段,则使用设置的字符串作为推送内容,否则使用默认提醒内容。

2. ( SDK 1.8.0 及以上版本支持)本地定制的通知栏提醒文案,目前支持配置Ticker文案(通知栏弹框条显示内容)和通知内容文案(下拉通知栏显示的通知内容), SDK 会在收到消息时回调 MessageNotifierCustomization 接口, 开发者可以根据昵称和收到的消息(消息类型、会话类型、发送者、消息扩展字段等)来决定要显示的通知内容。示例如下:

public class NimApplication extends Application {
    public void onCreate() {
        ...
        NIMClient.init(this, getLoginInfo(), getOptions());
        ...
    }

    private SDKOptions getOptions() {
        SDKOptions options = new SDKOptions();
        ...

        // 定制通知栏提醒文案(可选,如果不定制将采用SDK默认文案)
        options.messageNotifierCustomization = messageNotifierCustomization;
        return options;
    }

    private MessageNotifierCustomization messageNotifierCustomization = new MessageNotifierCustomization() {
        @Override
        public String makeNotifyContent(String nick, IMMessage message) {
            return null; // 采用SDK默认文案
        }

        @Override
        public String makeTicker(String nick, IMMessage message) {
            return null; // 采用SDK默认文案
        }
    };
}

3. 如果上述两点都不定制(返回null),将显示默认提醒内容:

类型 文案
文本消息 文本消息内容
文件消息 {说话者}发来一条文件消息
图片消息 {说话者}发来一条图片消息
语音消息 {说话者}发来一条语音消息
视频消息 {说话者}发来一条视频消息
位置消息 {说话者}分享了一个地理位置
通知消息 {说话者}: 通知消息
提示消息 {说话者}: 提示消息
自定义消息 {说话者}: 自定义消息

除文本消息外,开发者可以通过 NimStrings 类修改这些默认提醒内容。

接收消息时定制通知栏的头像

网易云通信支持定制通知栏显示的头像(用户头像、群头像),在 UserInfoProvider 接口下提供方法:

/**
 * 为云信端内通知栏提供消息发送者显示名称(例如:如果是P2P聊天,可以显示备注名、昵称、帐号等;如果是群聊天,可以显示群昵称,备注名,昵称、帐号等)
 *
 * @param account     消息发送者账号
 * @param sessionId   会话ID(如果是P2P聊天,那么会话ID即为发送者账号,如果是群聊天,那么会话ID就是群号)
 * @param sessionType 会话类型
 * @return 消息发送者对应的显示名称
 */
String getDisplayNameForMessageNotifier(String account, String sessionId, SessionTypeEnum sessionType);

/**
 * 为云信端内推送通知栏提醒提供头像(个人、群组)
 * 一般从本地图片缓存中获取,若未下载或本地不存在,请返回默认本地头像(可以返回默认头像资源ID对应的Bitmap)
 *
 * @param sessionType 会话类型(个人、群组)
 * @param sessionId   用户账号或者群ID
 * @return 头像位图
 */
Bitmap getAvatarForMessageNotifier(SessionTypeEnum sessionType, String sessionId);

实现上述需要的方法,在 SDKOptions 中配置 UserInfoProvider 实例,在 SDK 初始化时传入 SDKOptions 方可生效。

需要注意的是,上述返回头像 Bitmap 的函数,请尽可能从内存缓存里拿头像,如果读取本地头像可能导致 UI 进程阻塞,从而导致通知栏提醒延时弹出。

发送消息时指定消息提醒

发送消息时可以设置消息配置选项 CustomMessageConfig,可以设定是否需要推送,是否需要计入未读数等。

1. enablePush : 该消息是否进行推送(消息提醒)。默认为 true 。

2. enableUnreadCount :该消息是否要计入未读数,如果为 true ,那么对方收到消息后,最近联系人列表中未读数加1。默认为 true 。

自行实现消息提醒

如果 SDK 内建的消息提醒不能满足你的需求,你可以关闭 SDK 内置的消息提醒,自行实现。添加消息接收观察者,收到新消息时,在观察者的 onEvent 中实现状态栏提醒。 注册注销方式详见消息收发一节。 注意:只有 SDK 1.4.0 及以上版本才能使用该方式,1.4.0 以下的版本使用此方式有可能会漏掉通知。

桌面端在线配置推送

设置桌面端在线推送

支持配置桌面端(PC/Mac/Web)在线时,移动端是否需要推送。

/**
 * 设置桌面端(PC/WEB)在线时,移动端是否需要推送
 * @param isOpen true 桌面端在线时移动端不需推送;false 桌面端在线时移动端需推送
 * @return InvocationFuture 可以设置回调函数。成功会返回成功信息,错误会返回相应的错误码。
 */
InvocationFuture<Void> updateMultiportPushConfig(boolean isOpen);
参数 说明
isOpen true 桌面端在线时移动端不需推送;false 桌面端在线时移动端需推送
NIMClient.getService(SettingsService.class)
    .updateMultiportPushConfig(isOpen)
    .setCallback(new RequestCallback<Void>() { ... });

查询桌面端在线推送

支持查询当前配置的推送状态。true 桌面端在线时移动端不需推送;false 桌面端在线时移动端需推送

/**
 * 获取桌面端(PC/WEB)在线时,移动端是否需要推送
 * @return true 桌面端在线时移动端不需推送;false 桌面端在线时移动端需推送
 */
boolean isMultiportPushOpen();
NIMClient.getService(SettingsService.class).isMultiportPushOpen()