创建推送 API
向某单个设备或者某设备列表推送一条通知、或者消息。
推送的内容只能是 JSON 表示的一个推送对象。
这是 Push API 最近的版本。v4 版本的改进为:
- 使用 HTTP Basic Authentication 的方式做访问授权。这样整个 API 请求可以使用常见的 HTTP 工具来完成,比如:curl,浏览器插件等。
- 推送内容完全使用 JSON 的格式。
请求方式
POST
调用地址
接口服务地址与数据中心选择接入点一一对应,请选择与您的应用服务接入点对应的 调用地址。
目EngageLab已部署支持了两个数据中心接入点,不同服务接入点之间数据完全隔离,您可根据创建产品时选择的数据中心接入点选择调用地址。
- 新加坡数据中心调用地址:
POST https://push.api.engagelab.cc/v4/push
- 美国弗吉尼亚数据中心调用地址
POST https://push-usva.api.engagelab.cc/v4/push
调用验证
详情参见 REST API 概述的 鉴权方式 说明。
请求示例
请求头
> POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==
请求体
{
"from": "push",
"to": "all",
"body": {
"platform": "all",
"notification": {
"android": {
"alert": "Hi, Push!",
"title": "Send to Android",
"builder_id": 1,
"extras": {
"newsid": 321
}
},
"ios": {
"alert": "Hi, MTPush!",
"sound": "default",
"badge": "+1",
"extras": {
"newsid": 321
}
}
},
"message": {
"msg_content": "Hi,MTPush",
"content_type": "text",
"title": "msg",
"extras": {
"key": "value"
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
},
"request_id": "12345678",
"custom_args": "business info"
}'
> POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==
请求参数
推送的参数结构体,详见下表:
关键字 | 类型 | 选项 | 含义 |
---|---|---|---|
from | String | 可选 | 当前业务发送方 |
to | String 或 JSON Object | 必填 | 发送目标 |
body | JSON Object | 必填 | 发送请求体 |
platform | String 或 JSON Array | 必填 | 推送平台 |
notification | JSON Object | 可选 | |
message | JSON Object | 可选 | |
options | JSON Object | 可选 | 推送参数 |
request_id | String | 可选 | 客户自定义的可选字段,客户用来标识是哪条请求,响应时返回。 |
custom_args | JSON Object | 可选 | 客户自定义的可选字段,回调时返回给客户。 |
from
当前业务发送方,String 类型,可选字段。
请求示例
{
"from":"push"
}
to
推送设备对象,表示一条推送可以被推送到哪些设备列表。确认推送设备对象,App Push 提供了多种方式,比如:别名、标签、注册ID、分群、广播等。
推送目标
广播外的设备选择方式,有如下几种:
关键字 | 类型 | 含义 | 说明 | 备注 |
---|---|---|---|---|
all | String | 发广播 | 给全部设备进行推送 | 推送目标为30天内活跃过的设备。 |
tag | JSON Array | 标签 | 数组。多个标签之间是 OR 的关系,即取并集。 | 用标签来进行大规模的设备属性、用户属性分群。 |
tag_and | JSON Array | 标签AND | 数组。多个标签之间是 AND 关系,即取交集。 | 注意与 tag 区分,一次推送最多 20 个。 |
tag_not | JSON Array | 标签NOT | 数组。多个标签之间,先取多标签的并集,再对该结果取补集。 | 一次推送最多 20 个。 |
alias | JSON Array | 别名 | 数组。多个别名之间是 OR 关系,即取并集。 | 用别名来标识一个用户。 |
registration_id | JSON Array | 注册ID | 数组。多个注册ID之间是 OR 关系,即取并集。 | 设备标识。一次推送最多 1000 个。 |
数组里多个值之间隐含的关系是是 OR,即取并集;但 tag_and 不同,其数组里多个值之间是 AND 关系,即取交集。
tag_not 不能单独使用,其他 5 种类型至少需要有其一。如果值数组长度为 0,表示该类型不存在。
这几种类型可以并存。并存时多项的隐含关系是 AND,即取交集。例如:
"audience" : {"tag" : [ "tag1", "tag2"], "tag_and" : ["tag3", "tag4"], "tag_not" : ["tag5", "tag6"] }
先计算 "tag" 字段的结果 tag1 或 tag2 = A
;
再计算 "tag_and" 字段的结果 tag3 且 tag4 = B
;
再计算 "tag_not" 字段的结果 非 (tag5 或 tag6) = C
;
"audience" 的最终结果为 A 且 B 且 C
。
示例
- 推送给全部(广播):
{
"to": "all",
}
- 推送给多个标签(只要在任何一个标签范围内都满足):在深圳、广州、或者北京
{
"to":{
"tag":[
"深圳",
"广州",
"北京"
]
}
}
- 推送给多个标签(需要同时在多个标签范围内):在深圳并且是“女”
{
"to":{
"tag_and":[
"深圳",
"女"
]
}
}
- 推送给多个别名:
{
"to":{
"alias":[
"4314",
"892",
"4531"
]
}
}
- 推送给多个注册ID:
{
"to": {
"registration_id": [
"4312kjklfds2",
"8914afd2",
"45fdsa31"
]
}
}
- 可同时推送指定多类推送目标:在深圳或者广州,并且是 “女” “会员”
{
"to":{
"tag":[
"深圳",
"广州"
],
"tag_and":[
"女",
"会员"
]
}
}
body
发送请求体。支持的字段如下:
关键字 | 类型 | 选项 | 含义 |
---|---|---|---|
platform | String 或 JSON Array | 必填 | 推送平台 |
notification | JSON Object | 可选 | |
message | JSON Object | 可选 | |
options | JSON Object | 可选 | 推送参数 |
platform
MTPush 当前支持 Android, iOS 平台的推送。其关键字分别为:"android", "ios"。
如果目标平台为 iOS 平台,需要在 options 中通过 apns_production 字段来制定推送环境。True 表示推送生产环境,False 表示要推送开发环境; 如果不指定则为推送生产环境。
推送到所有平台:
{ "platform" : "all" }
指定特定推送平台:
{
"platform": [
"android",
"ios"
]
}
notification
“通知”对象,是一条推送的实体内容对象之一(另一个是“消息”),是会作为“通知”推送到客户端的。
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
alert | String 或 JSON Object | 必填 | 内容 | 消息内容本身。若 android、ios 下没有指定 alert,则以此为准。 |
android | JSON Object | 选填 | android 平台属性 | android 平台推送参数,详见android 说明 |
ios | JSON Object | 选填 | ios 平台属性 | ios 平台推送参数,详见ios 说明 |
alert
这个位置的 "alert" 属性(直接在 notification 对象下),是一个快捷定义,各平台的 alert 信息如果都一样,则可不定义平台下的 alert,以此为准。如果各平台有定义,则覆盖这里的定义。
{
"notification" : {
"alert" : "Hello, Push!"
}
}
上面定义的 notification 对象,将被推送到 "platform" 指定的多个平台,并且其通知 alert 信息都一样。
android
Android 平台上的通知,被 MTPush SDK 按照一定的通知栏样式展示。支持的字段如下:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
alert | String 或 JSON Object | 必填 | 通知内容 | |
title | String | 可选 | 通知标题 | |
builder_id | Int | 可选 | 通知栏样式ID | Android SDK 可设置通知栏样式,这里根据样式 ID 来指定该使用哪套样式。 |
channel_id | String | 可选 | Android 通知栏通道 ID | 不超过 1000 字节,Android 8.0开始可以进行NotificationChannel 配置,这里根据 channel ID 来指定通知栏展示效果。 |
priority | Int | 可选 | 通知栏展示优先级 | 默认为 0,范围为 -2~2。 |
category | String | 可选 | 通知栏条目过滤或排序 | 完全依赖 rom 厂商对 category 的处理策略。 |
style | Int | 可选 | 通知栏样式类型 | 用来指定通知栏样式类型,默认为 0。 |
big_text | String | 可选 | 大文本通知栏样式 | |
inbox | JSONObject | 可选 | 文本条目通知栏样式 | |
big_pic_path | String | 可选 | 大图片通知栏样式 | |
extras | JSON Object | 可选 | 扩展字段 | 这里自定义 JSON 格式的 Key/Value 信息,以供业务使用。 |
intent | JSON Object | 可选 | 指定跳转页面(推荐) | 使用 intent 里的 url 指定点击通知栏后跳转的目标页面。建议填写 intent 字段,否则点击通知可能无跳转动作。此字段支持以下三种类型:intent:#Intent;action=action 路径;component= 包名 /Activity 全名;end<li>应用首页: intent:#Intent;action=android.intent.action.MAIN;end (固定为此地址) <li>跳转到deeplink地址: scheme://test?key1=val1&key2=val2 |
large_icon | String | 可选 | 通知大图标 | |
small_icon | String | 可选 | 通知小图标 | |
sound | String | 可选 | 铃声 | |
badge_add_num | Int | 可选 | 设置角标数字累加值,在原角标的基础上进行累加 | |
badge_class | String | 可选 | 桌面图标对应的应用入口Activity类, 比如“com.test.badge.MainActivity” | |
display_foreground | String | 可选 | APP 在前台,通知是否展示 |
|
{
"notification": {
"android": {
"alert": "hello, MTPush!",
"title": "Push test",
"builder_id": 3,
"style": 1,
"big_text": "big text content",
"inbox":JSONObject,
"big_pic_path": "picture url",
"priority": 0,
"category": "category str",
"large_icon": "http://push.api.engagelab.cc/largeIcon.jpg",
"small_icon": "http://www.small.com/small_icon.jpg",
"intent": {
"url": "intent:#Intent;component=push.api.engagelab.cc/com.example.mtpushdemo.SettingActivity;end"
},
"extras": {
"news_id": 134,
"my_key": "a value"
}
}
}
}
ios
iOS 平台上 APNs 通知。
该通知内容会由 MTPush 代理发往 Apple APNs 服务器,并在 iOS 设备上在系统通知的方式呈现。
该通知内容满足 APNs 的规范,支持的字段如下:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
alert | String 或 JSON Object | 必填 | 通知内容 | |
sound | String 或 JSON Object | 可选 | 通知提示声音 | |
badge | Int 或 String | 可选 | 应用角标 | |
content-available | Boolean | 可选 | 推送唤醒 | 推送的时候携带"content-available":true 说明是 Background Remote Notification,如果不携带此字段则是普通的Remote Notification。详情参考:Background Remote Notification |
mutable-content | Boolean | 可选 | 通知扩展 | iOS 10 新增的 Notification Service Extension 功能,用于上报每条 APNs 信息的送达状态,使用该功能需要客户端实现 Service Extension 接口,并在服务端使用 mutable-content 字段完成设置。 |
category | String | 可选 | iOS 8 才支持。设置APNs payload中的"category"字段值。 | |
extras | JSON Object | 可选 | 扩展字段 | 这里自定义 Key/value 信息,以供业务使用。 |
thread-id | String | 可选 | 通知分组 | iOS 的远程通知通过该属性来对通知进行分组,同一个 thread-id 的通知归为一组。 |
interruption-level | String | 可选 | 通知优先级和交付时间的中断级别 | iOS 15 的通知级别,取值只能是 active,critical,passive,timeSensitive 中的一个,详情参考:UNNotificationInterruptionLevel。 |
iOS 通知 MTPush 要转发给 APNs 服务器。 MTPush 中 Notification + Message 长度限制为 4000 个字节。 MTPush 在推送时使用 utf-8 编码,所以一个汉字占用 3 个字节长度。
服务端发送示例:
{
"notification": {
"ios": {
"alert": "hello, Push!",
"sound": "sound.caf",
"badge": 1,
"extras": {
"news_id": 134,
"my_key": "a value"
}
}
}
}
客户端收到的消息:
{
"_j_msgid" = 813843507;
aps = {
alert = "hello,Push!";
badge = 1;
sound = "sound.caf";
};
"my_key" = "a value";
"news_id" = 134;
}
message
应用内消息。或者称作:自定义消息,透传消息。
- 此部分内容不会展示到通知栏上,MTPush SDK 收到消息内容后透传给 App。App 需要自行处理。
- iOS 在推送应用内消息通道(非 APNS)获取此部分内容,需 App 处于前台。
支持的字段如下:
关键字 | 类型 | 选项 | 含义 |
---|---|---|---|
msg_content | String 或 JSON Object | 必填 | 消息内容本身 |
title | String | 可选 | 消息标题 |
content_type | String | 可选 | 消息内容类型 |
extras | JSON Object | 可选 | JSON 格式的可选参数 |
示例:
{
"message": {
"msg_content": "Hi,Push",
"content_type": "text",
"title": "msg",
"extras": {
"key": "value"
}
}
}
options
推送可选项。当前包含如下几个可选项:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
time_to_live | Int 或 String | 可选 | 离线消息保留时长(秒) | |
override_msg_id | Long | 可选 | 要覆盖的消息 ID | 如果当前的推送要覆盖之前的一条推送,这里填写前一条推送的 msg_id 就会产生覆盖效果,即: |
apns_production | Boolean | 可选 | APNs 是否生产环境 | 该字段仅对 iOS 的 Notification 有效,如果不指定则为推送生产环境。注意:MTPush 官方 API LIbrary (SDK) 默认设置为推送 “开发环境”。 |
apns_collapse_id | String | 可选 | 更新 iOS 通知的标识符 | |
big_push_duration | Int | 可选 | 定速推送时长(分钟) | |
multi_language | json object | 可选 | 多语言推送设置 | 推送内容多语言适配设置,详情查看multi_language 说明。 |
third_party_channel | JSON Object | 可选 | Android 厂商通道配置信息 | 仅针对配置了厂商通道的用户有效参数,详情查看third_party_channel 说明。 |
multi_language
本字段是 EngageLab Push 服务的多语言推送功能。它允许您为不同语言的用户推送定制化的通知内容。通过在推送请求中指定多个语言及对应的消息内容、标题和 iOS 子标题,您可以针对用户的语言设置发送适当的推送通知。
请求参数
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
en | string | 可选 | 多语言key | 对应推送用户语言,key码详见附录 |
content | string | 可选 | 消息内容 | 根据用户语言替换notification.android.alert、notification.ios.alert、notification.web.alert、message.msg_content里的数据 |
title | string | 可选 | 消息标题 | 根据用户语言替换notification.android.title、notification.ios.alert、notification.web.title、message.title里的数据 |
ios_subtitle | string | 可选 | ios子标题 | 根据用户语言替换notification.ios.alert里的数据 |
请求示例
http请求方式: Post
请求地址:/v4/grouppush 或者 /v4/push
POST数据格式:json
POST数据例子:
{
"options": {
"multi_language": {
"en": {
"content": "",
"title": "",
"ios_subtitle": ""
}
}
}
}
返回示例
成功时:
{
}
失败时:
{
"code":400,
"data":"",
"message":"错误信息"
}
third_party_channel
本字段用来填写 Android 厂商通道的个性化信息,key 只支持 xiaomi、huawei、meizu、oppo、vivo、fcm、honor 这 7 个 Android 厂商通道,可以为其中一个或者多个同时存在,每个厂商类型的 KEY 当前可包含如下几个可选项:
注:多个key存在的情况下,distribution_new取值以厂商通道(xiaomi、huawei、meizu、oppo、vivo、honor)的设置为准。
请求参数
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
distribution_new | String | 必选 | Engagelab 和厂商通道并存时,设置下发优先级 | 取值不能为空字符串。 |
channel_id | String | 可选 | 通知栏消息分类 | 支持OPPO 的私信、小米的通知消息、华为消息分类 类别,分类 ChannelID 值需开发者自行向厂商申请。 |
classification | Int | 可选 | 通知栏消息分类 | vivo 手机厂商通知栏消息分类,不填默认为 0。 |
pushMode | Int | 可选 | vivo推送模式 | 不填默认为 0。详情参考vivo pushMode,使用测试推送需要手动在 vivo 后台配置测试设备的 ID 。 |
importance | String | 可选 | 华为/荣耀通知栏消息智能分类 | 为了适配华为手机厂商的通知栏消息智能分类,对应华为的 importance 字段,不填充默认为 "NORMAL",参考:华为通知消息智能分类。 |
urgency | String | 可选 | 华为厂商自定义消息优先级 | 为了适配华为手机厂商自定义消息的优先级。 |
category | String | 可选 | 华为厂商自定义消息场景标识 | 为了适配华为手机厂商自定义消息,标识高优先级透传消息的特殊场景,或用于标识消息类型以对特定类型消息加快发送,对应值及其说明参考:category 值说明。 |
small_icon_uri | String | 可选 | 厂商消息小图标样式 | |
small_icon_color | String | 可选 | 小米厂商小图标样式颜色 | 为了适配小米厂商的消息小图标样式颜色,不填充默认是灰色 (小米官方后续不在支持自定义小图标,建议开发者不要继续使用小米 small icon 相关特性功能)。 |
big_text | String | 可选 | 厂商消息大文本样式 | |
only_use_vendor_style | Boolean | 可选 | 是否使用自身通道设置样式 | 是否只使用自身通道设置的样式,不使用 android 里面设置的样式,默认为 false, |
请求示例
"third_party_channel": {
"xiaomi": {
"distribution_new": "mtpush",
"channel_id": "*******",
"small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png",
"small_icon_color": "#ABCDEF",
},
"huawei": {
"distribution_new": "mtpush_pns",
"importance": "NORMAL",
"small_icon_uri": "https://xx.com/xx.jpg",
"only_use_vendor_style": true
},
"meizu": {
"distribution_new": "mtpush"
},
"fcm": {
"distribution_new": "mtpush"
},
"oppo": {
"distribution_new": "mtpush",
"channel_id": "*******",
"large_icon": "3653918_5f92b5739ae676f5745bcbf4",
},
"vivo": {
"distribution_new": "mtpush",
"classification": 0,
"pushMode": 0
}
}
request_id
请求 id,客户自定义的可选字段。客户用来标识是哪条请求,响应时返回。
请求示例
{
"request_id":"12345678"
}
返回示例
{
"msg_id": "1225764",
"request_id": "12345678"
}
custom_args
客户自定义的,可选字段,响应时不返回,回调时返回。
请求示例
{
"custom_args":"business info"
}
返回参数
成功返回
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
request_id | String | 可选 | 请求时提交的自定义 ID,响应时原样返回。 |
message_id | String | 必选 | 消息 ID,唯一标识某一条消息。 |
< HTTP/1.1 200 OK
< Content-Type: application/json
{"request_id":"18","msg_id":"1828256757"}
失败返回
http 状态码为 4xx 或者 5xx,响应体包含字段如下:
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
code | int | 必选 | 错误码,详见错误码 说明 |
message | String | 必选 | 错误详情 |
{
"code": 3002,
"message": "Push.template field must be set correctly when type is template"
}
调用返回
HTTP 状态码
参考文档:HTTP-Status-Code
错误码
Code | 描述 | 详细解释 | HTTP Status Code |
---|---|---|---|
20101 | 推送参数无效 | registration_id 无效或不属于当前 appkey | 400 |
21001 | 只支持 HTTP Post 方法 | 不支持 Get 方法 | 405 |
21002 | 缺少了必须的参数 | 必须改正 | 400 |
21003 | 参数值不合法 | 必须改正 | 400 |
21004 | 验证失败 | 必须改正,详情请看:调用验证 | 401 |
21005 | 消息体太大 | 必须改正, Notification+Message长度限制为 2048 字节 | 400 |
21008 | app_key 参数非法 | 必须改正,请仔细对比你所传的 appkey 是否与应用信息中的一致,是否多了空格 | 400 |
21009 | 系统内部错误 | 必须改正 | 400 |
21011 | 没有满足条件的推送目标 | 请检查 to 字段 | 400 |
21015 | 请求参数校验失败 | 存在非预期的参数 | 400 |
21016 | 请求参数校验失败 | 参数类型错误,或者参数长度超出限制 | 400 |
21030 | 内部服务超时 | 稍后重试 | 503 |
23006 | 参数错误 | 定速推送 big_push_duration 超过最大值 1440 | 400 |
23008 | 接口限速 | 单应用推送接口 qps 达到上限(500 qps) | 400 |
27000 | 系统内存错误 | 请重试 | 500 |
27001 | 参数错误 | 校验信息为空 | 401 |
27008 | 参数错误 | third_party_channel 里面的 distribution 不为空,但是 notification 的 alert 内容为空 | 401 |
27009 | 参数错误 | third_party_channel 中 distribution 格式无效或为空 | 401 |
21038 | 推送权限错误 | VIP已过期或未开通 | 401 |
推送限制
厂商通道 | 标题长度 | 内容长度 | 敏感词 | 其他说明 |
---|---|---|---|---|
Engagelab 通道 | 不限制,但限制消息体总大小 | 不限制,但限制消息体总大小 | - | MTPush 中 Notification + Message 长度限制为 4000 个字节。 |
华为通道 | < 40 个字符 | < 1024 字符 | 禁止携带政府,领导人名称、台独等相关内容 | 默认【营销通知】的权限为静默通知,静默推送没有声音、震动等提示。 |
荣耀通道 | 不限制,但消息体总大小<4096字节 | 不限制,但消息体总大小 < 4096 字节 | 禁止携带政府,领导人名称、台独等相关内容 | - |
魅族通道 | < 32 个字符 | < 100 个字符 | 禁止特殊字符,如:# | |
小米通道 | < 50 个字符 | < 128 个字符 | 禁止特殊字符,如:#、>> | |
OPPO 通道 | < 32 个字符 | < 200 个字符 | 暂无说明 | |
vivo 通道 | < 40 个字符 | < 100 个字符 | ||
APNS 通道 | < 20 个字符(40 个英文字符) | 暂无说明 | 暂无 |
多语言码
语言 | Language | Language Code |
---|---|---|
英语 | English | en |
阿拉伯语 | Arabic | ar |
简体中文 | Chinese (Simplified) | zh-Hans |
繁体中文 | Chinese (Traditional) | zh-Hant |
捷克语 | Czech | cs |
丹麦语 | Danish | da |
荷兰语 | Dutch | nl |
法语 | French | fr |
德语 | German | de |
印地语 | Hindi | hi |
意大利语 | Italian | it |
日语 | Japanese | ja |
韩语 | Korean | ko |
马来语 | Malay | ms |
俄语 | Russian | ru |
西班牙语 | Spanish | es |
泰语 | Turkish | th |
越南语 | Vietnamese | vi |