友盟+搜索

{{errorMsg}}

概述

基本说明

本文所描述的API接口均基于HTTP Rest协议, 若无特殊说明接口均使用UTF-8编码, 消息体参数以及返回结果均采用Json格式。
注意: 使用API前需要在Web后台的App应用信息页面获取 appkeyapp_master_secret,同时在web后台添加 服务器IP地址 做IP白名单安全验证。如下图。

基本概念

appkey:应用唯一标识。友盟消息推送服务提供的appkey和友盟统计分析平台使用的同一套appkey。
app_master_secret:服务器秘钥,用于服务器端调用API请求时对发送内容做签名验证。
device_token: 友盟消息推送服务对设备的唯一标识。Android的device_token是44位字符串, iOS的device-token是64位。
alias: 开发者自有账号, 开发者可以在SDK中调用setAlias(alias, alias_type)接口将alias+alias_type与device_token做绑定, 之后开发者就可以根据自有业务逻辑筛选出alias进行消息推送。
单播(unicast): 向指定的设备发送消息,包括向单个device_token或者单个alias发消息。
列播(listcast): 向指定的一批设备发送消息,包括向多个device_token或者多个alias发消息。
广播(broadcast): 向安装该App的所有设备发送消息。
组播(groupcast): 向满足特定条件的设备集合发送消息,例如: "特定版本"、"特定地域"等。友盟消息推送所支持的维度筛选和友盟统计分析所提供的数据展示维度是一致的,后台数据也是打通的
文件播(filecast): 开发者将批量的device_token或者alias存放到文件, 通过文件ID进行消息发送。
自定义播(customizedcast): 开发者通过自有的alias进行推送, 可以针对单个或者一批alias进行推送,也可以将alias存放到文件进行发送。
任务: 除单播、列播外的其它类型的播类型均称为任务。任务支持查询、撤销操作。
通知-Android(notification): 消息送达到用户设备后,由友盟SDK接管处理并在通知栏上显示通知内容。
消息-Android(message): 消息送达到用户设备后,消息内容透传给应用自身进行解析处理。
通知/消息-iOS: 和APNs定义一致。
测试模式: 在广播、组播等大规模发送消息的情况下,为了防止开发者误将测试消息大面积发给线上用户,特增加了测试模式。 测试模式下,只会将消息发送给测试设备。测试设备需要到网站上手工添加。
测试模式-Android: Android的测试设备是正式设备的一个子集
测试模式-iOS: iOS的测试模式对应APNs的开发环境(sandbox), 正式模式对应APNs的生产环境(prod),测试设备和正式设备完全隔离。
签名: 为了保证调用API的请求是合法者发送且参数没有被篡改,需要在调用API时对发送的所有内容进行签名。签名附加在调用地址后面,签名的计算方式参见附录K。

接口描述

消息发送

功能说明

开发者调用此接口,向 指定终端用户(单播)所有终端用户(广播)满足特定条件的终端用户群(组播),发送 通知消息。此外,该接口还支持开发者使用 自有的账号系统(alias) 来发送消息给指定的账号或者账号群。
注意,iOS推送的相关协议,请严格按照APNs的协议来填写,友盟完全遵循APNs的协议。

调用地址

POST 

http接口:http://msg.umeng.com/api/send?sign=mysign

https接口:  https://msgapi.umeng.com/api/send?sign=mysign

签名(sign=mysign)的计算方式参见附录K。

调用参数

Android:

{
  "appkey":"xx",          // 必填 应用唯一标识
  "timestamp":"xx",       // 必填 时间戳,10位或者13位均可,时间戳有效期为10分钟
  "type":"xx",            // 必填 消息发送类型,其值可以为:
                                  unicast-单播
                                  listcast-列播(要求不超过500个device_token)
                                  filecast-文件播
                                    (多个device_token可通过文件形式批量发送)
                                  broadcast-广播
                                  groupcast-组播
                                    (按照filter条件筛选特定用户群, 具体请参照filter参数)
                                  customizedcast(通过开发者自有的alias进行推送), 
                                  包括以下两种case:
                                     - alias: 对单个或者多个alias进行推送
                                     - file_id: 将alias存放到文件后,根据file_id来推送
  "device_tokens":"xx",   // 可选 设备唯一表示
                                  当type=unicast时,必填, 表示指定的单个设备
                                  当type=listcast时,必填,要求不超过500个,
                                  多个device_token以英文逗号间隔
  "alias_type": "xx"      // 可选 当type=customizedcast时,必填,alias的类型, 
                                  alias_type可由开发者自定义,开发者在SDK中
                                  调用setAlias(alias, alias_type)时所设置的alias_type
  "alias":"xx",           // 可选 当type=customizedcast时, 开发者填写自己的alias。
                                  要求不超过50个alias,多个alias以英文逗号间隔。
                                  在SDK中调用setAlias(alias, alias_type)时所设置的alias
  "file_id":"xx",         // 可选 当type=filecast时,file内容为多条device_token, 
                                    device_token以回车符分隔
                                  当type=customizedcast时,file内容为多条alias,
                                    alias以回车符分隔,注意同一个文件内的alias所对应
                                    的alias_type必须和接口参数alias_type一致。
                                  注意,使用文件播前需要先调用文件上传接口获取file_id, 
                                     具体请参照"2.4文件上传接口"
  "filter":{},            // 可选 终端用户筛选条件,如用户标签、地域、应用版本以及渠道等,
                                  具体请参考附录G。
  "payload":              // 必填 消息内容(Android最大为1840B), 包含参数说明如下(JSON格式):
  {
    "display_type":"xx",  // 必填 消息类型,值可以为:
                                  notification-通知,message-消息
    "body":               // 必填 消息体。
                                  display_type=message时,body的内容只需填写custom字段。
                                  display_type=notification时, body包含如下参数:
    {
        // 通知展现内容:
        "ticker":"xx",     // 必填 通知栏提示文字
        "title":"xx",      // 必填 通知标题
        "text":"xx",       // 必填 通知文字描述 

        // 自定义通知图标:
        "icon":"xx",       // 可选 状态栏图标ID, R.drawable.[smallIcon],
                                   如果没有, 默认使用应用图标。
                                   图片要求为24*24dp的图标,或24*24px放在drawable-mdpi下。
                                   注意四周各留1个dp的空白像素
        "largeIcon":"xx",  // 可选 通知栏拉开后左侧图标ID, R.drawable.[largeIcon].
                                   图片要求为64*64dp的图标,
                                   可设计一张64*64px放在drawable-mdpi下,
                                   注意图片四周留空,不至于显示太拥挤
        "img": "xx",       // 可选 通知栏大图标的URL链接。该字段的优先级大于largeIcon。
                                   该字段要求以http或者https开头。

        // 自定义通知声音:
        "sound": "xx",     // 可选 通知声音,R.raw.[sound]. 
                                   如果该字段为空,采用SDK默认的声音, 即res/raw/下的
                                       umeng_push_notification_default_sound声音文件
                                   如果SDK默认声音文件不存在,
                                       则使用系统默认的Notification提示音。

        // 自定义通知样式:
        "builder_id": xx   // 可选 默认为0,用于标识该通知采用的样式。使用该参数时, 
                       开发者必须在SDK里面实现自定义通知栏样式。

        // 通知到达设备后的提醒方式
        "play_vibrate":"true/false", // 可选 收到通知是否震动,默认为"true".
                       注意,"true/false"为字符串
        "play_lights":"true/false",  // 可选 收到通知是否闪灯,默认为"true"
        "play_sound":"true/false",   // 可选 收到通知是否发出声音,默认为"true"

        // 点击"通知"的后续行为,默认为打开app。
        "after_open": "xx" // 必填 值可以为:
                                   "go_app": 打开应用
                                   "go_url": 跳转到URL
                                   "go_activity": 打开特定的activity
                                   "go_custom": 用户自定义内容。
        "url": "xx",       // 可选 当"after_open"为"go_url"时,必填。
                                   通知栏点击后跳转的URL,要求以http或者https开头  
        "activity":"xx",   // 可选 当"after_open"为"go_activity"时,必填。
                                   通知栏点击后打开的Activity
        "custom":"xx"/{}   // 可选 display_type=message, 或者
                                   display_type=notification且
                                   "after_open"为"go_custom"时,
                                   该字段必填。用户自定义内容, 可以为字符串或者JSON格式。
    },
    extra:                 // 可选 用户自定义key-value。只对"通知"
                                   (display_type=notification)生效。
                                   可以配合通知到达后,打开App,打开URL,打开Activity使用。
    {
        "key1": "value1",
        "key2": "value2",
        ...
    }
  },
  "policy":                // 可选 发送策略
  {
      "start_time":"xx",   // 可选 定时发送时间,若不填写表示立即发送。
                                   定时发送时间不能小于当前时间
                                   格式: "yyyy-MM-dd HH:mm:ss"。 
                                   注意, start_time只对任务生效。
      "expire_time":"xx",  // 可选 消息过期时间,其值不可小于发送时间或者
                                   start_time(如果填写了的话), 
                                   如果不填写此参数,默认为3天后过期。格式同start_time
      "max_send_num": xx   // 可选 发送限速,每秒发送的最大条数。
                                   开发者发送的消息如果有请求自己服务器的资源,可以考虑此参数。
      "out_biz_no": "xx"     // 可选 开发者对消息的唯一标识,服务器会根据这个标识避免重复发送。
                                   有些情况下(例如网络异常)开发者可能会重复调用API导致
                                   消息多次下发到客户端。如果需要处理这种情况,可以考虑此参数。
                                   注意, out_biz_no只对任务生效。
  },
  "production_mode":"true/false" // 可选 正式/测试模式。测试模式下,只会将消息发给测试设备。
                                         测试设备需要到web上添加。
                                         Android: 测试设备属于正式设备的一个子集。
  "description": "xx"      // 可选 发送消息描述,建议填写。
  "thirdparty_id": "xx"    // 可选 开发者自定义消息标识ID, 开发者可以为同一批发送的多条消息
                                   提供同一个thirdparty_id, 便于友盟后台后期合并统计数据。  
}

iOS

{
  "appkey":"xx",          // 必填 应用唯一标识
  "timestamp":"xx",       // 必填 时间戳,10位或者13位均可,时间戳有效期为10分钟
  "type":"xx",            // 必填 消息发送类型,其值可以为:
                                  unicast-单播
                                  listcast-列播(要求不超过500个device_token)
                                  filecast-文件播
                                    (多个device_token可通过文件形式批量发送)
                                  broadcast-广播
                                  groupcast-组播
                                    (按照filter条件筛选特定用户群, 具体请参照filter参数)
                                  customizedcast(通过开发者自有的alias进行推送), 
                                  包括以下两种case:
                                     - alias: 对单个或者多个alias进行推送
                                     - file_id: 将alias存放到文件后,根据file_id来推送
  "device_tokens":"xx",   // 可选 设备唯一表示
                                  当type=unicast时,必填, 表示指定的单个设备
                                  当type=listcast时,必填,要求不超过500个,
                                  多个device_token以英文逗号间隔
  "alias_type": "xx"      // 可选 当type=customizedcast时,必填,alias的类型, 
                                  alias_type可由开发者自定义,开发者在SDK中
                                  调用setAlias(alias, alias_type)时所设置的alias_type
  "alias":"xx",           // 可选 当type=customizedcast时, 开发者填写自己的alias。
                                  要求不超过50个alias,多个alias以英文逗号间隔。
                                  在SDK中调用setAlias(alias, alias_type)时所设置的alias
  "file_id":"xx",         // 可选 当type=filecast时,file内容为多条device_token, 
                                    device_token以回车符分隔
                                  当type=customizedcast时,file内容为多条alias,
                                    alias以回车符分隔,注意同一个文件内的alias所对应
                                    的alias_type必须和接口参数alias_type一致。
                                  注意,使用文件播前需要先调用文件上传接口获取file_id, 
                                     具体请参照"2.4文件上传接口"
  "filter":{},            // 可选 终端用户筛选条件,如用户标签、地域、应用版本以及渠道等,
                                  具体请参考附录G。
  "payload":              // 必填 消息内容(iOS最大为2012B), 包含参数说明如下(JSON格式):
  {
    "aps":                 // 必填 严格按照APNs定义来填写
    {
        "alert": "xx"          // 必填                    
        "badge": xx,           // 可选        
        "sound": "xx",         // 可选         
        "content-available":xx // 可选       
        "category": "xx",      // 可选, 注意: ios8才支持该字段。
    },
    "key1":"value1",       // 可选 用户自定义内容, "d","p"为友盟保留字段,
                                  key不可以是"d","p"
    "key2":"value2",       
    ...
  },
  "policy":                // 可选 发送策略
  {
      "start_time":"xx",   // 可选 定时发送时间,默认为立即发送。发送时间不能小于当前时间。
                                   格式: "YYYY-MM-DD HH:mm:ss"。 
                                   注意, start_time只对任务生效。
      "expire_time":"xx",  // 可选 消息过期时间,其值不可小于发送时间,
                                   默认为3天后过期。格式同start_time
      "max_send_num": xx   // 可选 发送限速,每秒发送的最大条数。
                                   开发者发送的消息如果有请求自己服务器的资源,可以考虑此参数。
      "apns-collapse-id":"xx"  //可选,iOS10开始生效。
  },
  "production_mode":"true/false" // 可选 正式/测试模式。测试模式下,广播/组播只会将消息发给测试设备。
                                         测试设备需要到web上添加。
                                         iOS: 测试模式对应APNs的开发环境(sandbox),
                                              正式模式对应APNs的正式环境(prod), 
                                              正式、测试设备完全隔离。
  "description": "xx"      // 可选 发送消息描述,建议填写。
  "thirdparty_id": "xx"    // 可选 开发者自定义消息标识ID, 开发者可以为同一批发送的消息提供
                                   同一个thirdparty_id, 便于后期合并统计数据。  
}

调用返回

在正常情况下,返回结果的HTTP状态码为200,错误情况下返回的HTTP状态码为400。 返回结果采用Json格式,包含的参数有:

{
  "ret":"SUCCESS/FAIL", // 返回结果,"SUCCESS"或者"FAIL"
  "data": 
    {
      // 当"ret"为"SUCCESS"时,包含如下参数:
          // 当type为unicast、listcast或者customizedcast且alias不为空时:
          "msg_id":"xx" 
          // 当type为于broadcast、groupcast、filecast、customizedcast
          且file_id不为空的情况(任务)
          "task_id":"xx"

      // 当"ret"为"FAIL"时,包含如下参数:
      "error_code":"xx" // 错误码详见附录I。

      //如果开发者填写了thirdparty_id, 接口也会返回该值。
      "thirdparty_id": "xx"
    }  
}

实例请参考附录A~F。
错误码详见附录I。

任务状态查询

功能说明

当消息发送的类型为任务时,包括"broadcast","groupcast", "filecast","customizedcast(通过file_id传参)"时, 可以通过"task_id"来查询当前的消息状态。
注意,当次发送任务如果发送总量小于500个的话,后台会按照列播的方式推送,不再按照任务的方式来处理。 该接口会不生效。

调用地址

POST 

http接口:http://msg.umeng.com/api/status?sign=mysign

https接口:  https://msgapi.umeng.com/api/status?sign=mysign

签名(sign=mysign)的计算方式参见附录K。

调用参数

{
  "appkey":"xx",     // 必填
  "timestamp":"xx",  // 必填
  "task_id":"xx"     // 必填 消息发送时,从返回消息中获取的task_id
}

调用返回

返回的Json格式信息包括如下内容:

{
  "ret":"SUCCESS/FAIL",
  "data": 
      {
        // 当"ret"为"SUCCESS"时,包含如下参数:
        "task_id":"xx",
        "status": xx, // 消息状态: 0-排队中, 1-发送中,2-发送完成,3-发送失败,4-消息被撤销,
                      // 5-消息过期, 6-筛选结果为空,7-定时任务尚未开始处理
        "total_count":xx, // 消息总数
        "accept_count":xx, // 消息受理数
        "sent_count":xx, // 消息实际发送数
        "open_count":xx,//打开数
        "dismiss_count":xx//忽略数

        // 当"ret"为"FAIL"时,包含参数如下:
        "error_code": "xx" //错误码详见附录I。
      }
}

注意:
Android: sent_count表示消息送达设备的数量。由于设备可能不在线,在消息有效时间内(expire_time),设备上线后还会收到消息。 所以"sent_count"的数字会一直增加,直至到达消息过期时间后,该值不再变化。
iOS: sent_count表示友盟成功推送到APNs平台的数字,不代表送达设备的个数。友盟将消息发送到APNs服务器之后,如果APNs没有返回错误,友盟认为发送成功。因此accept_count会和sent_count两个数字一样。

Web端查看消息状态

除了通过API调用查询接口来查看任务的状态以及报表之外,更直观的方法是在Web后台来查看 所有任务 的报表数据,截图如下:

任务取消

功能说明

当消息发送的type类型任务时,包括broadcast,groupcast,filecast或者customizedcast且file_id不为空时, 可以撤销正在进行中的发送任务。
注意: 撤销仅对排队中(status=0)或者发送中(status=1)的任务有效。
注意: 当次发送任务如果发送总量小于500个的话,后台会按照列播的方式推送,不再按照任务的方式来处理。 该接口会不生效。

调用地址

POST 

http接口:http://msg.umeng.com/api/cancel?sign=mysign

https接口:  https://msgapi.umeng.com/api/cancel?sign=mysign

签名(sign=mysign)的计算方式参见附录K。

调用参数

{
  "appkey":"xx",     // 必填
  "timestamp":"xx",  // 必填
  "task_id":"xx"     // 必填 消息发送时,从返回消息中获取的task_id
}

调用返回

返回的Json格式信息包括如下内容:

{
  "ret":"SUCCESS/FAIL",
  "data": 
      {
        // 当"ret"为"SUCCESS"时
        "task_id":"xx"

        // 当"ret"为"FAIL"时,包含参数如下:
        "error_code": "xx" //错误码详见附录I。
      }
}

文件上传接口

功能说明

文件上传接口支持两种应用场景:

  • a. 发送类型为"filecast"的时候, 开发者批量上传device_token;
  • b. 发送类型为"customizedcast"时, 开发者批量上传alias。

上传文件后获取file_id, 从而可以实现通过文件id来进行消息批量推送的目的。
文件自创建起,服务器会保存两个月。开发者可以在有效期内重复使用该file-id进行消息发送。
注意: 上传的文件不超过10M.

调用地址

POST 

http接口:http://msg.umeng.com/upload?sign=mysign

https接口:  https://msgapi.umeng.com/upload?sign=mysign

签名(sign=mysign)的计算方式参见附录K。

调用参数

{
  "appkey":"xx",     // 必填
  "timestamp":"xx",  // 必填
  "content":"xx"     // 必填 文件内容,多个device_token/alias请用回车符"\n"分隔。
}

注意: content文件内容建议不要超过10M, 文件内容为开发者的device_token/alias,每行一个device_token/alias,由于换行符的特殊性,请将"\n"(或者"\r\n") 显示置于每个device_token/alias之后:

    StringBuffer contentBuffer = new StringBuffer();
    for (String alias: aliasList) {
        contentBuffer.append(alias);
        contentBuffer.append("\n"); // don't forget the return character
    }


调用实例请参照附录E

调用返回

{
  "ret":"SUCCESS/FAIL",
  "data": 
      {
        // 当"ret"为"SUCCESS"时
        "file_id":"xx"

        // 当"ret"为"FAIL"时,包含参数如下:
        "error_code": "xx" //错误码详见附录I。
      }
}

常见问题

1 如何添加IP白名单?
首先查看服务器的外网ip(可通过www.myip.cn查看),然后登录Web后台,在“应用信息”页面进行设置。

网站后台截图如下:

2 为什么调用API返回HTTP 400错误?
我们对于格式错误或其他原因导致发送失败的消息返回400,在返回的内容里面会有error_code表明发送失败的原因(参见附录I)。您需要在代码里面输出返回内容(java,php,python代码中显示返回内容可参考示例代码 ,其他语言的开发者可参考相关手册。)。如果在查看错误码后仍然需要帮助,可联系我们的客服人员。
3 后台显示消息发送成功,设备并没有收到消息?
参见友盟开发者论坛的回答
4 消息推送接口的响应时间?调用推送API时超时应设置多久?
消息推送接口响应时间一般来说都不会超过2s,具体根据推送类型不同有一些差别,例如广播平均响应时间约1102.583ms,单播的响应时间约4.994ms。但是考虑到开发者的网络情况以及一些IO操作偶尔会耗时较长,我们推荐开发者将超时设置为 1分钟
5 友盟消息推送API调用有什么频率或者次数的限制?
发送次数:对于没有上线的App(集成个数小于200),没有限制。 对于已经上线的App,广播每天不超过3次,其他类型则没有限制。如果业务场景确实需要发送超过3次广播,可发送邮件到msg-support@umeng.com申请调大。
发送频率: 每分钟发送次数,对于单播目前没有限制。 对于任务(非单播),每分钟不能超过5次。
6 customized_cast中通过alias发送消息和通过file_id发送消息有什么区别?什么情况下使用file_id方式发送?
通过alias发送的消息使用单播方式发送,通过file_id发送的消息则需要在后台创建任务进行异步处理。通常来说,通过file_id方式发送消息到达设备的延时会比通过alias方式发送消息的延时大。所以我们建议alias个数小于50个时使用alias方式发送,超过50个使用file_id方式发送。
7 已经发送完成的消息是否可以撤销?
iOS无法撤销,Android可以。
对于Android,发送完成意味着消息已经投递给所有当前在线的设备,但是在消息过期之前,系统会尝试将消息发送给离线的设备(待设备上线后投递),此时可以通过撤销操作停止向这些离线设备发送。
8 out_biz_no是什么?什么情况下需要填写?
out_biz_no是开发者的消息标识,和消息一一对应,如果两条消息的out_biz_no相同,推送服务器认为是同一条消息。所以,如果发送多个msg key相同的消息,后发送的消息服务器不会下发。
如果开发者在sdk中调用了mPushAgent.setMergeNotificaiton(false),服务端程序又在网络异常时进行了重试,就有可能造成同一条消息通过友盟服务器在用户手机上显示两次以上的情况。可以通过使用out_biz_no参数避免这种情况的发生。
9 如何添加测试设备? 请参照截图:

10 消息推送的技术支持渠道是什么?
如果阅读我们提供的在线帮助文档无法帮助您解决开发过程中遇到的具体问题,可发送邮件到msg-support@umeng.com,我们会在第一时间给予您回复。也可以在友盟开发者论坛提问,我们有专人负责解答。

更多常见问题请点击访问:友盟消息推送常见问题索引

附录

注意: 附录A-F仅给出了调用发送接口最基本的参数,如需使用更多参数以支持更多的功能,请详细参照2.1.3

附录A unicast消息发送示例

Android

POST 
http接口:http://msg.umeng.com/api/send?sign=计算出来的签名
https接口:https://msgapi.umeng.com/api/send?sign=计算出来的签名
{
    "appkey":"你的appkey",
    "timestamp":"你的timestamp",
    "type":"unicast",
    "device_tokens":"xx(Android为44位)",
    "payload":
    {
        "display_type": "message", // 消息,message
        "body":
        {
           "custom":"自定义custom"/{} //message类型只需填写custom即可,可以是字符串或JSON。
        }    
    },
    "policy":
    {
        "expire_time":"2013-10-30 12:00:00"
    },
    "description":"测试单播消息-Android"
}

iOS

POST 
http接口:http://msg.umeng.com/api/send?sign=计算出来的签名
https接口:https://msgapi.umeng.com/api/send?sign=计算出来的签名
{
   "appkey":"你的appkey",
   "timestamp":"你的timestamp",
   "type":"unicast",
   "device_tokens":"xx(iOS为64位)", 
   "payload":
   {
    "aps":{ "alert":"xxx"} // 苹果必填字段
    "k1":"v1",   // 自定义key-value, key不可以是"d","p"
    "k2":"v2",
    ...
   },
   "policy":
   {
    "expire_time":"2013-10-30 12:00:00"
   }
   "description":"测试单播消息-iOS"      
}

返回结果示例:

返回成功
{
  "ret":"SUCCESS",
  "data":
  {
    "msg_id":"uu07343141897754408310"
  }
}

返回失败
{
  "ret":"FAIL",
  "data":
  {
    "error_code":"xxx" //错误码详见附录I。
  }
}

附录B listcast消息发送示例

Android
POST 
http接口:http://msg.umeng.com/api/send
https接口:https://msgapi.umeng.com/api/send
{
    "appkey":"你的appkey",
    "timestamp":"你的timestamp",
    "type":"listcast", 
    "device_tokens":"device1,device2,…", // 不能超过500个, 
                                            //多个device_token用英文逗号分隔
    "payload":
    {
        "display_type": "notification", // 通知,notification
        "body":
        {
            "ticker":"测试提示文字",
            "title":"测试标题",
            "text":"测试文字描述",
            "after_open":"go_app"
        }
    },
    "policy":
    {
        "expire_time": "2013-10-30 12:00:00"
    },
    "description":"测试列播通知-Android"
}


iOS

POST 
http接口:http://msg.umeng.com/api/send
https接口:https://msgapi.umeng.com/api/send
{
   "appkey":"你的appkey",
   "timestamp":"你的timestamp",
   "type":"listcast",
   "device_tokens":"device_token1,device_token2,...", // 不能超过500个, 
                                                         //多个device_token用英文逗号分隔

   "payload":
   {
    "aps":{ "alert":"xxx"} // 苹果必填字段
    "k1":"v1",   // 自定义key-value, key不可以是"d","p"
    "k2":"v2",
    ...
   },
   "policy":
   {
    "expire_time":"2013-10-30 12:00:00"
   }
   "description":"测试列播消息-iOS"      
}


返回结果示例:

返回成功
{
  "ret":"SUCCESS",
  "data":
  {
    "msg_id":"ul81476141897694936810"
  }
}

返回失败
{
  "ret":"FAIL",
  "data":
  {
    "error_code":"xxx" //错误码详见附录I。
  }
}

附录C broadcast消息发送示例

Android

POST 
http接口:http://msg.umeng.com/api/send?sign=计算出来的签名
https接口:https://msgapi.umeng.com/api/send?sign=计算出来的签名
{
    "appkey":"你的appkey",
    "timestamp":"你的timestamp",
    "type":"broadcast", 
    "payload":
    {
        "display_type": "notification", // 通知,notification
        "body":
        {
            "ticker":"测试提示文字",
            "title":"测试标题",
            "text":"测试文字描述",
            "after_open" : "go_app"
        }
    },
    "policy":
    {
        "start_time": "2013-10-29 12:00:00", //定时发送
        "expire_time": "2013-10-30 12:00:00"
    },
    "description":"测试广播通知-Android"
}

iOS

POST 
http接口:http://msg.umeng.com/api/send?sign=计算出来的签名
https接口:https://msgapi.umeng.com/api/send?sign=计算出来的签名
{
   "appkey":"你的appkey",
   "timestamp":"你的timestamp",
   "type":"broadcast",
   "payload":
   {
    "aps":{ "alert":"xxx"} // 苹果必填字段
    "k1":"v1",   // 自定义key-value
    "k2":"v2",
    ...
   },
   "policy":
   {
       "start_time": "2013-10-29 12:00:00", //定时发送
       "expire_time": "2013-10-30 12:00:00"
   },
   "description":"测试广播通知-iOS"    
}


返回结果示例:

返回成功
{
  "ret":"SUCCESS",
  "data":
  {
    "task_id":"um30683141897698780600"
  }
}

返回失败
{
  "ret":"FAIL",
  "data":
  {
    "error_code":"xxx" //错误码详见附录I。
  }
}

附录D groupcast消息发送示例

Android

POST 
http接口:http://msg.umeng.com/api/send?sign=计算出来的签名
https接口:https://msgapi.umeng.com/api/send?sign=计算出来的签名
{
    "appkey":"你的appkey",
    "timestamp":"你的timestamp",
    "type":"groupcast",
    "filter":
    {
      "where": 
      {
        "and": [{"app_version": "1.0"}] // 发送给app_version为1.0的用户群
      }
    },
    "payload":
    {
        "display_type": "notification", // 通知,notification
        "body":
        {
            "ticker":"测试提示文字",
            "title":"测试标题",
            "text":"测试文字描述",
            "after_open": "go_url",
            "url": "http://message.umeng.com"
        }
    },
    "policy":
    {
        "expire_time": "2013-10-30 12:00:00"
    },
    "description":"测试组播通知-Android"
}

iOS

POST 
http接口:http://msg.umeng.com/api/send?sign=计算出来的签名
https接口:https://msgapi.umeng.com/api/send?sign=计算出来的签名
{
   "appKey":"你的appkey",
   "timestamp":"你的timestamp",
   "type":"groupcast",
   "filter":
    {
      "where": 
      {
        "and": [{"app_version": "1.0"}]
      }
    },
   "payload":
   {
    "aps":{ "alert":"xxx"} // 苹果必填字段
    "k1":"v1",   // 自定义key-value
    "k2":"v2",
    ...
   },
   "policy":
   {
       "expire_time": "2013-10-30 12:00:00"
   },
   "description":"测试组播通知-iOS"   
}


返回结果示例:

返回成功
{
  "ret":"SUCCESS",
  "data":
  {
    "task_id":"us11500141897704915600"
  }
}

返回失败
{
  "ret":"FAIL",
  "data":
  {
    "error_code":"xxx" //错误码详见附录I。
  }
}

说明: 其中的filter条件表示向当前所有app_version是v1.0的应用客户端发送消息,其内容的使用语法示例请参考附录G。

附录E customizedcast消息发送示例

通过alias发送消息示例:

Android

POST 
http接口:http://msg.umeng.com/api/send?sign=计算出来的签名
https接口:https://msgapi.umeng.com/api/send?sign=计算出来的签名
{
    "appkey":"你的appkey",
    "timestamp":"你的timestamp",
    "type":"customizedcast", 
    "alias": "你的alias", //不能超过50个,多个alias以英文逗号风格
    "alias_type":"alias对应的type(SDK调用addAlias(alias,alis_type)接口指定的alias_type)",
    "payload":
    {
        "display_type": "notification", // 通知,notification
        "body":
        {
            "ticker":"测试提示文字",
            "title":"测试标题",
            "text":"测试文字描述",
            "after_open": "go_activity",
            "activity": "xxx"
        }
    },
    "policy":
    {
        "expire_time": "2013-10-30 12:00:00"
    },
    "description":"测试alias通知-Android"
}

iOS

POST 
http接口:http://msg.umeng.com/api/send?sign=计算出来的签名
https接口:https://msgapi.umeng.com/api/send?sign=计算出来的签名
{
   "appKey":"你的appkey",
   "timestamp":"你的timestamp",
   "type":"customizedcast",
   "alias": "你的alias", //不能超过50个,多个alias以英文逗号分隔。
   "alias_type":"alias对应的type",
   "payload":
   {
    "aps":{ "alert":"xxx"} // 苹果必填字段
    "k1":"v1",   // 自定义key-value
    "k2":"v2",
    ...
   },
   "policy":
   {   
       "expire_time": "2013-10-30 12:00:00"
   }
   "description":"测试alias通知-iOS"      
}

返回结果示例:

返回成功
{
  "ret":"SUCCESS",
  "data":
  {
    "msg_id":"ul42611141897709343510"
  }
}

返回失败
{
  "ret":"FAIL",
  "data":
  {
    "error_code":"xxx" //错误码详见附录I。
  }
}

通过file_id方式发送消息示例:

1. 先通过文件上传接口获取文件id: 
POST 
http接口:http://msg.umeng.com/upload?sign=计算出来的签名
https接口:https://msgapi.umeng.com/upload?sign=计算出来的签名
{
    "appkey":"你的appkey",
    "timestamp":"你的timestamp",
    "content":"alias1\nalias2\nalias3\n..." // 多个alias用回车符分隔,回车符需要显示出现。
}

返回结果:

{
  "ret":"SUCCESS",
  "data":
  {
    "file_id":"PF212711418961495056"
  }
}

2. 再通过文件方式发送消息: 

Android

POST 
http接口:http://msg.umeng.com/api/send?sign=计算出来的签名
https接口:https://msgapi.umeng.com/api/send?sign=计算出来的签名
{
    "appkey":"你的appkey",
    "timestamp":"你的timestamp",
    "type":"customizedcast", 
    "alias_type":"alias对应的type",
    "file_id": "PF8961384936199949", // 通过文件上传接口获得的file_id
    "payload":
    {
        "display_type": "notification", // 通知,notification
        "body":
        {
            "ticker":"测试提示文字",
            "title":"测试标题",
            "text":"测试文字描述",
            "after_open":"go_custom",
            "custom": {"key":"value",...}
        }
    },
    "policy":
    {
        "expire_time": "2013-10-30 12:00:00"
    },
    "description":"测试alias文件通知-Android"
}

iOS

POST 
http接口:http://msg.umeng.com/api/send?sign=计算出来的签名
https接口:https://msgapi.umeng.com/api/send?sign=计算出来的签名
{
   "appKey":"你的appkey",
   "timestamp":"你的timestamp",
   "type":"customizedcast",
   "alias_type":"alias对应的type(SDK添加的alias的时候,会带一个type)",
   "file_id": "PF8961384936199949", 
   "payload":
   {
    "aps":{ "alert":"xxx"} // 苹果必填字段
    "k1":"v1",   // 自定义key-value
    "k2":"v2",
    ...
   },
   "policy":
   { 
    "expire_time": "2013-10-30 12:00:00"
   }
   "description":"测试alias文件通知-iOS"      
}

返回结果示例:

返回成功
{
  "ret":"SUCCESS",
  "data":
  {
    "task_id":"uc92494141897770617701"
  }
}

返回失败
{
  "ret":"FAIL",
  "data":
  {
    "error_code":"xxx" //错误码详见附录I。
  }
}

附录F filecast消息发送示例

通过file_id方式发送消息示例:

1. 先通过文件上传接口获取文件id: 

POST 
http接口:http://msg.umeng.com/upload?sign=计算出来的签名
https接口:https://msgapi.umeng.com/upload?sign=计算出来的签名 
{
    "appkey":"你的appkey",
    "timestamp":"你的timestamp",
    "content":"device_token_1\ndevice_token_2\ndevice_token_3\n..." 
                            // 多个device_token用回车符分隔,回车符需要显示出现。
}

返回结果:

{
  "ret":"SUCCESS",
  "data":
  {
    "file_id":"PF8961384936199949"
  }
}

2. 再通过文件方式发送消息: 

Android

POST
 http接口: http://msg.umeng.com/api/send?sign=计算出来的签名
 https接口: https://msgapi.umeng.com/api/send?sign=计算出来的签名
{
    "appkey":"你的appkey",
    "timestamp":"你的timestamp",
    "type":"filecast", 
    "file_id": "PF8961384936199949", // 通过文件上传接口获得的file_id
    "payload":
    {
        "display_type": "notification", // 通知,notification
        "body":
        {
            "ticker":"测试提示文字",
            "title":"测试标题",
            "text":"测试文字描述",
            "after_open": "go_app"
        }
    },
    "policy":
    {
        "expire_time": "2013-10-30 12:00:00"
    },
    "description":"测试filecast文件通知-Android"
}

iOS

POST 
http接口:http://msg.umeng.com/api/send?sign=计算出来的签名
https接口:https://msgapi.umeng.com/api/send?sign=计算出来的签名
{
   "appKey":"你的appkey",
   "timestamp":"你的timestamp",
   "type":"filecast",
   "file_id": "PF8961384936199949", 
   "payload":
   {
    "aps":{ "alert":"xxx"} // 苹果必填字段
    "k1":"v1",   // 自定义key-value
    "k2":"v2",
    ...
   },
   "policy":
   {   
      "expire_time": "2013-10-30 12:00:00"
   }
   "description":"测试filecast文件通知-iOS"      
}

返回结果示例:

返回成功
{
  "ret":"SUCCESS",
  "data":
  {
    "task_id":"uf01418141897692987100"
  }
}

返回失败
{
  "ret":"FAIL",
  "data":
  {
    "error_code":"xxx" //错误码详见附录I。
  }
}

附录G 过滤条件示例

目前开放的筛选字段有:

  • "app_version"(应用版本)
  • "channel"(渠道)
  • "device_model"(设备型号)
  • "province"(省)
  • "tag"(用户标签)
  • "country"(国家) //"country"和"province"的类型定义请参照 附录J
  • "language"(语言)
  • "launch_from"(一段时间内活跃)
  • "not_launch_from"(一段时间内不活跃)

我们的筛选条件非常灵活,支持逻辑上的and(与), or(或), not(非)操作, 以及这些操作的组合。具体请参照下面的示例。
注意: 筛选条件的最顶层必须是and。
由于筛选条件使用起来比较复杂,我们在网站的消息发送页面下也添加了对应的在线生成工具,供开发者在网站上筛选好条件之后直接生成对应的filter条件,如下图:

点击"生成Json串"之后,结果如下图("+"号部分没有显示,展开之后是对应Json串的格式化打印)

and条件示例

已注册的(registered_user) 并且 版本(app_version)是1.0的用户群,且这些用户在2014-11-15之后活跃过。

"where": 
{
    "and": 
    [
      {"tag":"registered_user"}, // 开发者自定义tag
      {"app_version":"1.0"}, // app-version
      {"launch_from":"2014-11-15"} // X天活跃/不活跃
    ]
}

or条件示例

自定义标签为“美剧”的用户 或者 自定义标签为“文艺”的用户

"where":{
    "and":[
        {
        "or":[
            {"tag":"美剧"},
            {"tag":"文艺"}            ]
        }
    ]
}

not条件示例

注册的(registered_user)的用户群

"where": 
{
  "and": 
  [
    {
      "not": 
      {
        "tag": "registered_user"
      }
    }
  ]
}

and, or, not组合条件示例

发送给分渠道 360 或者 "版本号为1.2" 并且 "2014-11-15之后不活跃"的用户

"where": 
{
  "and": 
  [
    {
      "or": 
      [
        {
          "not": 
          {
            "channel": "360"
          }
        },
        {
          "app_version": "1.2"
        }
      ]
    },
    {
      "not_launch_from": "2014-11-15"
    }
  ]
}

注意: Query expression的最顶层只能是 and 或者 or

大于等于(>=)及小于等于(<=)组合条件示例

如果要选择推送给版本>=某版本或者<=某版本的设备,以筛选>=1.0的设备为例,可采用以下两种方法实现:

方法一:自己筛选出符合要求的各个版本。(官方建议方案)格式为:

{"and":[{"or":[{"app_version":">1.0"}]}]}

具体格式规范可以参考生成JSON串部分进行实现。

方法二:自己筛选出符合要求的各个版本。格式为:

{"and":[{"or":[{"app_version":"1.0"},{"app_version":"2.0"},{"app_version":"3.0"},{"app_version":"4.0"}]}]}

附录I 接口调用错误码

API通过HTTP Status Code来说明请求是否成功, 200表示成功, 400表示失败。

HTTP常见Status Code及其含义

200 OK 请求成功
201 CREATED 创建成功
202 ACCEPTED 更新成功
400 BAD REQUEST 请求的地址不存在或者包含不支持的参数
401 UNAUTHORIZED 未授权
403 FORBIDDEN 被禁止访问
404 NOT FOUND 请求的资源不存在
500 INTERNAL SERVER ERROR 内部错误

API服务错误码

1000 请求参数没有appkey 400
1001 请求参数没有payload 400
1002 请求参数payload中没有body 400
1003 display_type为message时,请求参数没有custom 400
1004 请求参数没有display_type 400
1005 img url格式不对,请以https或者http开始 400
1006 sound url格式不对,请以https或者http开始 400
1007 url格式不对,请以https或者http开始 400
1008 display_type为notification时,body中ticker不能为空 400
1009 display_type为notification时,body中title不能为空 400
1010 display_type为notification时,body中text不能为空 400
1011 play_vibrate的值只能为true或者false 400
1012 play_lights的值只能为true或者false 400
1013 play_sound的值只能为true或者false 400
1014 task-id没有找到 400
1015 请求参数中没有device_tokens 400
1016 请求参数没有type 400
1017 production_mode只能为true或者false 400
1018 appkey错误:指定的appkey尚未开通推送服务 400
1019 display_type填写错误 400
1020 应用组中尚未添加应用 400
2000 该应用已被禁用 400
2001 过期时间必须大于当前时间 400
2002 定时发送时间必须大于当前时间 400
2003 过期时间必须大于定时发送时间 400
2004 IP白名单尚未添加, 请到网站后台添加您的服务器IP白名单。 400
2005 该消息不存在 400
2006 validation token错误 400
2007 未对请求进行签名 400
2008 json解析错误 400
2009 请填写alias或者file_id 400
2010 与alias对应的device_tokens为空 400
2011 alias个数已超过50 400
2012 此appkey今天的广播数已超过3次 400
2013 消息还在排队,请稍候再查询 400
2014 消息取消失败,请稍候再试 400
2015 device_tokens个数已超过50 400
2016 请填写filter 400
2017 添加tag失败 400
2018 请填写file_id 400
2019 与此file_id对应的文件不存在 400
2020 服务正在升级中,请稍候再试 400
2021 appkey不存在 400
2022 payload长度过长 400
2023 文件上传失败,请重试 400
2024 限速值必须为正整数 400
2025 aps字段不能为空 400
2026 1分钟内发送任务次数超出3次 400
2027 签名不正确 400
2028 时间戳已过期 400
2029 content内容不能为空 400
2030 launch_from/not_launch_from条件中的日期须小于发送日期 400
2031 filter格式不正确 400
2032 未上传生产证书,请到Web后台上传 400
2033 未上传开发证书,请到Web后台上传 400
2034 证书已过期 400
2035 定时任务证书过期 400
2036 时间戳格式错误 400
2038 文件上传失败 400
2039 时间格式必须是yyyy-MM-dd HH:mm:ss 400
2040 过期时间不能超过7天 400
2046 定时推送时间不能超过创建推送时间+7天 500
3000 数据库错误 400
3001 数据库错误 400
3002 数据库错误 400
3003 数据库错误 400
3004 数据库错误 400
4000 系统错误 400
4001 系统忙 400
4002 操作失败 400
4003 appkey格式错误 400
4004 消息类型格式错误 400
4005 msg格式错误 400
4006 body格式错误 400
4007 deliverPolicy格式错误 400
4008 失效时间格式错误 400
4009 单个服务器队列已满 400
4010 设备号格式错误 400
4011 消息扩展字段无效 400
4012 没有权限访问 400
4013 异步发送消息失败 400
4014 appkey和device_tokens不对应 400
4015 没有找到应用信息 400
4016 文件编码有误 400
4017 文件类型有误 400
4018 文件远程地址有误 400
4019 文件描述信息有误 400
4020 device_token有误(注意,友盟的device_token是严格的44位字符串) 400
4021 HSF异步服务超时 400
4022 appkey已经注册 400
4023 服务器网络异常 400
4024 非法访问 400
4025 device-token全部失败 400
4026 device-token部分失败 400
4027 拉取文件失败 400
5000 device_token错误 400
5001 证书不存在 400
5002 p,d是umeng保留字段 400
5003 alert字段不能为空 400
5004 alert只能是String类型 400
5005 device_token格式错误 400
5006 创建socket错误 400
5007 certificate_revoked错误 400
5008 certificate_unkown错误 400
5009 handshake_failure错误 400

附录J 国家 & 省市 定义表

用于组播(groupcast)的时候,"国家地区(country)"或者"省级(province)"的筛选维度:

国家

美国
日本
英国
澳大利亚
德国
加拿大
法国
意大利
中国
瑞士
俄罗斯
韩国
荷兰
阿根廷
奥地利
比利时
巴西
保加利亚
智利
捷克
丹麦
埃及
芬兰
希腊
香港
匈牙利
印度
印度尼西亚
爱尔兰
以色列

更多国家和地区列表参见友盟开发者论坛

北京
上海
广东
安徽
澳门
重庆
福建
甘肃
广西
贵州
海南
河北
河南
黑龙江
湖北
湖南
吉林
江苏
江西
辽宁
内蒙古
宁夏
青海
山东
山西
陕西
四川
台湾
天津
西藏
香港
新疆
云南
浙江

附录K 关于签名

为了确保用户发送的请求不被更改,我们设计了签名算法。该算法基本可以保证请求是合法者发送且参数没有被修改,但无法保证不被偷窥。 签名生成规则:
A)提取请求方法method(POST,全大写);
B)提取请求url信息,包括Host字段的域名(或ip:端口)和URI的path部分。注意不包括path的querystring。
比如http://msg.umeng.com/api/send 或者 http://msg.umeng.com/api/status;
C)提取请求的post-body;
D)拼接请求方法、url、post-body及应用的app_master_secret;
E)将D形成字符串计算MD5值,形成一个32位的十六进制(字母小写)字符串,即为本次请求sign(签名)的值;
Sign=MD5($http_method$url$post-body$app_master_secret);

python生成签名示例

import hashlib
def md5(s):
    m = hashlib.md5(s)
    return m.hexdigest()

appkey = '你的appkey'
app_master_secret = '你的app_master_secret'
timestamp = '你的timestamp'
method = 'POST'
url = 'http://msg.umeng.com/api/send'
params = {'appkey': appkey,
          'timestamp': timestamp,
          'device_tokens': device_token,
          'type': 'unicast',
          'payload': {'body': {'ticker': 'Hello World',
                               'title':'你好',
                               'text':'来自友盟推送',
                               'after_open': 'go_app'},
                      'display_type': 'notification'
          }
}
post_body = json.dumps(params)
print post_body
sign = md5('%s%s%s%s' % (method,url,post_body,app_master_secret))

 温馨提示

为了保证使用友盟推送的开发者都能获得良好的用户体验,我们坚决杜绝滥用推送服务的事件发生。一经发现,友盟推送将有权对滥用服务的appkey实施封禁发送权限的处理

 技术支持

如果还有问题,请把您的问题发邮件至msg-support@umeng.com或者联系客服:联系客服 (在线时间:工作日10:00~18:00),我们会尽快回复您。