iOS实战（34）
& & & & 前段时间提了一个推送的需求，经过调研，选择了激光推送JPush。
JPush有什么优势？
& & & & 在集成后发现了一个问题，后台出现一大堆错误提醒，基本上都是“别名未注册“，这问题对于初级用户来说可能会经常遇到，也跟技服交流了很长时间。公司近百台调试设备，只有一台出现别名不能成功注册的情况。虽然说这个问题没有完全解决，但是总算找了一个合理的解决方案。
& & & & 如果JPush集成成功，在第一次运行的时候会弹出提醒框让用户选择是否允许推送。如果选择了否，则在用户通过通知中心重新打开推送的时候，会在24小时之后生效，也就是说在24小时之内依然无法收到推送，这一点确实有点烦人，所以在调试的过程中，只能往后更改一下手机的日期。苹果就是霸道，它就这样规定你有啥办法！
& & & & 如果集成方面没问题，使用添加了推送功能的证书，则在程序启动的时候会调用- (void)application:(UIApplication
*)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken或者- (void)application:(UIApplication
*)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error，如果两个方法都没调用，应该是集成有问题，可以参考集成步骤，还有注意证书以及生产/开发环境的对应设置
& & & & 对于别名未注册的情况，可以在设置别名的时候添加一个标志位，并将其上行到服务器，服务器根据这个值判断别名是否有效，从而不给别名设置失败的设备或用户发通知，这样就避免了资源浪费。按照这个方法，可以在别名设置失败的时候多设置几次，但是一定要控制设置次数，否则极光服务器就哭了。
& & & & 在设置别名的时候有一个返回值- (void)tagsAliasCallback:(int)iResCode
tags:(NSSet*)tags alias:(NSString*)alias方法中的iResCode，iResCode==0表示设置成功。
参考知识库
* 以上用户言论只代表其个人观点，不代表CSDN网站的观点或立场
访问：16566次
排名：千里之外
原创：68篇
转载：95篇
(44)(12)(107)资源索引 W_最新更新_ 资源索引 W软件列表_东坡下载
>> 软件字母导航 >>
资源索引 W
字母导航 资源索引 W最新更新
本站推荐下载
软件按字母排列:
东坡下载 & 分享互联网
Copyright(C)
All Rights Reserved! 网站备案/许可证号:鄂ICP备号-1> 消息推送 > 消息推送IOS文档 > API Doc
本文所描述的API接口均基于HTTP Rest协议, 若无特殊说明接口均使用UTF-8编码, 消息体参数以及返回结果均采用Json格式。
注意: 使用API前需要在的App应用信息页面获取 appkey 和 app_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的协议。
签名（sign=mysign)的计算方式参见附录K。
"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-消息
// 必填 消息体。
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格式。
// 可选 用户自定义key-value。只对"通知"
(display_type=notification)生效。
可以配合通知到达后,打开App,打开URL,打开Activity使用。
"key1": "value1",
"key2": "value2",
// 可选 发送策略
"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, 便于友盟后台后期合并统计数据。
"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格式):
// 必填 严格按照APNs定义来填写
"alert": "xx"
"badge": xx,
"sound": "xx",
"content-available":xx // 可选
"category": "xx",
// 可选, 注意: ios8才支持该字段。
"key1":"value1",
// 可选 用户自定义内容, "d","p"为友盟保留字段，
key不可以是"d","p"
"key2":"value2",
// 可选 发送策略
"start_time":"xx",
// 可选 定时发送时间，默认为立即发送。发送时间不能小于当前时间。
格式: "YYYY-MM-DD HH:mm:ss"。
注意, start_time只对任务生效。
"expire_time":"xx",
// 可选 消息过期时间,其值不可小于发送时间,
默认为3天后过期。格式同start_time
"max_send_num": xx
// 可选 发送限速，每秒发送的最大条数。
开发者发送的消息如果有请求自己服务器的资源，可以考虑此参数。
"production_mode":"true/false" // 可选 正式/测试模式。测试模式下，广播/组播只会将消息发给测试设备。
测试设备需要到web上添加。
iOS: 测试模式对应APNs的开发环境(sandbox),
正式模式对应APNs的正式环境(prod),
正式、测试设备完全隔离。
"description": "xx"
// 可选 发送消息描述，建议填写。
"thirdparty_id": "xx"
// 可选 开发者自定义消息标识ID, 开发者可以为同一批发送的消息提供
同一个thirdparty_id, 便于后期合并统计数据。
在正常情况下，返回结果的HTTP状态码为200，错误情况下返回的HTTP状态码为500。 返回结果采用Json格式，包含的参数有:
"ret":"SUCCESS/FAIL", // 返回结果，"SUCCESS"或者"FAIL"
// 当"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个的话，后台会按照列播的方式推送，不再按照任务的方式来处理。 该接口会不生效。
签名（sign=mysign)的计算方式参见附录K。
"appkey":"xx",
"timestamp":"xx",
"task_id":"xx"
// 必填 消息发送时，从返回消息中获取的task_id
返回的Json格式信息包括如下内容:
"ret":"SUCCESS/FAIL",
// 当"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个的话，后台会按照列播的方式推送，不再按照任务的方式来处理。 该接口会不生效。
签名（sign=mysign)的计算方式参见附录K。
"appkey":"xx",
"timestamp":"xx",
"task_id":"xx"
// 必填 消息发送时，从返回消息中获取的task_id
返回的Json格式信息包括如下内容:
"ret":"SUCCESS/FAIL",
// 当"ret"为"SUCCESS"时
"task_id":"xx"
// 当"ret"为"FAIL"时，包含参数如下:
"error_code": "xx" //错误码详见附录I。
文件上传接口
文件上传接口支持两种应用场景:
a. 发送类型为"filecast"的时候, 开发者批量上传device_
b. 发送类型为"customizedcast"时, 开发者批量上传alias。
上传文件后获取file_id, 从而可以实现通过文件id来进行消息批量推送的目的。
文件自创建起，服务器会保存两个月。开发者可以在有效期内重复使用该file-id进行消息发送。
注意: 上传的文件不超过10M.
签名（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",
// 当"ret"为"SUCCESS"时
"file_id":"xx"
// 当"ret"为"FAIL"时，包含参数如下:
"error_code": "xx" //错误码详见附录I。
1 如何添加IP白名单？
首先查看服务器的外网ip（可通过查看），然后登录，在“应用信息”页面进行设置。
网站后台截图如下:
2 为什么调用API返回HTTP 500错误？
我们对于格式错误或其他原因导致发送失败的消息返回500，在返回的内容里面会有error_code表明发送失败的原因（参见附录I）。您需要在代码里面输出返回内容（java,php,python代码中显示返回内容可参考 ,其他语言的开发者可参考相关手册。）。如果在查看错误码后仍然需要帮助，可联系我们的客服人员。
3 后台显示消息发送成功，设备并没有收到消息?
4 消息推送接口的响应时间?调用推送API时超时应设置多久?
消息推送接口响应时间一般来说都不会超过2s，具体根据推送类型不同有一些差别，例如广播平均响应时间约ms，单播的响应时间约4.994ms。但是考虑到开发者的网络情况以及一些IO操作偶尔会耗时较长，我们推荐开发者将超时设置为 1分钟。
5 友盟消息推送API调用有什么频率或者次数的限制？
发送次数：对于没有上线的App(集成个数小于200)，没有限制。 对于已经上线的App，广播每天不超过3次，其他类型则没有限制。如果业务场景确实需要发送超过3次广播，可发送邮件到申请调大。
发送频率: 每分钟发送次数，对于单播目前没有限制。 对于任务(非单播)，每分钟不能超过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 消息推送的技术支持渠道是什么？
如果阅读我们提供的在线帮助文档无法帮助您解决开发过程中遇到的具体问题，可发送邮件到，我们会在第一时间给予您回复。也可以在提问，我们有专人负责解答。
更多常见问题请点击访问：
注意: 附录A-F仅给出了调用发送接口最基本的参数，如需使用更多参数以支持更多的功能，请详细参照2.1.3
附录A unicast消息发送示例
POST /api/send?sign=计算出来的签名
"appkey":"你的appkey",
"timestamp":"你的timestamp",
"type":"unicast",
"device_tokens":"xx(Android为44位)",
"payload":
"display_type": "message", // 消息，message
"custom":"自定义custom"/{} //message类型只需填写custom即可，可以是字符串或JSON。
"expire_time":" 12:00:00"
"description":"测试单播消息-Android"
POST /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",
"expire_time":" 12:00:00"
"description":"测试单播消息-iOS"
返回结果示例:
"ret":"SUCCESS",
"msg_id":"uu"
"ret":"FAIL",
"error_code":"xxx" //错误码详见附录I。
附录B listcast消息发送示例
POST /api/send
"appkey":"你的appkey",
"timestamp":"你的timestamp",
"type":"listcast",
"device_tokens":"device1,device2,…", // 不能超过500个,
//多个device_token用英文逗号分隔
"payload":
"display_type": "notification", // 通知，notification
"ticker":"测试提示文字",
"title":"测试标题",
"text":"测试文字描述",
"after_open":"go_app"
"expire_time": " 12:00:00"
"description":"测试列播通知-Android"
POST /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",
"expire_time":" 12:00:00"
"description":"测试列播消息-iOS"
返回结果示例:
"ret":"SUCCESS",
"msg_id":"ul"
"ret":"FAIL",
"error_code":"xxx" //错误码详见附录I。
附录C broadcast消息发送示例
POST /api/send?sign=计算出来的签名
"appkey":"你的appkey",
"timestamp":"你的timestamp",
"type":"broadcast",
"payload":
"display_type": "notification", // 通知，notification
"ticker":"测试提示文字",
"title":"测试标题",
"text":"测试文字描述",
"after_open" : "go_app"
"start_time": " 12:00:00", //定时发送
"expire_time": " 12:00:00"
"description":"测试广播通知-Android"
POST /api/send?sign=计算出来的签名
"appkey":"你的appkey",
"timestamp":"你的timestamp",
"type":"broadcast",
"payload":
"aps":{ "alert":"xxx"} // 苹果必填字段
"k1":"v1",
// 自定义key-value
"k2":"v2",
"start_time": " 12:00:00", //定时发送
"expire_time": " 12:00:00"
"description":"测试广播通知-iOS"
返回结果示例:
"ret":"SUCCESS",
"task_id":"um"
"ret":"FAIL",
"error_code":"xxx" //错误码详见附录I。
附录D groupcast消息发送示例
POST /api/send?sign=计算出来的签名
"appkey":"你的appkey",
"timestamp":"你的timestamp",
"type":"groupcast",
"and": [{"app_version": "1.0"}] // 发送给app_version为1.0的用户群
"payload":
"display_type": "notification", // 通知，notification
"ticker":"测试提示文字",
"title":"测试标题",
"text":"测试文字描述",
"after_open": "go_url",
"expire_time": " 12:00:00"
"description":"测试组播通知-Android"
POST /api/send?sign=计算出来的签名
"appKey":"你的appkey",
"timestamp":"你的timestamp",
"type":"groupcast",
"and": [{"app_version": "1.0"}]
"payload":
"aps":{ "alert":"xxx"} // 苹果必填字段
"k1":"v1",
// 自定义key-value
"k2":"v2",
"expire_time": " 12:00:00"
"description":"测试组播通知-iOS"
返回结果示例:
"ret":"SUCCESS",
"task_id":"us"
"ret":"FAIL",
"error_code":"xxx" //错误码详见附录I。
说明: 其中的filter条件表示向当前所有app_version是v1.0的应用客户端发送消息，其内容的使用语法示例请参考附录G。
附录E customizedcast消息发送示例
通过alias发送消息示例:
POST /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
"ticker":"测试提示文字",
"title":"测试标题",
"text":"测试文字描述",
"after_open": "go_activity",
"activity": "xxx"
"expire_time": " 12:00:00"
"description":"测试alias通知-Android"
POST /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",
"expire_time": " 12:00:00"
"description":"测试alias通知-iOS"
返回结果示例:
"ret":"SUCCESS",
"msg_id":"ul"
"ret":"FAIL",
"error_code":"xxx" //错误码详见附录I。
通过file_id方式发送消息示例:
1. 先通过文件上传接口获取文件id:
POST /upload?sign=计算出来的签名
"appkey":"你的appkey",
"timestamp":"你的timestamp",
"content":"alias1\nalias2\nalias3\n..." // 多个alias用回车符分隔，回车符需要显示出现。
"ret":"SUCCESS",
"file_id":"PF495056"
2. 再通过文件方式发送消息:
POST /api/send?sign=计算出来的签名
"appkey":"你的appkey",
"timestamp":"你的timestamp",
"type":"customizedcast",
"alias_type":"alias对应的type",
"file_id": "PF9949", // 通过文件上传接口获得的file_id
"payload":
"display_type": "notification", // 通知，notification
"ticker":"测试提示文字",
"title":"测试标题",
"text":"测试文字描述",
"after_open":"go_custom",
"custom": {"key":"value",...}
"expire_time": " 12:00:00"
"description":"测试alias文件通知-Android"
POST /api/send?sign=计算出来的签名
"appKey":"你的appkey",
"timestamp":"你的timestamp",
"type":"customizedcast",
"alias_type":"alias对应的type(SDK添加的alias的时候，会带一个type)",
"file_id": "PF9949",
"payload":
"aps":{ "alert":"xxx"} // 苹果必填字段
"k1":"v1",
// 自定义key-value
"k2":"v2",
"expire_time": " 12:00:00"
"description":"测试alias文件通知-iOS"
返回结果示例:
"ret":"SUCCESS",
"task_id":"uc"
"ret":"FAIL",
"error_code":"xxx" //错误码详见附录I。
附录F filecast消息发送示例
通过file_id方式发送消息示例:
1. 先通过文件上传接口获取文件id:
POST /upload?sign=计算出来的签名
"appkey":"你的appkey",
"timestamp":"你的timestamp",
"content":"device_token_1\ndevice_token_2\ndevice_token_3\n..."
// 多个device_token用回车符分隔，回车符需要显示出现。
"ret":"SUCCESS",
"file_id":"PF9949"
2. 再通过文件方式发送消息:
POST /api/send?sign=计算出来的签名
"appkey":"你的appkey",
"timestamp":"你的timestamp",
"type":"filecast",
"file_id": "PF9949", // 通过文件上传接口获得的file_id
"payload":
"display_type": "notification", // 通知，notification
"ticker":"测试提示文字",
"title":"测试标题",
"text":"测试文字描述",
"after_open": "go_app"
"expire_time": " 12:00:00"
"description":"测试filecast文件通知-Android"
POST /api/send?sign=计算出来的签名
"appKey":"你的appkey",
"timestamp":"你的timestamp",
"type":"filecast",
"file_id": "PF9949",
"payload":
"aps":{ "alert":"xxx"} // 苹果必填字段
"k1":"v1",
// 自定义key-value
"k2":"v2",
"expire_time": " 12:00:00"
"description":"测试filecast文件通知-iOS"
返回结果示例:
"ret":"SUCCESS",
"task_id":"uf"
"ret":"FAIL",
"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的用户群，且这些用户在之后活跃过。
{"tag":"registered_user"}, // 开发者自定义tag
{"app_version":"1.0"}, // app-version
{"launch_from":""} // X天活跃/不活跃
or条件示例
自定义标签为“美剧”的用户 或者 自定义标签为“文艺”的用户
{"tag":"美剧"},
{"tag":"文艺"}
not条件示例
未注册的(registered_user)的用户群
"tag": "registered_user"
and, or, not组合条件示例
发送给分渠道 非 360 或者 "版本号为1.2" 并且 "之后不活跃"的用户
"channel": "360"
"app_version": "1.2"
"not_launch_from": ""
注意: Query expression的最顶层只能是 and 或者 or
附录I 接口调用错误码
API通过HTTP Status Code来说明请求是否成功, 200表示成功, 500表示失败。
HTTP常见Status Code及其含义
BAD REQUEST
请求的地址不存在或者包含不支持的参数
UNAUTHORIZED
被禁止访问
请求的资源不存在
INTERNAL SERVER ERROR
API服务错误码
请求参数没有appkey
请求参数没有payload
请求参数payload中没有body
display_type为message时，请求参数没有custom
请求参数没有display_type
img url格式不对，请以https或者http开始
sound url格式不对，请以https或者http开始
url格式不对，请以https或者http开始
display_type为notification时，body中ticker不能为空
display_type为notification时，body中title不能为空
display_type为notification时，body中text不能为空
play_vibrate的值只能为true或者false
play_lights的值只能为true或者false
play_sound的值只能为true或者false
task-id没有找到
请求参数中没有device_tokens
请求参数没有type
production_mode只能为true或者false
appkey错误：指定的appkey尚未开通推送服务
display_type填写错误
应用组中尚未添加应用
该应用已被禁用
过期时间必须大于当前时间
定时发送时间必须大于当前时间
过期时间必须大于定时发送时间
IP白名单尚未添加, 请到网站后台添加您的服务器IP白名单。
该消息不存在
validation token错误
未对请求进行签名
json解析错误
请填写alias或者file_id
与alias对应的device_tokens为空
alias个数已超过50
此appkey今天的广播数已超过3次
消息还在排队，请稍候再查询
消息取消失败，请稍候再试
device_tokens个数已超过50
请填写filter
添加tag失败
请填写file_id
与此file_id对应的文件不存在
服务正在升级中，请稍候再试
appkey不存在
payload长度过长
文件上传失败，请重试
限速值必须为正整数
aps字段不能为空
1分钟内发送任务次数超出3次
签名不正确
时间戳已过期
content内容不能为空
launch_from/not_launch_from条件中的日期须小于发送日期
filter格式不正确
未上传生产证书，请到Web后台上传
未上传开发证书，请到Web后台上传
证书已过期
定时任务证书过期
时间戳格式错误
文件上传失败
时间格式必须是yyyy-MM-dd HH:mm:ss
过期时间不能超过7天
数据库错误
数据库错误
数据库错误
数据库错误
数据库错误
appkey格式错误
消息类型格式错误
msg格式错误
body格式错误
deliverPolicy格式错误
失效时间格式错误
单个服务器队列已满
设备号格式错误
消息扩展字段无效
没有权限访问
异步发送消息失败
appkey和device_tokens不对应
没有找到应用信息
文件编码有误
文件类型有误
文件远程地址有误
文件描述信息有误
device_token有误(注意，友盟的device_token是严格的44位字符串)
HSF异步服务超时
appkey已经注册
服务器网络异常
device-token全部失败
device-token部分失败
拉取文件失败
device_token错误
证书不存在
p,d是umeng保留字段
alert字段不能为空
alert只能是String类型
device_token格式错误
创建socket错误
certificate_revoked错误
certificate_unkown错误
handshake_failure错误
附录J 国家 & 省市 定义表
用于组播(groupcast)的时候，"国家地区(country)"或者"省级(province)"的筛选维度:
印度尼西亚
更多国家和地区列表参见
附录K 关于签名
为了确保用户发送的请求不被更改，我们设计了签名算法。该算法基本可以保证请求是合法者发送且参数没有被修改，但无法保证不被偷窥。
签名生成规则：
A）提取请求方法method（POST，全大写）；
B）提取请求url信息，包括Host字段的域名(或ip:端口)和URI的path部分。注意不包括path的querystring。
比如 或者 ;
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 = '/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实施封禁发送权限的处理
 技术支持
如果还有问题，请把您的问题发邮件至或者联系企业QQ:(在线时间：工作日10:00~18:00)，我们会尽快回复您。}