一、Introduction

1、Push Server SDK文档

更新日志

2、用途

• 推送消息发送；
• 消息统计数据获取；
• 订阅标签；
• 消息状态；
• 开发者工具；

二、快速接入

接入Java SDK前，您需要已启用小米推送服务，并且获得应用对应的AppId、 AppKey和AppSecret。

您可以选择接入服务端Java Http2 SDK（参见2.1节）。

1、接入Java Http2 SDK

1.1、获取SDK

Java Http2 SDK下载地址：http://admin.xmpush.xiaomi.com/zh_CN/mipush/downpage/java-http2

请下载最新的SDK版本。

1.2、运行环境

要求JDK版本大于或等于1.8。

1.3、导入SDK

• 解压“MiPush_SDK_Server_Http2.zip”压缩包。
• 将“MiPush_SDK_Server_Http2”目录下的jar包放入项目工程libs目录。

说明：如果运行环境为JDK 1.9以上版本可以不引入conscrypt-openjdk-uber-2.1.0.jar包。如果不想使用okhttp3组件，可以不引入conscrypt-openjdk-uber-2.1.0.jar、okhttp-3.14.2.jar和okio-1.17.2.jar这三个jar包，同时调用Constants.disableOkHttp3()方法，此时将不会启动HTTP2.0协议。

2、SDK类定义说明

参见各个类使用说明：

三、发送消息

发送消息依赖Sender类com.xiaomi.xmpush.server.Sender
实例化SenderSender(String appSecret) - appSecret是在开发者网站上注册时生成的, 可在应用详情下查看返回结果Resultcom.xiaomi.xmpush.server.Result

Result对于所有发送消息接口使用方式完全一样

Demo

private void sendMessage() throws Exception {
    Constants.useOfficial();
    Sender sender = new Sender(APP_SECRET_KEY);
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    Message message = new Message.Builder()
        .title(title)
        .description(description).payload(messagePayload)
        .restrictedPackageName(MY_PACKAGE_NAME)
        .notifyType(1)     // 使用默认提示音提示
        .build();
    Result result = sender.send(message, regId, 3);
    Log.v("Server response: ", "MessageId: " + result.getMessageId()
            + " ErrorCode: " + result.getErrorCode().toString()
            + " Reason: " + result.getReason());
}

1、构建消息

• 构建Message消息对象
• 构建TargetedMessage对象：TargetedMessage类中封装了Message对象和该Message所要发送的target；

TargetedMessage类：com.xiaomi.xmpush.server.TargetedMessage

区别：Message消息体只是包含消息参数, 不包括消息推送目标(regid, alias, useraccount, topic)

注意: TargetedMessage集合接口发送消息时, 所有的TargetedMessage对象的targetType必须相同, 不支持在一个调用中同时给regid和alias发送消息

targetType表示目标类型(目前仅支持三种类型)TargetedMessage.TARGET_TYPE_REGID(regid消息类型, target对应regid)TargetedMessage.TARGET_TYPE_ALIAS(alias消息类型, target对应alias)TargetedMessage.TARGET_TYPE_USER_ACCOUNT(useraccount消息类型, target对应useraccount)

1.1、Android平台

com.xiaomi.xmpush.server.Message.Builder

消息类型：

• 通知栏消息 - 在系统通知栏进行展示；

Builder方法列表：

Demo：

private Message buildMessage() throws Exception {
    String PACKAGENAME = "com.xiaomi.mipushdemo";
    String messagePayload = “This is a message”;
    Message message = new Message.Builder()
            .payload(messagePayload)
            .restrictedPackageName(MY_PACKAGE_NAME)
            .notifyType(1)   // 使用默认提示音提示
            .build();
    return message;
}

2、RegID消息

使用场景：

regId是app在客户端向小米推送服务注册时, 小米推送服务端根据设备标识和appId以及当前时间戳生成, 因此能够保证每个设备上每个app对应的regId都是不同的, 可以作为每台设备上app的唯一标识；注: 需要开发者自己的服务器接收客户端返回的regid并存储在自身服务器；

接口说明：

com.xiaomi.xmpush.server.Sender

Demo：

• 单个regid消息：

private void sendMessage() throws Exception {
    Constants.useOfficial();
    private Sender sender = new Sender(APP_SECRET_KEY);
    String messagePayload= “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    Message message = new Message.Builder()
                .title(title)
                .description(description).payload(messagePayload)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .notifyType(1)     // 使用默认提示音提示
                .build();
    sender.send(message, regId, 3); //根据regID，发送消息到指定设备上
}

• 多个regid消息(推荐使用)

private void sendMessage() throws Exception {
    Constants.useOfficial();
    private Sender sender = new Sender(APP_SECRET_KEY);
    String messagePayload= “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    Message message = new Message.Builder()
                .title(title)
                .description(description).payload(messagePayload)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .notifyType(1)     // 使用默认提示音提示
                .build();
    sender.send(message, Lists.newArrayList(regId1, regId2 ...), 3); //发送消息到一组设备上, regids个数不得超过1000个
}

3、Alias消息

使用场景：

别名alias是小米推送这边提供的一个个性化设定, 可以为每个设备上的app设置一个别名, 方便开发者管理, 并能做到精细化推送 alias与regid(设备)一一对应, 主要是为了方便开发者管理而推出, 如果多个设备设置同一个alias, 则只能后设置的设备才会收到消息(如果需要多个设备使用同一名称进行管理, 推荐使用UserAccount消息)；注: alias由客户端发送Command请求进行设置，且每个app单台设备可订阅的alias上限为15个。

接口说明：

com.xiaomi.xmpush.server.Sender

Demo：

• 单个alias消息:

private void sendMessageToAlias() throws Exception {
    Constants.useOfficial();
    private Sender sender = new Sender(APP_SECRET_KEY);
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    String alias = “testAlias”;    //alias非空白, 不能包含逗号, 长度小于128
    Message message = new Message.Builder()
                .title(title)
                .description(description).payload(messagePayload)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .notifyType(1)     // 使用默认提示音提示
                .build();
    sender.sendToAlias(message, alias, 3); //根据alias, 发送消息到指定设备上
}

• 多个alias消息(推荐使用)

private void sendMessageToAliases() throws Exception {
    Constants.useOfficial();
    private Sender sender = new Sender(APP_SECRET_KEY);
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    List<String> aliasList = new ArrayList<String>();
    aliasList.add(“testAlias1”);  //alias非空白，不能包含逗号, 长度小于128
    aliasList.add(“testAlias2”);  //alias非空白，不能包含逗号, 长度小于128
    aliasList.add(“testAlias3”);  //alias非空白，不能包含逗号, 长度小于128
    Message message = new Message.Builder()
                .title(title)
                .description(description).payload(messagePayload)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .notifyType(1)     // 使用默认提示音提示
                .build();
    sender.sendToAlias(message, aliasList, 3); //根据aliasList, 发送消息到指定设备上
}

4、UserAccount消息

使用场景：

userAccount主要适用于用户多点登陆的情况；一个账号account可以绑定多个设备（上限20个）, 可以认为是小型的topic。注: useraccount由客户端调用setUserAccount(final Context context, final String userAccount, String category)接口进行设置。

接口说明：

com.xiaomi.xmpush.server.Sender

Demo：

• 单个useraccount消息：

private void sendMessageToUserAccount() throws Exception {
    Constants.useOfficial();
    private Sender sender = new Sender(APP_SECRET_KEY);
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    String useraccount = “testUserAccount”;    //useraccount非空白, 不能包含逗号, 长度小于128
    Message message = new Message.Builder()
                .title(title)
                .description(description).payload(messagePayload)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .notifyType(1)     // 使用默认提示音提示
                .build();
    sender.sendToUserAccount(message, useraccount, 3); //根据useraccount, 发送消息到指定设备上
}

• 多个useraccount消息(推荐使用)：

private void sendMessageToUserAccounts() throws Exception {
    Constants.useOfficial();
    private Sender sender = new Sender(APP_SECRET_KEY);
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    List<String> accoutList = new ArrayList<String>();
    accoutList.add(“testUserAccount1”);  //useraccount非空白，不能包含逗号, 长度小于128
    accoutList.add(“testUserAccount2”);  //useraccount非空白，不能包含逗号, 长度小于128
    accoutList.add(“testUserAccount3”);  //useraccount非空白，不能包含逗号, 长度小于128
    Message message = new Message.Builder()
                .title(title)
                .description(description).payload(messagePayload)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .notifyType(1)     // 使用默认提示音提示
                .build();
    sender.sendToUserAccount(message, accoutList, 3); //根据accountList, 发送消息到指定设备上
}

5、Topic消息

使用场景：

Topic消息, 开发者如果想要给不同的用户群体（量级一般比较大）发送不同的推送消息, 比如不同的客户端版本、 不同地域、男女等的用户群体，那么使用Topic消息就非常适合；通过给不同的用户群体打不同的标签（topic）来实现, 我们内部还为全量用户打了统一标签, 开发者可以直接使用全量标签发送, 方便快捷；开发者还可以使用topic做交并差集运算，以达到更精细推送的目的；注: 参考第七部分订阅标签。

特别提示：请谨慎使用API发送全量Topic消息，如果因测试等原因误发全量消息，对用户造成干扰，小米推送有权禁止topic消息功能使用；

接口说明：

com.xiaomi.xmpush.server.Sender

• 在multiTopicBroadcast中topic_op - BROADCAST_TOPIC_OP是一个枚举类型, 指定了发送广播消息时多个topic之间的运算关系；

public enum BROADCAST_TOPIC_OP {
        UNION,        // 并集
        INTERSECTION, // 交集
        EXCEPT,       // 差集
}

• 例如: topics的列表元素是[A, B, C, D], 则并集结果是A ∪ B ∪ C ∪ D, 交集的结果是A ∩ B ∩ C ∩ D，差集的结果是A - B - C - D

注: 发送topic消息时topic的数量不能超过5；

Demo：

• 单个topic：

private void sendBroadcast() throws Exception {
    Constants.useOfficial();
    private Sender sender = new Sender(APP_SECRET_KEY);
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    String topic = “testTopic”;
    Message message = new Message.Builder()
                .title(title)
                .description(description).payload(messagePayload)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .notifyType(1)     // 使用默认提示音提示
                .build();
    sender.broadcast(message, topic, 3); //根据topic, 发送消息到指定一组设备上
}

• 多个topic：

private void sendBroadcast() throws Exception {
    Constants.useOfficial();
    private Sender sender = new Sender(APP_SECRET_KEY);
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    List<String> topicList = new ArrayList<>();
    String topic1 = “testTopic1”;
    String topic2 = “testTopic2”;
    topicList.add(topic1);
    topicList.add(topic2);
    Message message = new Message.Builder()
                .title(title)
                .description(description).payload(messagePayload)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .notifyType(1)     // 使用默认提示音提示
                .build();
    //根据topicList做并集运算, 发送消息到指定一组设备上
    sender.multiTopicBroadcast(message, topicList, BROADCAST_TOPIC_OP.UNION, 3);
}

6、定时消息

使用场景：

一些日常的定点推送任务或者一些固定时间点的活动, 实时推送难免会费时费力还可能不及时, 这时候就可以提前准备好推送文案, 提交定时消息到我们后台, 到了推送时间指定时间小米推送会准时将消息下发；

接口说明：

com.xiaomi.xmpush.server.Sender

1.构建Message对象时设置timeToSend(long milliseconds)

• 定时发送消息, timeToSend是以毫秒为单位的时间戳(仅支持七天内的定时消息)

2.构建TargetedMessage对象调用Sender.send(List messages, int retries, long timeToSend)

• 定时发送一组消息, timeToSend是用自1970年1月1日以来00:00:00.0 UTC时间表示(以毫秒为单位的时间)注: 仅支持七天内的定时消息；

Demo:

设置Message对象timeToSend属性:

private void sendMessageToAlias() throws Exception {
    Constants.useOfficial();
    private Sender sender = new Sender(APP_SECRET_KEY);
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    String alias = “testAlias”;    //alias非空白, 不能包含逗号, 长度小于128
    Message message = new Message.Builder()
                .title(title)
                .description(description).payload(messagePayload)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .timeToSend(System.currentTimeMillis() + 60 * 60 * 1000) // 1个小时后发送
                .notifyType(1)     // 使用默认提示音提示
                .build();
    sender.sendToAlias(message, alias, 3); //根据alias, 发送消息到指定设备上
}

构建TargetedMessage：

private void sendMessageToAlias() throws Exception {
    Constants.useOfficial();
    private Sender sender = new Sender(APP_SECRET_KEY);
    String messagePayload = “This is a message”;
    String messagePayload1 = “Other This is a message”;
    String title = “notification title”;
    String title1 = "other notification title"
    String description = “notification description”;
    String description1 = “other notification description”;
    Message message = new Message.Builder()
                .title(title)
                .description(description).payload(messagePayload)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .notifyType(1)     // 使用默认提示音提示
                .build();
    String alias = “testAlias”;    //alias非空白, 不能包含逗号, 长度小于128
    String alias1 = “testAlias1”;    //alias非空白, 不能包含逗号, 长度小于128
    TargetedMessage targetedMessage = new TargetedMessage();
    targetedMessage.setTarget(TargetedMessage.TARGET_TYPE_ALIAS, alias);
    targetedMessage.setMessage(message);

    TargetedMessage targetedMessage1 = new TargetedMessage();
    targetedMessage1.setTarget(TargetedMessage.TARGET_TYPE_ALIAS, alias1);
    Message message1 = new Message.Builder()
                .title(title1)
                .description(description1).payload(messagePayload1)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .notifyType(1)     // 使用默认提示音提示
                .build();
    targetedMessage1.setMessage(message1);
    List<TargetedMessage> messages = new ArrayList<TargetdMessage>();
    messages.add(targetMessage);
    messages.add(targetMessage1);

    //根据TargetedMessage列表, 发送消息到指定设备上, 设置一个小时后发送
    sender.send(messages, 3, System.currentTimeMillis() + 60 * 60 * 1000);
}

7、提高发送性能

优先使用batch接口, 如优先使用, 在发消息时, 想要发送一条消息给10000个用户, 开发者A只用10次请求每次发送1000个目标量(如alias, regId等), 而开发者B用了10000次请求每次只发送1个目标量. 很明显, 开发者A的效率远高于开发者B, 其次使用TargetMessage消息对象；发送之前如果能够过滤掉一部分无效设备数（通过消息回执callback接口，设置callback.type=16，获取无效设备）, 提高发送性能。

8 、提高送达率

使用消息回执callback接口，设置callback.type=16，过滤用户集中的无效设备；设置合适的ttl(timeToLive消息过期时间)也能一定程度上提高送达率；建议使用通知栏消息；

四、高级功能

构造Message对象时, 调用extra(String key, String value)方法设置key和value, 自定义app的扩展功能；

1、自定义铃声

Android 8.0以下版本

Android 8.0以下版本在发送消息时按此方式设置自定义铃声：

调用Message.Builder类的extra(String key, String value)方法设置铃声uri。
key - 'sound_uri', value - 铃声的uri；
注:铃声只能使用当前app内的资源, uri格式满足 android.resource://your packagename/XXX/XXX
铃声文件放在Android app的raw目录下
只适用于通知栏消息
存储的声音文件需要有扩展名, 但是不要把扩展名写在uri中

private Message buildMessage() throws Exception {
    String PACKAGENAME = "com.xiaomi.mipushdemo";
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    Message message = new Message.Builder()
            .title(title)
            .description(description).payload(messagePayload)
            .restrictedPackageName(MY_PACKAGE_NAME)
            .notifyType(1)
            .extra(Constants.EXTRA_PARAM_SOUND_URI, "android.resource://" + PACKAGENAME + "/raw/shaking")
            .build();
    return message;
}

Android 8.0及以上版本

Android 8.0及以上版本的通知效果以channel中的效果为准，发送消息时设置自定义铃声将不会生效，需要在新建channel时设置自定义铃声。

• 如果您未设置channel，当您发送第一条消息时小米推送会为您创建一个默认channel，该channel的效果会以您发送的这条消息为准。如果您在这条消息中按照上面的方式设置了自定义铃声，该默认channel的铃声效果就会为此自定义铃声效果，以后再更改不会生效。
• 如果您希望更改自定义铃声，只能新建一个channel，在新建时设置自定义铃声，再使用该channel推送消息。该channel推送的消息都会带有此自定义铃声。

    channel的使用方法请参见“4.4 通知类别（Channel)”。

2、控制APP前台通知弹出

当app在前台时, 默认情况下服务端向客户端发送通知栏消息, app会弹出通知；如果开发者不想让客户端弹出通知, 调用Message.Builder类的extra(String key, String value)方法设置是否弹出通知；key - 'notify_foreground', value - 开启/关闭(1/0)；注:只适用于通知栏消息

Demo：

private Message buildMessage() throws Exception {
    String PACKAGENAME = "com.xiaomi.mipushdemo";
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    Message message = new Message.Builder()
            .title(title)
            .description(description).payload(messagePayload)
            .restrictedPackageName(MY_PACKAGE_NAME)
            .notifyType(1)
            .extra(Constants.EXTRA_PARAM_NOTIFY_FOREGROUND, "0")
            .build();
    return message;
}

3、预定义通知栏通知的点击行为

3.1、打开当前app对应的Launcher Activity：

调用Message.Builder类的extra(String key, String value)方法将key设置为Constants.EXTRA_PARAM_NOTIFY_EFFECT，value设置为Constants.NOTIFY_LAUNCHER_ACTIVITY;

Demo：

private Message buildMessage() throws Exception {
    String PACKAGENAME = "com.xiaomi.mipushdemo";
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    Message message = new Message.Builder()
            .title(title)
            .description(description).payload(messagePayload)
            .restrictedPackageName(MY_PACKAGE_NAME)
            .notifyType(1)
            .extra(Constants.EXTRA_PARAM_NOTIFY_EFFECT, Constants.NOTIFY_LAUNCHER_ACTIVITY)
            .build();
    return message;
}

3.2、打开当前app内任意一个Activity

调用Message.Builder类的extra(String key, String value)方法：

key - Constants.EXTRA_PARAM_NOTIFY_EFFECT, value - Constants.NOTIFY_ACTIVITYkey - Constants.EXTRA_PARAM_INTENT_URI, value - 启动Activity的intent uri

获取Intent uri的具体步骤：

在安卓客户端的工程的AndroidManifest.xml里定义一个Activity, 例如下面是一个展示新闻的Activity:

<activity android:name=".NewsActivity"/>

定义一个Intent来启动该Activity, 例如要打开上面定义的NewsActivity可定义Intent为：

intent:#Intent;component=com.yourpackage/.YourActivity;end

例如转换intent为uri：

String uriString = intent.toUri(Intent.URI_INTENT_SCHEME);//该uriString就是Constants.EXTRA_PARAM_INTENT_URI对应的值

返回值：

intent:#Intent;component=com.xiaomi.mipushdemo/.NewsActivity;end

注:

• 如果你希望在Intent uri中携带数据，注意一个限制:Intent.toUri(Intent.URI_INTENT_SCHEME), 返回的结果不会携带除基本类型(boolean, byte, short, int, long, float, double, String)以外的数据类型, 例如数组和HashMap
• 获取了Intent uri之后, 在服务端的工程里(需要引用推送服务器SDK), 把uriString 设置进的Message.Builder.extra()，对应的key是Constants.EXTRA_PARAM_INTENT_URI
• 在生成intent uri时，如果出现点击无法跳转或者Activity的生命周期没有执行时，建议追加flag参数：intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP)

Demo：

private Message buildMessage() throws Exception {
    String PACKAGENAME = "com.xiaomi.mipushdemo";
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    return new Message.Builder()
            .title(title)
            .description(description).payload(messagePayload)
            .restrictedPackageName(MY_PACKAGE_NAME)
            .notifyType(1)
            .extra(Constants.EXTRA_PARAM_NOTIFY_EFFECT, Constants.NOTIFY_ACTIVITY)
            .extra(Constants.EXTRA_PARAM_INTENT_URI, "intent:#Intent;component=com.xiaomi.mipushdemo/.NewsActivity;end")
            .build();
}

3.3、打开网页

调用Message.Builder类的extra(String key, String value)方法：

key -Constants.EXTRA_PARAM_NOTIFY_EFFECT, value - Constants.NOTIFY_WEBkey - Constants.EXTRA_PARAM_WEB_URI, value - 网页uri

Demo：

private Message buildMessage() throws Exception {
    String PACKAGENAME = "com.xiaomi.mipushdemo";
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    Message message = new Message.Builder()
            .title(title)
            .description(description).payload(messagePayload)
            .restrictedPackageName(MY_PACKAGE_NAME)
            .notifyType(1)
            .extra(Constants.EXTRA_PARAM_NOTIFY_EFFECT, Constants.NOTIFY_WEB)
            .extra(Constants.EXTRA_PARAM_WEB_URI, "http://www.xiaomi.com")
            .build();
    return message;
}

4、通知类别（Channel）

通知类别（Channel）介绍

通知类别（Channel）是 Android O 引入的新功能，旨在解决以下问题：

• 应用的通知越来越多，给用户造成明显打扰。
• 但用户只能全局屏蔽这个应用的全部通知，不能屏蔽部分，然后留下对自己有用的。

为了解决这个问题，Android 支持开发者给自己的通知分成若干类，然后允许用户单独屏蔽这个类别的通知。关于通知类别（Channel）的详细介绍请参见《MIUI 10 通知类别 (Channel) 适配》。

说明：1. 当前版本暂不支持设置Channel Group。2. 对于MIUI系统，可以不设置Channel，通知也能发出。对于非MIUI系统，是否必须设置Channel取决于你的应用的target API：target API ≥ 26(Android 8.0)：必须设置Channel，而且必须给每条通知指定一个 Channel，否则无法发出通知。target API ≤ 25(Android 7.1)：可以不设置Channel。在8.0及以上的设备，通知也能正常发出。为确保通知在不同类型的设备上都能正常显示，建议您设置Channel。

使用方法

注意：用户最多可创建8组Channel。各Channel的Channel_id不可重复，Channel_name也不允许同名。Channel一旦创建并发送了带有Channel的消息，设备上即会生成这个Channel，不能删除也不能修改，所以请谨慎创建Channel。

• 添加新Channel：

参考《小米推送消息分类新规》2.channel申请与接入方法。

• 发送带有Channel的消息：

构建message时，通过自定义键值对，向extra里传递参数。

代码示例：

private Message buildMessage() throws Exception {
        String PACKAGENAME = "com.xiaomi.mipushdemo";
        String messagePayload = "This is a message";
        String title = "notification title";
        String description = "notification description";
        Message message = new Message.Builder()
                .title(title)
                .description(description).payload(messagePayload)
                .restrictedPackageName("com.xiaomi.mipushdemo")
                .notifyType(1)     // 使用默认提示音提示
                .extra("channel_id", "my_channel_1")              // 设置channel id, 必须配
                .build();
        return message;
    }

5、过滤消息

开发者通过调用Message.Builder类的extra(String key, String value)来指定消息的过滤规则(过滤规则能够支持所有的消息)

key - 'locale', value - 可以接收消息设备的语言范围, 用逗号分隔；key - 'locale_not_in', value - 无法收到消息设备的语言范围, 用逗号分隔；

当前设备locale获取方法为Locale.getDefault().toString()

比如, 中国大陆用"zh_CN"表示（详见附录1：语言代码对照表）

key - 'app_version', value - 可以接收消息app版本号, 用逗号分隔；key - 'app_version_not_in', value - 无法收到消息app版本号, 用逗号分隔；

安卓app版本号来源于manifest文件中的"android:versionName"的值 (目前支持MiPush_SDK_Client_2_2_12_sdk.jar及以后的版本)

key - 'connpt', value - 指定在特定的网络环境下才能接到消息, 目前仅支持指定"wifi"；

Demo：

private Message buildMessage() throws Exception {
    String PACKAGENAME = "com.xiaomi.mipushdemo";
    String messagePayload = “This is a message”;
    String title = “notification title”;
    String description = “notification description”;
    Message message = new Message.Builder()
            .title(title)
            .description(description).payload(messagePayload)
            .restrictedPackageName(MY_PACKAGE_NAME)
            .notifyType(1)
            .extra("locale","zh_CN")
            .build();
    return message;
}

6、消息回执

开发者希望消息发送后，推送系统能发送回执给开发者，告知开发者这些消息的送达、点击或发送失败状态。可通过调用Message.Builder类的extra(String key, String value)来指定消息回执规则。

规则列表：

小米推送服务器每隔1s将已送达、已点击或目标设备无效的消息ID和对应设备的regid或alias通过调用第三方http接口传给开发者（每次调用后, 小米推送服务器会清空这些数据, 下次传给开发者将是新一拨数据）。

注意: 消息的送达回执只支持向regId或alias发送的消息。目标设备无效的回执支持regId、alias和useraccount消息。

服务器callback回调采用post方式，在进行api调用时http请求头会携带以下信息：

Accept:text/html,application/xhtml xml,application/xml

Accept-Charset：UTF-8

Accept-Language：zh-cn

Content-Type：application/x-www-form-urlencoded

请参考，并建议在接入前使用postman或其他工具测试api可用性时也携带以上请求头信息。

request body为data={json格式的字符串}，JSON数据格式如下：

{
      //type为1表示该消息已送达，targets为送达的设备alias列表
       "msgId1":{"param":"param","type": 1, "targets":"alias1,alias2,alias3", "jobkey": "123" ,"barStatus":"Enable","timestamp":1324167800000}, 

      //type为2表示该消息被点击，targets为点击的设备alias列表
      "msgId2":{"param":"param","type": 2, "targets":"alias1,alias2,alias3", "jobkey": "456", "barStatus": "Enable", "timestamp": 1524187800000},   

      //type为16表示目标设备无效，targets为无效的alias列表
      "msgId3":{"param":"param","type":16,"targets":"alias1,alias2,alias3","barStatus":"Unknown","timestamp":xxx},

      //type为16表示目标设备无效，targets为无效的regId列表，errorCode为1表示无效regId
      "msgId4":{"param":"param","type":16,"targets":"regId1,regId2,regId3","barStatus":"Unknown","errorCode":1,"timestamp":xxx,"replaceTarget":{"regId1":"otherRegId"}},
      
       //type为64表示目标设备不符合过滤条件
      "msgId5":{"param":"param","type":64,"targets":"regId1,regId2,regId3", "barStatus":"Unknown","timestamp":1572228055643}
 
       //type为128表示当日推送总量超限，或单设备接收超限
       "msgId6": {"extra":{"ack":"当日已送达数","quota":"当日可以下发总数"},"type":128,"targets":"alias","timestamp":1585203103625}      
       "msgId7": {"extra":{"device_acked":"当日单设备已接收数","device_quota":"当日单设备可以下发总数"},"type":128,"targets":"alias","timestamp":1585203104390} 

      //type为1024表示消息有效期TTL过期
      "msgId8": {"param":"param","type":1024,"targets":"regId1,regId2,regId3", "timestamp":1572228055643}
} 

格式说明:

外层key代表相应的消息msgId, value是一个JSONObject, 包含了下面的参数值：
param：开发者上传的自定义参数值。
type：消息状态类型（1-送达；2-点击；16-无法找到目标设备；32-客户端调用了disablePush接口禁用Push；64-目标设备不符合过滤条件；128-当日推送总量超限或单设备接收超限；1024-消息有效期TTL过期）。
device_acked：当日单设备已接收数；device_quota：当日单设备可以下发总数；targets：一批alias、regId或useraccount列表，逗号分隔；jobkey：发送消息时设置的jobkey值；barStatus：消息送达时通知栏的状态；Enable：用户允许此app展示通知栏消息； Disable：通知栏消息已关闭； Unknown：通知栏状态未知；timestamp：消息送到设备的时间；replaceTarget：该发送目标无法正常送达，但建议可替换成另外一个新的目标标识以满足该设备的正常推送，其值为键值对；key：该设备原始发送目标标识；value：建议替换成的新的目标标识；errorCode：type为16时返回的无效目标的子类；errorCode:1表示无效regid；errorCode:2表示无效alias；errorCode:3表示无效useraccount。

Demo：

private Message buildMessage() throws Exception {
     String PACKAGENAME = "com.xiaomi.mipushdemo";
     String messagePayload = "This is a message";
     String title = "notification title";
     String description = "notification description";
     Message message = new Message.Builder()
             .title(title)
             .description(description).payload(messagePayload)
             .restrictedPackageName(MY_PACKAGE_NAME)
             .notifyType(1)
             .extra("callback", "http://www.xiaomi.com/msgcallback")
             .build();
     return message;
}

7、 消息聚合

开发者在发送消息时可以设置消息的组ID(JobKey), 带有相同的组ID的消息会被聚合为一个消息组；

系统支持按照消息组展示消息详情以及计划推送/送达数量/送达曲线等统计信息。另外, 相同JobKey的消息在客户端会进行去重, 只展示其中的第一条。这样如果发送时同JobKey中不慎有重复的设备也不用担心用户会收到重复的通知。

设置消息的组ID的方法是调用Message.Builder类的extra(String key, String value)方法将key设置为“jobkey”；value设置为消息组的ID, 合法的消息组ID由数字([0-9]), 大小写字母([a-zA-Z]), 下划线(_)和中划线(-)组成, 长度不大于20个字符，且不能以下划线(_)开头。

Demo：

private Message buildMessage() throws Exception {
    String PACKAGENAME = "com.xiaomi.mipushdemo";
    String messagePayload = “This is a message with job key.”;
    String title = “notification title”;
    String description = “notification description”;
    Message message = new Message.Builder()
            .title(title)
            .description(description).payload(messagePayload)
            .restrictedPackageName(MY_PACKAGE_NAME)
            .notifyType(1)
            .extra("jobkey", "0115a001")
            .build();
    return message;
}

8、平滑推送

考虑有开发者服务器资源的问题, 如果推送消息速度过快会导致开发者服务器产生很大的压力, 所以我们提供平滑推送特性，开发者可以设定消息发送速度。

开发者通过调用Message.Builder类的extra(String key, String value)来设置消息发送速度：

key - "flow_control"value - 发送速度(qps)注: 若设置速度低于1000, 则默认3000qps

说明：如果设置了平滑推送，同一个应用同时发送两条消息时会排队发送，需要等第一条消息发送完毕才会发送第二条。

Demo：

private Message buildMessage() throws Exception {
    String PACKAGENAME = "com.xiaomi.mipushdemo";
    String messagePayload = “This is a message with job key.”;
    String title = “notification title”;
    String description = “notification description”;
    Message message = new Message.Builder()
            .title(title)
            .description(description).payload(messagePayload)
            .restrictedPackageName(MY_PACKAGE_NAME)
            .notifyType(1)
            .extra("flow_control", "20000") // 设置平滑推送, 推送速度20000每秒(qps=20000)
            .build();
    return message;
}

9、only send once消息

一些开发者希望消息只在设备网络在线时下发，不缓存离线消息进行多次下发，以满足及时性需求。为此我们提供了only send once消息功能，开启该功能后消息只会当设备在线时下发一次。

开发者通过调用Message.Builder类的extra(String key, String value)来设置only send once消息：

key - "only_send_once"value - "1"

Demo：

private Message buildMessage() throws Exception {
    String PACKAGENAME = "com.xiaomi.mipushdemo";
    String messagePayload = “This is a message that will only be send once.”;
    String title = “notification title”;
    String description = “notification description”;
    Message message = new Message.Builder()
            .title(title)
            .description(description).payload(messagePayload)
            .restrictedPackageName(MY_PACKAGE_NAME)
            .notifyType(1)
            .extra("only_send_once", "1") // 设置消息只发送1次
            .build();
    return message;
}

五、获取统计数据{Deprecated}

获取统计数据的com.xiaomi.xmpush.server.Stats类已下线，请使用com.xiaomi.xmpush.server.Tracer类获取消息统计数据。

六、追踪消息状态

获取统计数据依赖Tracer类：

com.xiaomi.xmpush.server.Tracer

实例化Tracer：

Tracer(String appSecret) - appSecret是在开发者网站上注册时生成的, 可在应用详情下查看；

方法介绍：

• 该方法用于获取某条消息或某个时间段的消息的统计数据，如发送量、送达量、点击量等；

1、获取指定消息ID的统计信息

String getMessageStatus(String msgId, int retries)

• msgId : 发送消息时返回的msgId(参考Sender相关接口)
• retries : 重试次数

返回值 - json字符串

• id表示消息ID。
• resolved表示消息的计划推送数(包含送达数, 以及其他某些原因导致无法下发的目标数)。
• raw_counter表示https原始请求目标数。
• invalid_target表示无效目标数(alias无效, user_account无效等)。
• app_not_register表示app未注册push服务数量。
• device_condition_unmatch表示设备所处的环境不符合消息设置的条件(例如: 网络环境不匹配, 地域不匹配, app版本不匹配, 机型不匹配等)。 
• msg_send表示消息的实际下发数。
• delivered表示消息的送达数(实际下发到客户端的消息数量)。
• delivery_rate表示送达率(送达数/有效目标数) 。
• bar_closed表示屏蔽通知栏数。
• msg_display表示消息的展示数（送达数-屏蔽通知栏数）。
• click表示消息点击数。
• click_rate表示消息点击率（点击数/送达数）。
• create_time表示消息发送时间。
• time_to_live表示消息有效期。
• msg_type表示消息发送方式(Common、BatchRegId、Alias、BatchAlias、Topic)。

成功：

{
    "result" : "ok",
    "description" : "成功",
    "data" : {
                "data" : "{"id" : XXXX, "delivery_rate" : XXXX, "delivered" : XXXX, "resolved" : XXXX, "raw_counter": XXXX, "invalid_target": XXXX, "app_not_register": XXXX, "device_condition_unmatch": XXXX, "msg_type" : XXXX, "create_time" : XXXX, "time_to_live" : XXXX, "click" : XXXX, "click_rate":XXXX}"
              },
    ”code”:0
}

失败：

{
    "result" : "error",
    "reason" : "XXXXXXXXX",
    "description" : "XXXX",
    "code" : XXXX
}

2、获取某个时间段内所有消息的统计数据

String getMessageStatus(long beginTime, long endTime, int retries)

• beginTime : 开始时间戳(单位: ms)
• endTime : 结束时间戳(单位: ms)
• retries : 重试次数

返回值 - json字符串；

注：

• 如果该时间区间内的消息数大于100条, 则返回最近100条
• 开始时间和结束时间之间的跨度不能大于7天

成功：

{
    "result" : "ok",
    "description" : "成功",
    "data" : {
                "data" : "{"id" : XXXX, "delivery_rate" : XXXX, "delivered" : XXXX, "resolved" : XXXX, "msg_type" : XXXX, "raw_counter": XXXX, "invalid_target": XXXX, "app_not_register": XXXX, "device_condition_unmatch": XXXX, "create_time" : XXXX, "time_to_live" : XXXX, "click" : XXXX, "click_rate":XXXX}"
              },
    ”code”:0
}

失败：

{
    "result" : "error",
    "reason" : "XXXXXXXXX",
    "description" : "XXXX",
    "code" : XXXX
}

3、获取指定jobkey消息统计数据

String getMessageGroupStatus(String jobKey, int retries)

• jobKey : 发送消息时设置(参考4.高级功能), 相同jobkey的消息在客户端只显示一条, 并可以通过jobkey来批量获取消息的统计信息
• retries : 重试次数

返回值 - json字符串

成功：

{
    "result" : "ok",
    "description" : "成功",
    "data" : {
                "data" : "{"id" : XXXX, "delivery_rate" : XXXX, "delivered" : XXXX, "resolved" : XXXX, "msg_type" : XXXX, "create_time" : XXXX, "time_to_live" : XXXX, "click" : XXXX, "click_rate":XXXX}"
              },
    ”code”:0
}

失败：

{
    "result" : "error",
    "reason" : "XXXXXXXXX",
    "description" : "XXXX",
    "code" : XXXX
}

Demo：

public void getTrace() throws Exception {
    Tracer tracer = new Tracer(APP_SECRET_KEY); // 使用AppSecretKey创建一个Tracer对象
    // 获取单条消息的送达状态， 参数:msgId, retry次数
    String messageStatus = tracer.getMessageStatus("s1005246409317636237jB", 0);
    System.out.println(messageStatus);

    // 获取一个时间区间内的消息的送达状态, 参数:开始时间, 结束时间, retry次数
    String messageStatus2 = tracer.getMessageStatus(System.currentTimeMillis() - 1000, System.currentTimeMillis(), 3);
    System.out.println(messageStatus2);
}

七、订阅标签

使用场景：

标签可以认为是具有某些相同属性的用户集合, 我们可以针对一个标签发送消息。这时，所有订阅了该标签的用户（设备）都会收到该消息（广播消息）。该接口用于将某个设备设置标签（加入集合）或取消标签（从集合中删除）。我们可以通过给不同的用户全体设置不同的标签，已达到精细化推送的目的。

注：每个App单台设备可订阅标签的个数为30个，如果超过了对应上限数，则新订阅的Topic会覆盖最早设置的Topic。

接口说明：

com.xiaomi.xmpush.server.Subscription

实例化Subscription

Subscription(String appSecret) - appSecret是在开发者网站上注册时生成的, 可在应用详情下查看；

API介绍：

八、拉取失效数据{Deprecated}

建议您使用消息回执callback接口（callback.type: 16）进行失效数据过滤。

Feedback接口用于拉取已经失效的regid或alias等数据，该接口已下线。

九、开发者工具

该接口主要用于调查问题时使用, 可以获取某个设备相关的一些信息。

开发者工具依赖DevTools类

com.xiaomi.xmpush.server.DevTools

实例化DevTools

DevTools(String appSecret) - appSecret是在开发者网站上注册时生成的, 可在应用详情下查看

方法介绍：

1、获取某个设备设置的所有alias

String getAliasesOf(String packageName, String regId, int retries)packageName : 应用包名regId : 设备regIdretries : 重试次数返回值如下:

成功：

{
    "result" : "ok",
    "description" : "成功",
    "data" : {
                "list" : ["XXXXXX", "XXXXXX", "XXXXXX"]
              },
    "code" : 0
}

失败：

{
    "result" : "error",
    "reason" : "XXXXXXXXX",
    "description" : "XXXX",
    "code" : XXXX
}

2、获取某个设备订阅的所有topic

String getTopicsOf(String packageName, String regId, int retries)packageName : 应用包名regId : 设备regIdretries : 重试次数返回值如下:

成功：

{
    "result" : "ok",
    "description" : "成功",
    "data" : {
                "list" : ["XXXXXX", "XXXXXX", "XXXXXX"]
              },
    "code" : 0
}

失败：

{
    "result" : "error",
    "reason" : "XXXXXXXXX",
    "description" : "XXXX",
    "code" : XXXX
}

十、FAQ

名词解释：

traceID是什么？

在调用我们sdk发送消息返回的结果中, 总会有一个traceId字段, 它代表这个操作请求在我们服务端的唯一标识, 所以通过这个traceId就可以定位请求的访问调查相关问题；

messageID是什么？

messageId用来标识一条消息, 通过messageId我们可以调查消息的活动周期；

异常处理

主要是三类情况:

网络问题证书问题代码漏洞；

网络问题

确认网络到api.xmpush.xiaomi.com是否畅通；

证书问题

服务端接口使用https方式, 请确认本地是否导入证书；

代码漏洞

参考Server SDK文档, 确认是否由于代码缺失参数或者调用方法错误；

十一、附录：

附录1：国家地区语言代码（基于 ISO-3166 标准）

附录2：品牌表

小米推送技术常见问题解答