小米推送服务Server端SDK (MiPushServiceSDK for server)

 

修订历史
2013-08-23 初稿v
2013-09-27 升级新版本v2.1
2014-03-24 升级新版本v2.2
增加一些扩展功能,如自定义消息铃声、开启/关闭app在前台时的通知弹出、预定义通知栏通知的点击行为。
2014-07 增加对IOS的支持
2016-03增加对多包名的支持
如对小米推送有任何技术问题,请通过推送客服系统与我们联系:http://dev.xiaomi.com/mipush/feedback/fe/

1. 如何接入ServerSDK

  1. 开发者需要登录开发者网站http://developer.xiaomi.com,申请AppID, AppKey,
    AppSecret。
  2. 从开发者网站http://dev.xiaomi.com/mipush/downpage下载SDK,将MiPush_SDK_Sever目录下的jar文件加入到自己的服务端项目中。Jar文件包括MiPush_SDK_Sever_1_2.jar文件和json-simple-1.1.1.jar。
    • 在开发者网站上,下载并解压MiPush_SDK_V1.2.zip;
    • 将ServerSDK文件夹下的MiPush_SDK_Sever_1_2.jar文件和json-simple-1.1.1.jar文件放入项目工程的libs目录;
    • 刷新工程,确保文件出现在libs目录下。如果没有的话请手动添加;
  3. 选择环境。
    • 在正式环境下使用push服务,启动时需要调用如下代码:
      Constants.useOfficial();
    • 在测试环境下使用push服务,启动时需要调用如下代码:
      Constants.useSandbox();

      在测试环境中使用push服务不会影响线上用户。

    注:测试环境只提供对IOS支持,不支持Android。

2. 服务端SDK说明

2.1. 服务端SDK类的介绍

表 1. Server SDK类的简介

类名 使用说明
Message 构建要发送的消息内容。
Builder 构建发送给Android设备的Message对象。
IOSBuilder 构建发送给IOS设备的Message对象。
TargetedMessage 构建要发送的消息内容和消息的发送目标。
Sender MiPush消息发送类。
Result Sender发送消息后,服务器返回的结果。
Stats 获取发送的消息统计数据。
Tracer 追踪消息状态。
Subscription 订阅/取消订阅标签。
Feedback 获取反馈信息,比如失效的regId列表。注:目前仅支持安卓设备。
DevTools 设备工具集,目前提供了获取某个用户的所有alias列表和topic列表。
MessageRevoker 撤回通知栏消息
Constants 常量定义。
ErrorCode Sender发送消息后,返回的错误类型。

 

2.1.1. Message

Message是MiPush推送服务系统中的消息,开发者可以用它构建要发送的消息体。注:
Message的实例是不可变对象(immutable),由Builder或IOSBuilder来构建。

java.lang.Object
↳com.xiaomi.xmpush.server.Message

2.1.2. Builder

构建发送给Android设备的Message对象。

java.lang.Object
↳com.xiaomi.xmpush.server.Message.Builder

表 2. Message.Builder类的方法列表

方法名称 方法说明
Builder() 建立Builder对象,用来构造消息。
payload(String payload) 设置要发送的消息内容payload,不允许全是空白字符,长度小于4K,中英文均以一个计算。对应客户端接受消息时 MiPushMessage 对象中的 content。
title(String title) 设置在通知栏展示的通知的标题,不允许全是空白字符,长度小于16,中英文均以一个计算。
description(String description) 设置在通知栏展示的通知的描述,不允许全是空白字符,长度小于128,中英文均以一个计算。
passThrough(int passThrough) 设置消息是否通过透传的方式送给app,1表示透传消息,0表示通知栏消息。
notifyType(Integer type) 设置通知类型,type的值可以是DEFAULT_ALL或者以下其他几种的OR组合:

  • DEFAULT_ALL = -1;
  • DEFAULT_SOUND  = 1;   // 使用默认提示音提示
  • DEFAULT_VIBRATE = 2;   // 使用默认震动提示
  • DEFAULT_LIGHTS = 4;    // 使用默认led灯光提示
restrictedPackageName(String packageName) 设置app的包名packageName。packageName必须和开发者网站上申请的结果一致。
restrictedPackageNames(String[] packageNames) 设置app的多包名packageNames(多包名发送广播消息)。packageNames必须和开发者网站上申请的结果一致。可以为空,为空则默认给所有渠道包名推送。备注:不能同时调用restrictedPackageName方法和restrictedPackageNames方法。
timeToLive(int milliseconds) 可选项。如果用户离线,设置消息在服务器保存的时间,单位:ms。服务器默认最长保留两周。
timeToSend(long timeToSend) 可选项。定时发送消息。timeToSend是以毫秒为单位的时间戳。注:仅支持七天内的定时消息。
notifyId(Integer id) 可选项。默认情况下,通知栏只显示一条推送消息。如果通知栏要显示多条推送消息,需要针对不同的消息设置不同的notify_id(相同notify_id的通知栏消息会覆盖之前的)。
enableFlowControl(boolean needFlowControl) 可选项。控制消息是否需要进行平缓发送(如果开启平滑推送,则qps 默认为3000/s)。默认不支持。也可以直接通过extra字段自定义设置平滑推送的速度(如果自定义了平滑推送的extra字段,那么不再需要调用enableFlowControl()方法)。key是flow_control,value代表平滑推送的速度。注:服务端支持最低1000/s的qps,最高100000/s。也就是说,如果将平滑推送设置为500,那么真实的推送速度是3000/s,如果大于1000小于100000,则以设置的qps为准。
extra(String key, String value) 可选项,对app提供一些扩展的功能,请参考2.2。除了这些扩展功能,开发者还可以定义一些key和value来控制客户端的行为。注:key和value的字符数不能超过1024,至多可以设置10个key-value键值对。
build() 根据前面的属性,生成message对象。

 

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)
             .passThrough(1)  //消息使用透传方式
             .notifyType(1)     // 使用默认提示音提示
             .extra("flow_control", "4000")     // 设置平滑推送, 推送速度4000每秒(qps=4000)
             .build();
     return message;
}

2.1.3. IOSBuilder

构建发送给IOS设备的Message对象。

java.lang.Object
↳com.xiaomi.xmpush.server.Message.IOSBuilder

表 3. Message.IOSBuilder类的方法列表

方法名称 方法说明
IOSBuilder() 建立IOSBuilder对象,用来构造消息。APNs消息体为4096个字节。
title(String title) 在通知栏展示的通知的标题(支持iOS10及以上版本,如有该字段,会覆盖掉description字段)。
subtitle(String subtitle) 展示在标题下方的子标题(支持iOS10及以上版本,如有该字段,会覆盖掉description字段)。
body(String body) 在通知栏展示的通知的内容(支持iOS10及以上版本,如有该字段,会覆盖掉description字段)。
mutableContent(String mutableContent) 通知可以修改选项,设置之后,在展示远程通知之前会进入Notification Service Extension中允许程序对通知内容修改(支持iOS10及以上版本)
description(String description) 设置在通知栏展示的通知的描述。
timeToLive(int milliseconds) 可选项。如果用户离线,设置消息在服务器保存的时间,单位:ms。服务器默认最长保留两周。
timeToSend(long timeToSend) 可选项。定时发送消息。timeToSend是用自1970年1月1日以来00:00:00.0
UTC时间表示(以毫秒为单位的时间)。注:仅支持七天内的定时消息。
soundURL(String url) 可选项,自定义消息铃声。
badge(int badge) 可选项,自定义通知数字角标。
category(String category) 可选项,iOS8推送消息快速回复类别。
extra(String key, String value) 可选项,自定义键值对。控制客户端的行为。注:至多可以设置10个key-value键值对。支持使用平滑推送。key是flow_control,value代表平滑推送的速度。注:服务端支持最低1000/s的qps,最高100000/s。也就是说,如果将平滑推送设置为500,那么真实的推送速度是3000/s,如果大于1000小于100000,则以设置的qps为准。
build() 根据前面的属性,生成message对象。

 

Demo:

private Message buildMessage() throws Exception {
     String description = “notification description”;
     Message message = new Message.IOSBuilder()
             .description(description)
             .soundURL(“default”)    // 消息铃声
             .badge(1)               // 数字角标
             .category("action")     // 快速回复类别
             .extra("key", "value")  // 自定义键值对
             .extra("flow_control", "4000")   // 设置平滑推送, 推送速度4000每秒(qps=4000)
             .build();
     return message;
}

2.1.4. TargetedMessage

TargetedMessage封装了MiPush推送服务系统中的消息Message对象,和该Message对象所要发送到的目标。

java.lang.Object
↳com.xiaomi.xmpush.server.TargetedMessage

表 4. TargetedMessage方法列表

方法名称 方法说明
TargetedMessage() 构造函数。
setTarget(int targetType, String target) 设置消息的发送目标。
targetType表示目标类型,目前支持TargetedMessage.TARGET_TYPE_REGID和TargetedMessage.TARGET_TYPE_ALIAS两种类型。当targetType是TARGET_TYPE_REGID时,target需要设置为regid;当targetType是TARGET_TYPE_ALIAS时,target需要设置为alias。
setMessage(Message message) 设置消息。

 

Demo:

注意:下面函数返回的List中所有 TargetedMessage对象的targetType必须相同:全是
TargetedMessage.TARGET_TYPE_REGID,或者全是TargetedMessage.TARGET_TYPE_ALIAS。

private List<TargetedMessage> buildMessages() throws Exception {
     List<TargetedMessage> messages = new ArrayList<TargetdMessage>();
     TargetedMessage message1 = new TargetedMessage();
     message1.setTarget(TargetedMessage.TARGET_TYPE_ALIAS, “alias1”);
     message1.setMessage(buildMessage());
     messages.add(message1);
     TargetedMessage message2 = new TargetedMessage();
     message2.setTarget(TargetedMessage.TARGET_TYPE_ALIAS, “alias2”);
     message2.setMessage(buildMessage());
     messages.add(message2);
     return messages;
}

2.1.5. Sender

MiPush消息发送类。

java.lang.Object
↳com.xiaomi.xmpush.server.Sender

表 5. Sender方法列表

方法名称 方法说明
Sender(String appSecret) 构造Sender对象。appSecret是在开发者网站上注册时生成的, 可在应用详情下查看。
send(Message message, String registrationId,int retries) 根据registrationId,发送消息到指定设备上,retries为发送失败之后重试的次数。
send(Message message, List<String> regIds, int retries) 根据regIds,发送消息到指定的一组设备上,retries为发送失败之后重试的次数。regIds的个数不得超过1000个。
send(List<TargetedMessage>messages, int retries) 发送一组消息。其中TargetedMessage类中封装了Message对象和该Message所要发送的目标。注意:messages内所有TargetedMessage对象的targetType必须相同,
不支持在一个调用中同时给regid和alias发送消息。
send(List<TargetedMessage> messages, int retries, long
timeToSend)
定时发送一组消息。timeToSend是用自1970年1月1日以来00:00:00.0 UTC时间表示(以毫秒为单位的时间)。注:仅支持七天内的定时消息。
sendToAlias(Message message, String alias, int retries) 根据alias,发送消息到指定设备上,retries为发送失败之后重试的次数。alias不允许全是空白字符,不能包含逗号,长度小于128,中英文均以一个计算。
sendToAlias(Message message, List<String> aliasList, int
retries)
根据aliasList,发送消息到指定的一组设备上,retries为发送失败之后重试的次数。aliasList中的每个元素不允许全是空白字符,不能包含逗号,长度小于128,中英文均以一个计算;元素的个数不得超过1000个。
sendToUserAccount(Message message, String userAccount, int retries) 根据account,发送消息到指定account上,retries为发送失败之后重试的次数。account不允许全是空白字符,不能包含逗号,长度小于128,中英文均以一个计算。
sendToUserAccount(Message message, List<String> accountList, int
retries)
根据accountList,发送消息到指定的一组设备上,retries为发送失败之后重试的次数。accountList中的每个元素不允许全是空白字符,不能包含逗号,长度小于128,中英文均以一个计算;元素的个数不得超过1000个。
broadcast(Message message, String topic, int retries) 根据topic,发送消息到指定一组设备上,retries为发送失败之后重试的次数。topic不允许全是空白字符,长度小于128,中英文均以一个计算。
broadcastAll(Message message, int retries) 向所有设备发送消息,retries为发送失败之后重试的次数。
multiTopicBroadcast(Message message, List<String> topics,
BROADCAST_TOPIC_OP topicOp, int retries)
向多个topic广播消息,支持topic间的交集、并集或差集(如果只有一个topic请用单topic版本)。其中,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的数量不能超过5。

checkScheduleJobExist(String msgId) 检测定时消息的任务是否存在。
deleteScheduleJob(String msgId) 删除指定的定时消息。

 

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();
     sender.send(message, regId, 0); //根据regID,发送消息到指定设备上,不重试。
}

private void sendMessages() throws Exception {
     Constants.useOfficial();
     Sender sender = new Sender(APP_SECRET_KEY);
     List<TargetedMessage> messages = new ArrayList<TargetdMessage>();
     TargetedMessage targetedMessage1 = new TargetedMessage();
     targetedMessage1.setTarget(TargetedMessage.TARGET_TYPE_ALIAS, “alias1”);
     String messagePayload1= “This is a message1”;
     String title1 = “notification title1”;
     String description1 = “notification description1”;
     Message message1 = new Message.Builder()
                .title(title1)
                .description(description1).payload(messagePayload1)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .notifyType(1)     // 使用默认提示音提示
                .build();
     targetedMessage1.setMessage(message1);
     messages.add(targetedMessage1);
     TargetedMessage targetedMessage2 = new TargetedMessage();
     targetedMessage1.setTarget(TargetedMessage.TARGET_TYPE_ALIAS, “alias2”);
     String messagePayload2= “This is a message2”;
     String title2 = “notification title2”;
     String description2 = “notification description2”;
     Message message2 = new Message.Builder()
                .title(title2)
                .description(description2).payload(messagePayload2)
                .restrictedPackageName(MY_PACKAGE_NAME)
                .notifyType(1)     // 使用默认提示音提示
                .build();
     targetedMessage2.setMessage(message2);
     messages.add(targetedMessage2);
     sender.send(messages, 0); //根据alias,发送消息到指定设备上,不重试。
}

private void sendMessageToAlias() 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”;
     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, 0); //根据alias,发送消息到指定设备上,不重试。
}

private void sendMessageToAliases() 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”;
     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, 0); //根据aliasList,发送消息到指定设备上,不重试。
}

private void sendBroadcast() 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”;
     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, 0); //根据topic,发送消息到指定一组设备上,不重试。
}

2.1.6. Result

Sender发送消息给服务器之后,服务器返回的结果

java.lang.Object
↳com.xiaomi.xmpush.server.Result

表 6. Result方法列表

方法名称 方法说明
String getMessageId() 如果消息发送成功,服务器返回消息的ID;如果发送失败,返回null。
ErrorCode getErrorCode() 发送消息返回的错误码,如果返回ErrorCode.Success表示发送成功,其他表示发送失败。
String getReason() 如果消息发送失败,服务器返回错误原因的文字描述;如果发送成功,返回null。

 

Result对于sendToAlias(),broadcast()和send()使用方式完全一样。

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, 0); //Result对于sendToAlias(),broadcast()和send()调用方式完全一样
     Log.v("Server response: ", "MessageId: " + result.getMessageId()
                                + " ErrorCode: " + result.getErrorCode().toString()
                                + " Reason: " + result.getReason());
}

2.1.7. Stats

获取发送的消息统计数据。

com.xiaomi.xmpush.server.HttpBase
↳com.xiaomi.xmpush.server.Stats

表 7. Stats方法列表

方法名称 方法说明
Stats(String appSecret) 构造Stats对象。appSecret是在开发者网站上注册时生成的, 可在应用详情下查看。
String getStats(String startDate, String endDate, String
restrictedPackageName, int retries)
获取指定日期范围内的日统计数据(如果日期范围包含今日,则今日数据为从今天00:00开始到现在的累计量)。

  1. 参数说明开始日期和结束日期必须符合yyyyMMdd的格式,并且时间跨度小于30天。
    • start_date表示开始日期,如20140214
    • end_date表示结束日期 ,如20140218
    • restrictedPackageName。
      • Android设备,传入App的包名
      • IOS设备,传入App的Bundle Id
    • retries表示重试的次数
  2. 返回值说明返回的是json格式的字符串。
    • 如果成功,则返回的字符串格式如下。{“result”:”ok”,”reason”:”成功”,”description”:”成功”,”data”:{“data”:”[{"date":"yyyyMMdd","single_recipients":XXXX,"broadcast_recipients":XX,"received":XXXX,"click":XXXX}...{"date":"yyyyMMdd","single_recipients":XXXX,"broadcast_recipients":XX,"received":XXXX,"click":XXXX}]“},”code”:0}其中,single_recipients表示的是单发(发送到指定的regid或者alias)消息量,broadcast_recipients表示的是群发(发送到指定的topic)消息量,received表示的是消息的接受量(包括单发消息和群发消息),click表示通知栏消息的点击量。
    • 如果失败,则返回的字符串格式如下。{“result”:”error”,”reason”:”XXXXXXXXX”,”description”:”XXXX”,”code”:XXXX}


Demo:

private void getStatsData() throws Exception {
     Constants.useOfficial();
     Stats stats = new Stats(APP_SECRET_KEY);
     String result = stats.getStats("20140218", "20140224", PACKAGE_NAME, 0);
}

2.1.8. Tracer

追踪消息状态。

com.xiaomi.xmpush.server.HttpBase
↳com.xiaomi.xmpush.server.Tracer

表 8. Tracer方法列表

方法名称 方法说明
Tracer(String appSecret) 构造Tracer对象。appSecret是在开发者网站上注册时生成的, 可在应用详情下查看。
String getMessageStatus(String msgId, int retries) 获取指定ID的消息状态。

  1. 参数说明
    • msgId: 发送消息时返回的msgId。
    • retries:重试的次数。
  2. 返回值说明
    • 如果成功,则返回的字符串格式如下。{“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}
String getMessageStatus(long beginTime, long endTime, int retries) 获取某个时间间隔内所有消息的状态。

  1. 参数说明
    • beginTime表示开始时间戳,单位ms。
    • endTime表示结束时间戳,单位ms。
    • retries表示重试的次数。
  2. 返回值说明
    • 如果成功,则返回的字符串格式如下。{“result”:”ok”,”reason”:”成功”,”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}其中,id表示单条消息的id;raw_counter表示https原始请求目标数invalid_target表示无效目标数可能是alias无效,regid无效,userAccount无效等等;app_not_register表示app没有注册push服务device_condition_unmatch表示设备所处的环境不符合消息设置的条件比如网络环境不匹配地域不匹配,app版本不匹配设备机型不匹配等等;delivered表示消息的送达数;resolved表示消息的计划送达数;delivery_rate表示送达率;click表示消息的点击数;click_rate表示消息的点击率;create_time表示消息的发送时间;time_to_live表示消息的有效期;msg_type表示该消息发送的方式(msg_type分为Common、BatchRegId、Alias、BatchAlias、Topic)。
    • 如果失败,则返回的字符串格式如下。{“result”:”error”,”reason”:”XXXXXXXXX”,”description”:”XXXX”,”code”:XXXX}

另外:

  1. 如果该时间区间内的消息数大于100条,则返回最接近结束时间的100条。
  2. 开始时间和结束时间之间的跨度不能大于7天。
String getMessageGroupStatus(String jobKey, int retries) 获取指定jobKey的消息组的消息发送状态。

  1. 参数说明
    • jobKey: 发送消息时设置的 jobKey
    • retries:重试的次数。
  2. 返回值说明参考getMessageStatus的返回值。

 

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(), 0);
        System.out.println(messageStatus2);
    }

2.1.9. Subscription

订阅/取消订阅标签。

com.xiaomi.xmpush.server.HttpBase
↳com.xiaomi.xmpush.server.Subscription

表 9. Subscription方法列表

方法名称 方法说明
Subscription(String appSecret) 构造Subscription对象。appSecret是在开发者网站上注册时生成的, 可在应用详情下查看。
subscribeTopic(List<String> regIds, String topic, String category, int
retries)
给一组regid列表订阅标签。其中,retries表示重试的次数,catergory可以使用null。限制:最多1000个regId。
subscribeTopic(List<String> regIds, String topic, String packageName,
String category, int retries)
给一组regid列表订阅标签。其中,retries表示重试的次数,catergory可以使用null。限制:最多1000个regId。备注:如果是多包名情况,即一个app对应有多个不同的包名,在订阅标签的时候,必须提供一个确切的包名;非多包名情况则不需要。
subscribeTopic(String regId, String topic, String category, int
retries)
给某个regid订阅标签。
subscribeTopic(String regId, String packageName, String topic, String
category, int retries)
给某个regid订阅标签。备注:如果是多包名情况,即一个app对应有多个不同的包名,在订阅标签的时候,必须提供一个确切的包名;非多包名情况则不需要。
unsubscribeTopic(List<String> regIds, String topic, String category, int
retries)
取消一组regid列表的标签。限制:最多1000个regId。
unsubscribeTopic(List<String> regIds, String topic, String packageName,
String category, int retries)
取消一组regid列表的标签。限制:最多1000个regId。备注:如果是多包名情况,即一个app对应有多个不同的包名,在取消订阅标签的时候,必须提供一个确切的包名;非多包名情况则不需要。
unsubscribeTopic(String regId, String topic, String category, int
retries)
取消某个regid的标签。
unsubscribeTopic(String regId, String topic, String packageName, String
category, int retries)
取消某个regid的标签。备注:如果是多包名情况,即一个app对应有多个不同的包名,在取消订阅标签的时候,必须提供一个确切的包名;非多包名情况则不需要。
subscribeTopicByAlias(String topic, List<String> aliases, String
category, int retries)
给一组alias列表订阅标签。限制:最多1000个alias。
subscribeTopicByAlias(String topic, List<String> aliases, String
packageName, String category, int retries)
给一组alias列表订阅标签。限制:最多1000个alias。备注:如果是多包名情况,即一个app对应有多个不同的包名,在订阅标签的时候,必须提供一个确切的包名;非多包名情况则不需要。
unsubscribeTopicByAlias(String topic, List<String> aliases, String
category, int retries)
取消一组alias列表的标签。限制:最多1000个alias。
unsubscribeTopicByAlias(String topic, List<String> aliases, String
packageName, String category, int retries)
取消一组alias列表的标签。限制:最多1000个alias。备注:如果是多包名情况,即一个app对应有多个不同的包名,在取消订阅标签的时候,必须提供一个确切的包名;非多包名情况则不需要。

 

2.1.10. Feedback

获取反馈信息。

com.xiaomi.xmpush.server.HttpBase
↳com.xiaomi.xmpush.server.Feedback

表 10. Feedback方法列表

方法名称 方法说明
Feedback(String appSecret) 构造Feedback对象。appSecret是在开发者网站上注册时生成的, 可在应用详情下查看。
getInvalidRegIds(int retries) 获取失效的regId列表。该API两点说明:

  1. 获取失效的regId列表,每次请求最多返回1000个regId。
  2. 每次请求之后,成功返回的失效的regId将会从MiPush数据库删除。

返回的是json格式的字符串,分为以下三种情况。

  • 存在失效的regid{“result”:”ok”,”description”:”成功”,”data”:{“list”:["regid1","regid2","regid3"]},”code”:0}
  • 不存在失效的regid{“result”:”ok”,”description”:”成功”,”data”:{“list”:[]},”code”:0}
  • 请求存在异常{“result”:”error”,”reason”:”Invalid application
    secret.”,”description”:”认证失败”,”code”:21301}

 

2.1.11. DevTools

设备工具集。

com.xiaomi.xmpush.server.HttpBase
↳com.xiaomi.xmpush.server.DevTools

表 11. DevTools方法列表

方法名称 方法说明
DevTools(String appSecret) 构造DevTools对象。appSecret是在开发者网站上注册时生成的, 可在应用详情下查看。
getAliasesOf(String packageName, String regId, int retries) 获取一个应用的某个用户目前设置的所有Alias。返回的是一个json格式的字符串,json的格式如下。

  • 如果成功,则返回{“result”:”ok”,”code”:0,”data”:{“list”:["XXXXXX","XXXXXX",...,"XXXXXX"]},”description”:”成功”}
  • 如果失败,则返回
    {“result”:”error”,”reason”:”XXXXXXXXX”,”description”:”XXXX”,”code”:XXXX}
getTopicsOf(String packageName, String regId, int retries) 获取一个应用的某个用户的目前订阅的所有Topic。返回的是一个json格式的字符串,json的格式如下。

  • 如果成功,则返回{“result”:”ok”,”code”:0,”data”:{“list”:["XXXXXX","XXXXXX",...,"XXXXXX"]},”description”:”成功”}
  • 如果失败,则返回
    {“result”:”error”,”reason”:”XXXXXXXXX”,”description”:”XXXX”,”code”:XXXX}

 

2.1.12. MessageRevoker

撤回通知栏消息

com.xiaomi.xmpush.server.MessageRevoker

表 12. MessageRevoker方法列表:

方法名称

方法说明

MessageRevoker(String appSecret)

构造函数,参数为app secret。

revokeMessage(String packageName, String title, String description, int notifyId, String[] topics, String msgId, int retries)

撤回通知栏消息

packageName表示包名,title表示消息标题,description表示消息描述,notifyId表示消息展示的位置,topics表示发topic消息时指定的topic,如果是多topic做交、并、差,则需要填写多个topic,msgId表示消息ID,retries表示发送请求失败后重试次数。(全量消息对应的topic为:**ALL**,仅适用于撤回)

Demo:

public void testMessageRevoker() throws Exception {
 MessageRevoker revoker = new MessageRevoker(APP_SECRET);
 String [] topics = {“topic1", “topic2"};
 String result = revoker.revokeMessage(packageName, "test title", "test description", 0, topics, "XXXXXX55481619324726hy", 1);
 System.out.println(result);
 }
}

2.1.13. Constants

系统常量定义

java.lang.Object
↳com.xiaomi.xmpush.server.Constants

如果需要在测试环境(Sandbox)和正式环境切换,
可以调用Constants.useSandbox()切换到开发环境上,使用测试环境(Sandbox)不会影响到线上的在线用户;开发完成后,再切换到正式环境。

注:测试环境只提供对IOS支持,不支持Android。

Demo:

Constants.useOfficial(); //使用正式环境
Constants.useSandbox(); //使用开发环境

2.1.14. ErrorCode

java.lang.Object
 com.xiaomi.push.sdk.ErrorCode

该类是服务器返回的错误码类

2.2. 针对Android设备提供的扩展功能

在利用Message.Builder构造Message对象时,通过调用extra(String key, String
value)方法设置key和value,可以自定义app的扩展功能。

2.2.1. 自定义消息铃声

调用Message.Builder类的extra(String key, String
value)方法将key设置为sound_uri(推荐使用我们预定义的常量Constants.EXTRA_PARAM_SOUND_URI=”sound_uri”),value设置为铃声的URI。

注:

  • 铃声只能使用当前app内的资源,URI格式满足 android.resource://your packagename/XXX/XXX。
  • 铃声文件放在Android app的raw目录下。
  • 只适用于通知栏消息。
  • 存储的声音文件需要有扩展名,但是不要把扩展名写在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)
             .passThrough(0)  //消息使用通知栏方式
             .notifyType(1)
             .extra(Constants.EXTRA_PARAM_SOUND_URI, "android.resource://" + PACKAGENAME + "/raw/shaking")
             .build();
     return message;
}

2.2.2. 开启/关闭app在前台时的通知弹出

当app在前台时,默认情况下服务端向客户端发送通知栏消息,app会弹出通知;如果开发者不想让客户端弹出通知,需要调用Message.Builder类的extra(String
key, String value)方法将key设置为Constants.EXTRA_PARAM_NOTIFY_FOREGROUND,value设置为”0″。

注:只适用于通知栏消息。

Android
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)
             .passThrough(0)  //消息使用通知栏方式
             .notifyType(1)
             .extra(Constants.EXTRA_PARAM_NOTIFY_FOREGROUND, "0")
             .build();
     return message;
}

2.2.3. 预定义通知栏通知的点击行为

目前支持三种预定义点击行为。

通过调用Message.Builder类的extra(String key, String value)方法,将key设置为Constants.EXTRA_PARAM_NOTIFY_EFFECT,value设置为Constants.NOTIFY_LAUNCHER_ACTIVITY、Constants.NOTIFY_ACTIVITY或Constants.NOTIFY_WEB以得到不同的预定义行为。

  1. Constants.NOTIFY_LAUNCHER_ACTIVITY:打开当前app对应的Launcher Activity。
  2. Constants.ACTIVITY:打开当前app内的任意一个Activity。
  3. Constants.NOTIFY_WEB:打开网页。

app打开相应的Activity后,可以调用Intent的getSerializableExtra(PushMessageHelper.KEY_MESSAGE)方法得到MiPushMessage对象。

客户端参考代码如下:

MiPushMessage message = (MiPushMessage) intent.getSerializableExtra(PushMessageHelper.KEY_MESSAGE);

注:用户点击预定义通知栏消息后,小米推送安卓客户端SDK会利用Intent将消息传到相应的Activity而不是通过调用onReceiveMessage(Context
context, MiPushMessage message)方法传过去。

2.2.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)
             .passThrough(0)  //消息使用通知栏方式
             .notifyType(1)
             .extra(Constants.EXTRA_PARAM_NOTIFY_EFFECT, Constants.NOTIFY_LAUNCHER_ACTIVITY)
             .build();
     return message;
}
2.2.3.2. 打开当前app内的任意一个Activity

调用Message.Builder类的extra(String key, String
value)方法将key设置为Constants.EXTRA_PARAM_NOTIFY_EFFECT,value设置为Constants.NOTIFY_ACTIVITY;再次调用extra(String
key, String value)方法,将key设置为Constants.EXTRA_PARAM_INTENT_URI,value设置为要启动Activity的intent
URI。

获取Intent URI的具体步骤是:

  1. 在安卓客户端的工程的AndroidManifest.xml里定义一个Activity。例如下面是一个展示新闻的Activity:
    <activity android:name=".NewsActivity"/>
  2. 定义一个Intent来启动该Activity。例如要打开 1.
    中定义的NewsActivity可定义Intent为:

    Intent intent = new Intent(context, NewsActivity.class);
  3. 把Intent转换成Intent URI字符串;转换得到的Intent URI的格式是:
    intent:#Intent;component=com.yourpackage/.YourActivity;end

    例如转换2.中的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.

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)
             .passThrough(0)  //消息使用通知栏方式
             .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();
}
2.2.3.3. 打开网页

调用Message.Builder类的extra(String key, String
value)方法将key设置为Constants.EXTRA_PARAM_NOTIFY_EFFECT,value设置为Constants.NOTIFY_WEB;再次调用extra(String
key, String value)方法,将key设置为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)
             .passThrough(0)  //消息使用通知栏方式
             .notifyType(1)
             .extra(Constants.EXTRA_PARAM_NOTIFY_EFFECT, Constants.NOTIFY_WEB)
             .extra(Constants.EXTRA_PARAM_WEB_URI, "http://www.xiaomi.com")
             .build();
     return message;
}

2.2.4. 使用自定义通知栏样式

如果系统默认的通知栏样式不满足需求,开发者可以自定义通知栏样式。SDK根据推送消息中指定的layout文件和填充内容,自由定制展示样式。

注意,在MIUI中,通知展示由系统通道负责,需要MIUI升级后才支持自定义通知。具体使用方法如下:

  1. layout文件中只能包含以下控件: FrameLayout, LinearLayout, RelativeLayout, Button, ImageButton, ImageView, ProgressBar, TextView
  2. 调用Message.Builder类的extra(String key, String
    value)方法将以“layout_name”为key,value设置为客户端要展示的layout文件名;
  3. 以“layout_value”为key,指定layout中各控件展示的内容,其value为一个Json。其格式为{“text”:{“txt_res_name1”:”txt_value1”, “txt_res_name2”:”txt_value2”…},
    “image”:{“img_res_name1”:”img_value1”, “img_res_name2”:”img_value2”…},
    “time”:{“time_res_name”:”format_value”}},其中:txt_res_name为layout文件中的控件名字,txt_value为控件上需要展示的文本内容。img_res_name为layout中需要展示图片资源的控件名字,img_value为程序中对应的资源名。time_res_name为layout文件中的控件名字,format_value为控件上需要展示的时间format样式。默认 yy-MM-dd
    hh:mm

Demo:以下消息,将指定以custom_notify为通知栏样式,将其中的titleText设置为“我是标题”,descText设置为“我是描述”;将iconImage设置为icon对应的图片。

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)
             .passThrough(0)  //消息使用通知栏方式
             .notifyType(1)
             .extra("layout_name","custom_notify")
             .extra("layout_value", "{\"text\":{\"titleText\":\"标题\"},\"image\": {\"iconImage\": \"icon\"},
                                      \"time\": {\"timeText\": \"HH:mm\"}}")​
             .build();
     return message;
}

2.2.5. 指定消息的过滤规则

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

表 13. 消息的过滤规则

​key value​含义
​locale 可以接收消息的设备的语言范围,用逗号分隔。当前设备的local的获取方法:

Locale.getDefault().toString()

比如,中国大陆用”zh_CN”表示。

​locale_not_in 无法收到消息的设备的语言范围,逗号分隔。
​model model支持三种用法。

  1. 可以收到消息的设备的机型范围,逗号分隔。当前设备的model的获取方法:
    Build.MODEL

    比如,小米手机4移动版用”MI 4LTE”表示。

  2. 可以收到消息的设备的品牌范围,逗号分割。比如,三星手机用”samsung”表示。 (目前覆盖42个主流品牌,对应关系见附录”品牌表”)
  3. 可以收到消息的设备的价格范围,逗号分隔。比如,0-999价格的设备用”0-999″表示。 (目前覆盖4个价格区间,对应关系见附录”价格表”)
​model_not_in 无法收到消息的设备的机型范围,逗号分隔​。
app_version 可以接收消息的app版本号,用逗号分割。安卓app版本号来源于manifest文件中的”android:versionName”的值。注:目前支持MiPush_SDK_Client_2_2_12_sdk.jar(及以后)的版本。
app_version_not_in 无法接收消息的app版本号,用逗号分割。
​connpt 指定在特定的网络环境下才能接收到消息。目前仅支持指定”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)
             .passThrough(0)  //消息使用通知栏方式
             .notifyType(1)
             .extra("locale","zh_CN")
             .build();
     return message;
}

2.2.6. 开启消息的送达和点击回执

开发者通过调用Message.Builder类的extra(String key, String value)来指定消息的送达和点击回执规则。

表 14. 消息的送达和点击回执规则

key value​含义
callback String,必填字段。第三方接收回执的http接口,最大长度128个字节。
callback.param String,可选字段。第三方自定义回执参数,最大长度64个字节。
callback.type int,可选字段。第三方所需要的回执类型。

  • 1 送达回执
  • 2 点击回执
  • 3 送达和点击回执

默认值为3。

 

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

注:消息的送达回执只支持向regId或alias发送的消息。

服务器POST一个JSON数据到callback 参数对应的url。

需要注意的是这里使用Content-Type为application/x-www-form-urlencoded的方式提交数据。

JSON对应的http参数名为data,JSON数据格式如下:

 {
      "msgId1":{"param":"param","type": 1, "targets":"alias1,alias2,alias3", "jobkey": "123"},
      "msgId2":{"param":"param","type": 2, "targets":"alias1,alias2,alias3", "jobkey": "456"}
  }

格式说明:外层key代表相应的消息msgId,value是一个JSONObject,包含了下面的参数值。

  • “param” 开发者上传的自定义参数值。
  • “type” callback类型。
  • “targets” 一批alias或者regId列表,之间是用逗号分割。
  • “jobkey” 发送消息时设置的jobkey值。

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)
             .passThrough(0)  //消息使用通知栏方式
             .notifyType(1)
             .extra("callback", "http://www.xiaomi.com/msgcallback")
             .build();
     return message;
}

2.2.7. 使用推送批次(JobKey)功能聚合消息

开发者在发送消息时可以设置消息的组ID(JobKey),带有相同的组ID的消息会被聚合为一个消息组。系统支持按照消息组展示消息详情以及计划推送/送达数量/送达曲线等统计信息。另外,相同JobKey的消息在客户端会进行去重,只展示其中的第一条。这样如果发送时同JobKey中不慎有重复的设备也不用担心用户会收到重复的通知。
设置消息的组ID 的方法是调用Message.Builder类的extra(String key, String
value)方法将key设置为”jobkey”,value设置为消息组的ID。合法的消息组ID由数字([0-9]),大小写字母([a-zA-Z]),下划线(_)和中划线(-)组成,长度不大于8个字符。

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)
             .passThrough(0)  //消息使用通知栏方式
             .notifyType(1)
             .extra("jobkey", "0115a001")
             .build();
     return message;
}

2.2.8. 开启通知消息在状态栏滚动显示

调用Message.Builder类的extra(String key, String
value)方法将key设置为”ticker”,value设置为状态栏滚动显示的内容。

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)
             .passThrough(0)  //消息使用通知栏方式
             .notifyType(1)
             .extra("ticker", "This is a ticker text.")
             .build();
     return message;
}

2.2.9. 配置捆绑通知

客户端版本 3.1 之后,就可以支持 Android N 的新特性:捆绑通知

需要调用 Message.Builder 类的 extra(String key, String value) 方法设置两个字段:一个的 key 为 “notification_group”,value 为分组的名称,另外一个的 key 为 “notification_is_summary”,value 为是否是分组的概述,分别对应 Notification.Builder 的 setGroup 方法和 setGroupSummary 方法。

Demo:

private Message buildMessage() throws Exception {
     String PACKAGENAME = "com.xiaomi.mipushdemo";
     String messagePayload = “This is a message with group.”;
     String title = “notification title”;
     String description = “notification description”;
     Message message = new Message.Builder()
             .title(title)
             .description(description).payload(messagePayload)
             .restrictedPackageName(MY_PACKAGE_NAME)
             .passThrough(0)  //消息使用通知栏方式
             .notifyType(1)
             .extra("notification_group", " news")
             .extra("notification_is_summary", "true")
             .build();
     return message;
}

2.3. 服务器API地址以及参数

如果用户期望开发其它平台的ServerSDK,下面提供的API地址和参数也许会有帮助。

注:sandbox API只提供对IOS支持,不支持Android。

推送单条消息(支持多包名)

  • 正式环境V2版接口
  • 向某个regid或一组regid列表推送某条消息https://api.xmpush.xiaomi.com/v2/message/regid
  • 向某个alias或一组alias列表推送某条消息https://api.xmpush.xiaomi.com/v2/message/alias
  • 向某个account或一组account列表推送某条消息https://api.xmpush.xiaomi.com/v2/message/user_account
  • 向某个topic推送某条消息https://api.xmpush.xiaomi.com/v2/message/topic
  • 向多个topic推送单条消息https://api.xmpush.xiaomi.com/v2/message/multi_topic
  • 向所有设备推送某条消息https://api.xmpush.xiaomi.com/v2/message/all

V3版接口(兼容V2版接口并支持多包名):

  • 向某个regid或一组regid列表推送某条消息(这些regId可以属于不同的包名)https://api.xmpush.xiaomi.com/v3/message/regid
  • 向某个alias或一组alias列表推送某条消息(这些alias可以属于不同的包名)https://api.xmpush.xiaomi.com/v3/message/alias
  • 向某个topic推送某条消息(可以指定一个或多个包名)https://api.xmpush.xiaomi.com/v3/message/topic
  • 向多个topic推送单条消息(可以指定一个或多个包名)https://api.xmpush.xiaomi.com/v3/message/multi_topic
  • 向所有设备推送某条消息(可以指定一个或多个包名)https://api.xmpush.xiaomi.com/v3/message/all
测试环境
  • 向某个regid或一组regid列表推送某条消息https://sandbox.xmpush.xiaomi.com/v2/message/regid
  • 向某个alias或一组alias列表推送某条消息https://sandbox.xmpush.xiaomi.com/v2/message/alias
  • 向某个account或一组account列表推送某条消息https://sandbox.xmpush.xiaomi.com/v2/message/user_account
  • 向某个topic推送某条消息https://sandbox.xmpush.xiaomi.com/v2/message/topic
  • 向多个topic推送单条消息https://sandbox.xmpush.xiaomi.com/v2/message/multi_topic
  • 向所有设备推送某条消息https://sandbox.xmpush.xiaomi.com/v2/message/all

HTTP请求方法:POST

添加HEADER字段Authorization,用于身份验证。格式是 key=<APP_SECRET>。
APP_SECRET是从开发者网站申请得到。

注意:字符key必须小写

例如:

Authorization: key=YOUR_APP_SECRET

表 15. Android POST参数说明: (需要对所有参数做urlencode处理)

类型 参数名称 参数说明
String payload 消息的内容。
String restricted_package_name App的包名。备注:V2版本支持一个包名,V3版本支持多包名(中间用逗号分割)。
Integer pass_through pass_through的值可以为:
  • 0 表示通知栏消息
  • 1 表示透传消息

Stringtitle通知栏展示的通知的标题。Stringdescription通知栏展示的通知的描述。Integernotify_typenotify_type的值可以是DEFAULT_ALL或者以下其他几种的OR组合:

  • DEFAULT_ALL = -1;
  • DEFAULT_SOUND  = 1;  // 使用默认提示音提示;
  • DEFAULT_VIBRATE = 2;  // 使用默认震动提示;
  • DEFAULT_LIGHTS = 4;   // 使用默认led灯光提示;

longtime_to_live可选项。如果用户离线,设置消息在服务器保存的时间,单位:ms。服务器默认最长保留两周。longtime_to_send可选项。定时发送消息。用自1970年1月1日以来00:00:00.0 UTC时间表示(以毫秒为单位的时间)。注:仅支持七天内的定时消息。Integernotify_id可选项。默认情况下,通知栏只显示一条推送消息。如果通知栏要显示多条推送消息,需要针对不同的消息设置不同的notify_id(相同notify_id的通知栏消息会覆盖之前的)。Stringextra.sound_uri可选项,自定义通知栏消息铃声。extra.sound_uri的值设置为铃声的URI。参考2.2.1注:铃声文件放在Android app的raw目录下。Stringextra.ticker可选项,开启通知消息在状态栏滚动显示。Stringextra.notify_foreground可选项,开启/关闭app在前台时的通知弹出。当extra.notify_foreground值为”1″时,app会弹出通知栏消息;当extra.notify_foreground值为”0″时,app不会弹出通知栏消息。注:默认情况下会弹出通知栏消息。参考2.2.2Stringextra.notify_effect可选项,预定义通知栏消息的点击行为。通过设置extra.notify_effect的值以得到不同的预定义点击行为。

  • “1″:通知栏点击后打开app的Launcher Activity。
  • “2″:通知栏点击后打开app的任一Activity(开发者还需要传入extra.intent_uri)。
  • “3″:通知栏点击后打开网页(开发者还需要传入extra.web_uri)。

参考2.2.3Stringextra.intent_uri可选项,打开当前app的任一组件。参考2.2.3.2Stringextra.web_uri可选项,打开某一个网页。参考2.2.3.3intextra.flow_control可选项,控制是否需要进行平缓发送。默认不支持。value代表平滑推送的速度。注:服务端支持最低1000/s的qps,最高100000/s。也就是说,如果将平滑推送设置为500,那么真实的推送速度是3000/s,如果大于1000小于100000,则以设置的qps为准。intextra.layout_name可选项,自定义通知栏样式,设置为客户端要展示的layout文件名。接口协议请参考2.2.4intextra.layout_value可选项,自定义通知栏样式,必须与layout_name一同使用,指定layout中各控件展示的内容。接口协议请参考2.2.4。Stringextra.jobkey可选项,使用推送批次(JobKey)功能聚合消息。客户端会按照jobkey去重,即相同jobkey的消息只展示第一条,其他的消息会被忽略。合法的jobkey由数字([0-9]),大小写字母([a-zA-Z]),下划线(_)和中划线(-)组成,长度不大于8个字符。Stringextra.callback可选项,开启消息送达和点击回执。将extra.callback的值设置为第三方接收回执的http接口。接口协议请参考2.2.6。Stringextra.​locale可选项,可以接收消息的设备的语言范围,用逗号分隔。当前设备的local的获取方法:

Locale.getDefault().toString()

比如,中国大陆用zh_CN表示。Stringextra.​locale_not_in可选项,无法收到消息的设备的语言范围,逗号分隔。Stringextra.​model可选项,model支持三种用法。

  1. 可以收到消息的设备的机型范围,逗号分隔。当前设备的model的获取方法:
    Build.MODEL

    比如,小米手机4移动版用”MI 4LTE”表示。

  2. 可以收到消息的设备的品牌范围,逗号分割。比如,三星手机用”samsung”表示。 (目前覆盖42个主流品牌,对应关系见附录”品牌表”)
  3. 可以收到消息的设备的价格范围,逗号分隔。比如,0-999价格的设备用”0-999″表示。 (目前覆盖4个价格区间,对应关系见附录”价格表”)

Stringextra.​model_not_in可选项,无法收到消息的设备的机型范围,逗号分隔。Stringextra.​app_version可以接收消息的app版本号,用逗号分割。安卓app版本号来源于manifest文件中的”android:versionName”的值。注:目前支持MiPush_SDK_Client_2_2_12_sdk.jar(及以后)的版本。Stringextra.​app_version_not_in无法接收消息的app版本号,用逗号分割。Stringextra.​connpt可选项,指定在特定的网络环境下才能接收到消息。目前仅支持指定”wifi”。以上参数适用于所有推送消息的HTTP API。Stringregistration_id根据registration_id,发送消息到指定设备上。可以提供多个registration_id,发送给一组设备,不同的registration_id之间用“,”分割。参数仅适用于“/message/regid”HTTP API。Stringalias根据alias,发送消息到指定的设备。可以提供多个alias,发送给一组设备,不同的alias之间用“,”分割。参数仅适用于“/message/alias”HTTP API。Stringuser_account根据user_account,发送消息给设置了该user_account的所有设备。可以提供多个user_account,user_account之间用“,”分割。参数仅适用于“/message/user_account”HTTP API。Stringtopic根据topic,发送消息给订阅了该topic的所有设备。参数仅适用于“/message/topic”HTTP API。Stringtopicstopic列表,使用;$;分割。注: topics参数需要和topic_op参数配合使用,另外topic的数量不能超过5。参数仅适用于“/message/multi_topic”HTTP API。Stringtopic_optopic之间的操作关系。支持以下三种:

  • UNION并集
  • INTERSECTION交集
  • EXCEPT差集

例如:

topics的列表元素是[A, B, C, D],则并集结果是A∪B∪C∪D,具体用法可以参考”Demo 8″,交集的结果是A ∩B ∩C
∩D,差集的结果是A-B-C-D。

参数仅适用于“/message/multi_topic”HTTP API。

 

表 16. IOS POST参数说明:

类型 参数名称 参数说明
String description 通知栏展示的通知的描述。
String aps_proper_fields.title 在通知栏展示的通知的标题(支持iOS10及以上版本,如有该字段,会覆盖掉description字段)。
String aps_proper_fields.subtitle 展示在标题下方的子标题(支持iOS10及以上版本,如有该字段,会覆盖掉description字段)。
String aps_proper_fields.body 在通知栏展示的通知的内容(支持iOS10及以上版本,如有该字段,会覆盖掉description字段)。
String aps_proper_fields.mutable-content 通知可以修改选项,设置之后,在展示远程通知之前会进入Notification Service Extension中允许程序对通知内容修改(支持iOS10及以上版本)。
long time_to_live 可选项。如果用户离线,设置消息在服务器保存的时间,单位:ms。服务器默认最长保留两周。
long time_to_send 可选项。定时发送消息。用自1970年1月1日以来00:00:00.0 UTC时间表示(以毫秒为单位的时间)。注:仅支持七天内的定时消息。
String extra.sound_url 可选项,自定义消息铃声。当值为空时为无声,default为系统默认声音。
int extra.badge 可选项。通知角标。
int extra.category 可选项。iOS8推送消息快速回复类别。
以上参数适用于所有推送消息的HTTP API。
String registration_id 根据registration_id,发送消息到指定设备上。可以提供多个registration_id,发送给一组设备,不同的registration_id之间用“,”分割。参数仅适用于“/message/regid”HTTP API。
String alias 根据alias,发送消息到指定的设备。可以提供多个alias,发送给一组设备,不同的alias之间用“,”分割。参数仅适用于“/message/alias”HTTP API。
String topic 根据topic,发送消息给订阅了该topic的所有设备。注:不同提供多个topic。参数仅适用于“/message/topic”HTTP API。
String topics topic列表,使用;$;分割。注: topics参数需要和topic_op参数配合使用。参数仅适用于“/message/multi_topic”HTTP API。
String topic_op topic之间的操作关系。支持以下三种:

  • UNION并集
  • INTERSECTION交集
  • EXCEPT差集

例如:

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

参数仅适用于“/message/multi_topic”HTTP API。

 

参数附加说明:

  1. 服务器端还可以定义一些以”extra.”开头的POST参数,POST参数形式如:extra.key=value。注:至多可以设置10个key-value键值对。
  2. 利用v2/message/all可以向所有设备发送消息。参数跟向topic发送消息类似,不需要额外提供topic域。
  3. 参数规范与Message类和Sender类中的描述相同。alias,topic,registration_id三者不能同时出现,alias可以有多个,表示向这些alias指定的设备发送消息。

返回的是json格式的字符串,包括以下几个字段。

  • “result”: string,”ok” 表示成功, “error” 表示失败。
  • “description”: string, 对发送消息失败原因的解释。
  • “data”: string,本身就是一个json字符串(其中id字段的值就是消息的Id)。
  • “code”: integer,0表示成功,非0表示失败。
  • “info”: string,详细信息。

例如:

{"result":"ok","description":"成功","data":{"id":"1000999_1375164696370"},"code":0,"info":"Received push messages for 1 regid"}
或
{"result":"error","reason":"payload参数不能为空","description":"缺失必选参数","code":10016}

Demo

  1. 向”alias1”,“alias2”,“alias3” 三个别名指定的设备发送消息。
    Request URL: https://api.xmpush.xiaomi.com/v2/message/alias 
    Request Method: POST
    Form Data:
    alias=alias1,alias2,alias3
    &description=notification description
    &payload=this+is+xiaomi+push
    &restricted_package_name=com.xiaomi.mipushdemo
    &title=notification title
    &notify_type=2
    &time_to_live=1000
    &pass_through=0
    &extra.sound_uri=android.resource://com.xiaomi.mipushdemo/raw/shaking
  2. 向registration_id为123指定的设备发送消息。
    Request URL: https://api.xmpush.xiaomi.com/v2/message/regid
    Request Method: POST
    Form Data:
    description=notification description
    &payload=this+is+xiaomi+push
    &restricted_package_name=com.xiaomi.mipushdemo
    &registration_id=123
    &title=notification title
    &notify_type=2
    &time_to_live=1000
    &notify_id=0
  3. 向订阅了my_topic的所有设备发送消息。
    Request URL: https://api.xmpush.xiaomi.com/v2/message/topic
    Request Method: POST
    Form Data:
    description=notification description
    &payload=this+is+xiaomi+push
    &restricted_package_name=com.xiaomi.mipushdemo
    &topic=my_topic
    &title=notification title
    &notify_type=2
    &time_to_live=1000
  4. 自定义点击行为:打开app的Launcher Activity
    Request URL: https://api.xmpush.xiaomi.com/v2/message/alias 
    Request Method: POST
    Form Data:
    alias=test_alias1
    &description=notification description
    &payload=this+is+xiaomi+push
    &restricted_package_name=com.xiaomi.mipushdemo
    &title=notification title
    &notify_type=2
    &time_to_live=1000
    &pass_through=0
    &extra.notify_effect=1
  5. 自定义点击行为:打开app的任一组件
    Request URL: https://api.xmpush.xiaomi.com/v2/message/alias 
    Request Method: POST
    Form Data:
    alias=test_alias1
    &description=notification description
    &payload=this+is+xiaomi+push
    &restricted_package_name=com.xiaomi.mipushdemo
    &title=notification title
    &notify_type=2
    &time_to_live=1000
    &pass_through=0
    &extra.notify_effect=2
    &extra.intent_uri=intent:#Intent;action=com.a.b.shot;end
  6. 自定义点击行为:打开网页
    Request URL: https://api.xmpush.xiaomi.com/v2/message/alias 
    Request Method: POST
    Form Data:
    alias=test_alias1
    &description=notification description
    &restricted_package_name=com.xiaomi.mipushdemo
    &title=notification title
    &notify_type=2
    &time_to_live=1000
    &pass_through=0
    &extra.notify_effect=3
    &extra.web_uri=http://www.xiaomi.com
  7. 自定义通知栏样式:
    Request URL: https://api.xmpush.xiaomi.com/v2/message/alias 
    Request Method: POST
    Form Data:
    alias=test_alias1
    &description=notification description
    &restricted_package_name=com.xiaomi.mipushdemo
    &title=notification title
    &notify_type=2
    &time_to_live=1000
    &pass_through=0
    &extra.layout_name=custom_notify
    &extra.layout_value={\"text\":{\"titleText\":\"我是标题\"},\"image\": {\"iconImage\": \"icon\"},\"time\": {\"timetext\": \"HH:mm\"}}
  8. 向订阅了[A,B,C,D]集合中任一标签的设备发送消息。
    Request URL: https://api.xmpush.xiaomi.com/v2/message/multi_topic
    Request Method: POST
    Form Data:
    description=notification description
    &payload=this+is+xiaomi+push
    &restricted_package_name=com.xiaomi.mipushdemo
    &topics=A;$;B;$;C;$;D
    &topic_op=UNION
    &title=notification title
    &notify_type=2
    &time_to_live=1000
  1. 推送多条消息
    • 正式环境针对不同的regid推送不同的消息https://api.xmpush.xiaomi.com/v2/multi_messages/regids针对不同的alias推送不同的消息https://api.xmpush.xiaomi.com/v2/multi_messages/aliases针对不同的userAccount推送不同的消息https://api.xmpush.xiaomi.com/v2/multi_messages/user_accounts
    • 测试环境针对不同的regid推送不同的消息https://sandbox.xmpush.xiaomi.com/v2/multi_messages/regids针对不同的alias推送不同的消息https://sandbox.xmpush.xiaomi.com/v2/multi_messages/aliases针对不同的userAccount推送不同的消息https://sandbox.xmpush.xiaomi.com/v2/multi_messages/user_accounts

    HTTP请求方法:POST

    添加HEADER字段Authorization,用于身份验证。格式是 key=<APP_SECRET>。
    APP_SECRET是从开发者网站申请得到。

    注意:字符key必须小写

    例如:

    Authorization: key=YOUR_APP_SECRET

    表 17. Android POST参数说明:(需要对所有参数做urlencode处理)

    类型 参数名称 参数说明
    String messages 发送的消息。messages是json格式的字符串。(注意:需要对messages字符串做urlencode处理)对于extra.sound_uri、extra.notify_foreground、extra.notify_effect、extra.intent_uri、extra.web_uri等以extra为前缀的Post参数,需要将它们定义成一个json字符串,格式如下:

    "extra":{"sound_uri":"XXX","notify_effect":"XX"....}

    当使用https://sandbox.xmpush.xiaomi.com/v2/multi_messages/regids时,格式满足:

    [
    {"target":"regid1","message":{"payload":"your content","restricted_package_name":
    "your packagename","pass_through":XXX,"notify_type":XXX,"description":"XXX",
    "title":"XXX","time_to_live":XXX,"notify_id":XXX,"extra":{"sound_uri":"XXX","notify_effect":"XX"....}}},
    {"target":"regids2","message":{......}},
    ...,
    {"target":"regidsN","message":{......}}
    ]

    当使用https://sandbox.xmpush.xiaomi.com/v2/multi_messages/aliases时,格式满足:

    [
    {"target":"alias1","message":{"payload":"your content","restricted_package_name":
    "your packagename","pass_through":XXX,"notify_type":XXX,"description":"XXX",
    "title":"XXX","time_to_live":XXX,"notify_id":XXX,"extra":{"sound_uri":"XXX","notify_effect":"XX"....}}},
    {"target":"alias2","message":{......}},
    ...,
    {"target":"aliasN","message":{......}}
    ]
    long time_to_send 可选项,定时发送批量消息。用自1970年1月1日以来00:00:00.0 UTC时间表示(以毫秒为单位的时间)。注:

    • 定时发送批量消息,不需要针对每条消息设置time_to_send。
    • 仅支持七天内的定时消息。

     

    表 18. IOS POST参数说明

    类型 参数名称 参数说明
    String messages 发送的消息。messages是json格式的字符串。(注意:需要对messages字符串做urlencode处理)对于extra.sound_url、extra.badge、extra.category等以extra为前缀的Post参数,需要将它们定义成一个json字符串,格式如下:

    "extra":{"sound_url":"XXX","badge":"XXX"....,"category":"XXX"}

    当使用https://sandbox.xmpush.xiaomi.com/v2/multi_messages/regids时,格式满足:

    [
    {"target":"regid1","message":{"description":"XXX","time_to_live":XXX,"extra":{"sound_url":"XXX","badge":"XXX","category":"XXX"....}}},
    {"target":"regids2","message":{......}},
    ...,
    {"target":"regidsN","message":{......}}
    ]

    当使用https://sandbox.xmpush.xiaomi.com/v2/multi_messages/aliases时,格式满足:

    [
    {"target":"alias1","message":{"description":"XXX","time_to_live":XXX,"extra":{"sound_url":"XXX","badge":"XXX","category":"XXX"....}}},
    {"target":"alias2","message":{......}},
    ...,
    {"target":"aliasN","message":{......}}
    ]
    long time_to_send 可选项,定时发送批量消息。用自1970年1月1日以来00:00:00.0 UTC时间表示(以毫秒为单位的时间)。注:

    • 定时发送批量消息,不需要针对每条消息设置time_to_send。
    • 仅支持七天内的定时消息。

     

    返回的是json格式的字符串,包括以下几个字段。

    • “result”: string,”ok” 表示成功, “error” 表示失败。
    • “description”: string, 对发送消息失败原因的解释。
    • “data”: string,本身就是一个json字符串(其中id字段的值就是消息的Id)。
    • “code”: integer,0表示成功,非0表示失败。
    • “info”: string,详细信息。

    Demo:

    注意:为了将json数据的格式看得比较清晰,我们没有做urlencode处理。但是,实际开发中必须对json数据做urlencode处理。

    1. 向不同的regid发送不同的消息
      https://api.xmpush.xiaomi.com/v2/multi_messages/regids
      ?messages=[{"target":"regid1","message":
      {"payload":"send message to regid1","restricted_package_name":"com.xiaomi.mipushdemo","pass_through":1,
      "notify_type":1,"description":"description1","title":"title1","time_to_live":100000,
      "extra":{"sound_uri":"android.resource://com.xiaomi.mipushdemo/raw/shaking"}}},
      {"target":"regid2","message":
      {"payload":"send message to regid2","restricted_package_name":"com.xiaomi.mipushdemo","pass_through":1,
      "notify_type":2,"description":"description2","title":"title2","time_to_live":20000}}]
    2. 向不同的alias发送不同的消息
      https://api.xmpush.xiaomi.com/v2/multi_messages/aliases
      ?messages=[{"target":"alias1","message":
      {"payload":"send message to alias1","restricted_package_name":"com.xiaomi.mipushdemo","pass_through":1,
      "notify_type":1,"description":"description1","title":"title1","time_to_live":100000}},
      {"target":"alias2","message":
      {"payload":"send message to alias2","restricted_package_name":"com.xiaomi.mipushdemo","pass_through":1,
      "notify_type":2,"description":"description2","title":"title2","time_to_live":20000}}]
  2. 获取消息的统计数据正式环境API地址:https://api.xmpush.xiaomi.com/v1/stats/message/counters HTTP请求方法:GET添加HEADER字段Authorization,用于身份验证。格式是 key=<APP_SECRET>。
    APP_SECRET是从开发者网站申请得到。注意:字符key必须小写例如:Authorization: key=YOUR_APP_SECRET

    表 19. GET参数说明:

    类型 参数名称 参数说明
    String start_date 表示开始日期,必须符合yyyyMMdd的格式。
    String end_date 表示结束日期,必须符合yyyyMMdd的格式。开始日期和结束日期之间的跨度小于30天。
    String restricted_package_name
    • Android设备,传入App的包名。
    • IOS设备,传入App的Bundle Id。

     

    返回的是json格式的字符串。

    • 如果成功,则返回的字符串格式如下。{“result”:”ok”,”description”:”成功”,”data”:{“data”:”[{"date":"yyyyMMdd","single_recipients":XXXX,"broadcast_recipients":XX,"received":XXXX,"click":XXXX}...{"date":"yyyyMMdd","single_recipients":XXXX,"broadcast_recipients":XX,"received":XXXX,"click":XXXX}]“},”code”:0}其中,single_recipients表示的是单发(发送到指定的regid或者alias)消息量,broadcast_recipients表示的是群发(发送到指定的topic)消息量,received表示的是消息的接受量(包括单发消息和群发消息),click表示通知栏消息的点击量。
    • 如果失败,则返回的字符串格式如下。{“result”:”error”,”reason”:”XXXXXXXXX”,”description”:”XXXX”,”code”:XXXX}

    Demo:

    https://api.xmpush.xiaomi.com/v1/stats/message/counters
    ?start_date=20140428
    &end_date=20140429
    &restricted_package_name=com.xiaomi.mipushdemo

    返回结果

     {"result":"ok","description":"成功","data":{"data":"[
      {\"date\":\"20140428\",\"single_recipients\":0,\"broadcast_recipients\":7689,\"received\":7026,\"click\":1703},
      {\"date\":\"20140429\",\"single_recipients\":0,\"broadcast_recipients\":5129,\"received\":4642,\"click\":1256}
      ]"},"code":0}
  3. 追踪消息状态正式环境API地址:
    1. 追踪消息https://api.xmpush.xiaomi.com/v1/trace/message/status
    2. 追踪某个时间区域内的消息https://api.xmpush.xiaomi.com/v1/trace/messages/status

    HTTP请求方法:GET

    添加HEADER字段Authorization,用于身份验证。格式是 key=<APP_SECRET>。
    APP_SECRET是从开发者网站申请得到。

    注意:字符key必须小写

    例如:

    Authorization: key=YOUR_APP_SECRET

    表 20. 追踪消息的GET参数说明:

    类型 参数名称 参数说明
    String msg_id 可选项,表示消息的Id。
    String job_key 可选项,消息组的jobKey。如果jobKey不为空,则查询消息组的状态。否则,使用msg_id 查询单条消息的状态。

     

    返回的是json格式的字符串。

    Demo:

    {"result":"ok","description":"成功","data":{"data":"
    {\"id\":\"s1005246409317636237jB\",\"delivery_rate\":\"100%\",\"delivered\":1,\"resolved\":1,
    \"msg_type\":\"BatchRegId\",\"create_time\":\"2014-08-29 21:07:16\",\"time_to_live\":\"1209600s\",
    \"click\":0,\"click_rate\":\"0%\"}"},"code":0}

    其中,id
    表示单条消息的id,delivered表示消息的送达数,resolved表示消息的计划送达数,delivery_rate表示送达率,click表示消息的点击数,click_rate表示消息的点击率,create_time表示消息的发送时间,time_to_live表示消息的有效期,msg_type表示该消息发送的方式(msg_type分为Common、BatchRegId、Alias、BatchAlias、Topic)。

    表 21. 追踪某个时间区域内消息的GET参数说明:

    类型 参数名称 参数说明
    long begin_time 表示开始时间戳,单位ms。
    long end_time 表示结束时间戳,单位ms。

     

    返回的是json格式的字符串。

    Demo:

    {"result":"ok","description":"成功","data":{"data":"[
    {\"id\":\"a1000270409820283940fp\",\"delivery_rate\":\"100%\",\"delivered\":2,\"resolved\":2,
    \"msg_type\":\"BatchAlias\",\"create_time\":\"2014-09-04 16:44:43\",\"time_to_live\":\"109s\",
    \"create_timestamp\":1409820283941,\"click\":0,\"click_rate\":\"0%\"},
    {\"id\":\"s1000270409820247716NA\",\"delivery_rate\":\"100%\",\"delivered\":2,\"resolved\":2,
    \"msg_type\":\"BatchRegId\",\"create_time\":\"2014-09-04 16:44:07\",\"time_to_live\":\"109s\",
    \"create_timestamp\":1409820247717,\"click\":0,\"click_rate\":\"0%\"},
    {\"id\":\"a1000270409820207789dJ\",\"delivery_rate\":\"0%\",\"delivered\":0,\"resolved\":1,
    \"msg_type\":\"Alias\",\"create_time\":\"2014-09-04 16:43:27\",\"time_to_live\":\"1209600s\",
    \"create_timestamp\":1409820207789,\"click\":0,\"click_rate\":\"0%\"},
    {\"id\":\"t1000270409820155849Ek\",\"delivery_rate\":\"100%\",\"delivered\":2,\"resolved\":2,
    \"msg_type\":\"Topic\",\"create_time\":\"2014-09-04 16:42:35\",\"time_to_live\":\"109s\",
    \"create_timestamp\":1409820155849,\"click\":0,\"click_rate\":\"0%\"},
    {\"id\":\"s10002704098201310026i\",\"delivery_rate\":\"0%\",\"delivered\":0,\"resolved\":1,
    \"msg_type\":\"Common\",\"create_time\":\"2014-09-04 16:42:11\",\"time_to_live\":\"1209600s\",
    \"create_timestamp\":1409820131002,\"click\":0,\"click_rate\":\"0%\"}]"},"code":0}
  4. 订阅/取消订阅标签
    • 正式环境订阅RegId的标签https://api.xmpush.xiaomi.com/v2/topic/subscribe取消订阅RegId的标签https://api.xmpush.xiaomi.com/v2/topic/unsubscribe订阅alias的标签https://api.xmpush.xiaomi.com/v2/topic/subscribe/alias取消订阅alias的标签https://api.xmpush.xiaomi.com/v2/topic/unsubscribe/alias
    • 测试环境订阅RegId的标签https://sandbox.xmpush.xiaomi.com/v2/topic/subscribe取消订阅RegId的标签https://sandbox.xmpush.xiaomi.com/v2/topic/unsubscribe订阅alias的标签https://sandbox.xmpush.xiaomi.com/v2/topic/subscribe/alias取消订阅alias的标签https://sandbox.xmpush.xiaomi.com/v2/topic/unsubscribe/alias

    HTTP请求方法:POST

    添加HEADER字段Authorization,用于身份验证。格式是 key=<APP_SECRET>。
    APP_SECRET是从开发者网站申请得到。

    注意:字符key必须小写

    例如:

    Authorization: key=YOUR_APP_SECRET

    • 针对/v2/topic/subscribe和/v2/topic/unsubscribe的参数说明:

      表 22. 订阅/取消订阅RegId的标签的GET参数说明:

      类型 参数名称 参数说明
      String registration_id 设备regid列表,逗号分隔,必填。限制:最多1000个regid。
      String topic 标签,必填。
      String restricted_package_name 包名。注意:app设置了多包名,则必填。
      String category 可选。

       

      Demo:

      https://api.xmpush.xiaomi.com/v2/topic/subscribe
      ?registration_id=abc
      &topic=tt
    • 针对/v2/topic/subscribe/alias和/v2/topic/unsubscribe/alias的参数说明:

      表 23. 订阅/取消订阅alias的标签的GET参数说明:

      类型 参数名称 参数说明
      String aliases 各个alias之间用逗号分割,必填。限制:最多1000个alias。
      String topic 标签,必填。
      String restricted_package_name 包名。注意:app设置了多包名,则必填。
      String category 可选。

       

      Demo:

      https://api.xmpush.xiaomi.com/v2/topic/subscribe/alias
      ?aliases=a1
      &topic=tt
  5. 获取失效的regId列表正式环境API地址:https://feedback.xmpush.xiaomi.com/v1/feedback/fetch_invalid_regidsHTTP请求方法:GET添加HEADER字段Authorization,用于身份验证。格式是 key=<APP_SECRET>。
    APP_SECRET是从开发者网站申请得到。注:字符key必须小写。另外,目前仅支持安卓设备。例如:Authorization: key=YOUR_APP_SECRET该HTTP请求的几点说明:

    1. 获取失效的regId列表不需要传递任何HTTP参数。
    2. 获取失效的regId列表,每次请求最多返回1000个regId。
    3. 每次请求之后,成功返回的失效的regId将会从MiPush数据库删除。

    返回的是json格式的字符串,分为以下三种情况。

    • 存在失效的regid{“result”:”ok”,”description”:”成功”,”data”:{“list”:["regid1","regid2","regid3"]},”code”:0}
    • 不存在失效的regid{“result”:”ok”,”description”:”成功”,”data”:{“list”:[]},”code”:0}
    • 请求存在异常{“result”:”error”,”reason”:”Invalid application
      secret.”,”description”:”认证失败”,”code”:21301}
  6. 获取一个应用的某个用户目前设置的所有Alias正式环境API地址:https://api.xmpush.xiaomi.com/v1/alias/allHTTP请求方法:GET添加HEADER字段Authorization,用于身份验证。格式是 key=<APP_SECRET>。
    APP_SECRET是从开发者网站申请得到。注:字符key必须小写。例如:Authorization: key=YOUR_APP_SECRET

    表 24. 获取所有Alias的GET参数说明:

    类型 参数名称 参数说明
    String restricted_pa​ckage_name 可选。应用包名,因为一个AppId可能对应多个包名,使用该参数指定具体的包名。
    String registrati​on_id 查询设备的regId。

     

    返回的是json格式的字符串。

    • 如果成功,则返回的字符串格式如下。​{“result”:”ok”,”code”:0,”data”:{“list”:["XXXXXX","XXXXXX",...,"XXXXXX"]},”description”:”成功”}
    • 如果失败,则返回的字符串格式如下。{“result”:”error”,”reason”:”XXXXXXXXX”,”description”:”XXXX”,”code”:XXXX}
  7. 获取一个应用的某个用户目前订阅的所有Topic正式环境API地址:https://api.xmpush.xiaomi.com/v1/topic/allHTTP请求方法:GET添加HEADER字段Authorization,用于身份验证。格式是 key=<APP_SECRET>。
    APP_SECRET是从开发者网站申请得到。注:字符key必须小写。例如:Authorization: key=YOUR_APP_SECRET

    表 25. 获取所有Topic的GET参数说明:

    类型 参数名称 参数说明
    String restricted_pa​ckage_name 可选。应用包名,因为一个AppId可能对应多个包名,使用该参数指定具体的包名。
    String registrati​on_id 查询设备的regId。

     

    返回的是json格式的字符串。

    • 如果成功,则返回的字符串格式如下。​{“result”:”ok”,”code”:0,”data”:{“list”:["XXXXXX","XXXXXX",...,"XXXXXX"]},”description”:”成功”}
    • 如果失败,则返回的字符串格式如下。{“result”:”error”,”reason”:”XXXXXXXXX”,”description”:”XXXX”,”code”:XXXX}
  8. 检测/删除定时任务正式环境API地址:检测定时任务是否存在https://api.xmpush.xiaomi.com/v2/schedule_job/exist删除定时任务https://api.xmpush.xiaomi.com/v2/schedule_job/deleteHTTP请求方法:POST添加HEADER字段Authorization,用于身份验证。格式是 key=<APP_SECRET>。
    APP_SECRET是从开发者网站申请得到。注:字符key必须小写。例如:Authorization: key=YOUR_APP_SECRET

    表 26. 参数列表

    类型 参数名称 参数说明
    String job_id 表示消息的Id。

     

    返回的是json格式的字符串。

    code是0,表示成功;否则表示失败,reason表示失败的原因。

3. 附录

表 27. 品牌表

品牌 model
小米 xiaomi
三星 samsung
华为 huawei
中兴 zte
中兴努比亚 nubia
酷派 coolpad
联想 lenovo
魅族 meizu
HTC htc
OPPO oppo
VIVO vivo
摩托罗拉 motorola
索尼 sony
LG lg
金立 jinli
天语 tianyu
诺基亚 nokia
美图秀秀 meitu
谷歌 google
TCL tcl
锤子手机 chuizi
一加手机 1+
中国移动 china mobile
昂达 angda
邦华 banghua
波导 bird
长虹 changhong
大可乐 dakele
朵唯 doov
海尔 haier
海信 hisense
康佳 konka
酷比魔方 kubimofang
米歌 mige
欧博信 ouboxin
欧新 ouxin
飞利浦 philip
维图 voto
小辣椒 xiaolajiao
夏新 xiaxin
亿通 yitong
语信 yuxin

 

表 28. 价格表

价格区间 model
0-999 0-999
1000-1999 1000-1999
2000-3999 2000-3999
4000以上 4000+