公共参数

公共参数

本文档主要介绍个推开放平台公共请求参数和公共返回参数

公共请求参数

以下参数是调用每个接口都需要使用的参数

header参数

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

公共返回结构

以下参数格式为每个接口返回的数据的通用格式。

名称 类型 描述
code Number 成功或失败code码,详细含义见业务返回码说明
msg String 失败时返回此说明
data Json 详见接口说明

推送接口公共消息说明

推送消息体示例(具体含义请见推送API):

{
    "request_id":"请填写10到32位的id",
    "audience":"all",
    "settings":{
        "ttl":7200000,
        "strategy":{
            "default":1,
            "ios":4,
            "st":4
        }
    },
    "push_message":{
        "notification":{
            "title":"请填写标题",
            "body":"请填写内容",
            "click_type":"url",
            "url":"https://www.json.cn/"
        }
    },
    "push_channel":{
        "android":{
            "ups":{
                "notification":{
                    "title":"请填写android标题",
                    "body":"请填写android内容",
                    "click_type":"url",
                    "url":"https://xxx"
                }
            }
        },
        "ios":{
            "type":"notify",
            "payload":"自定义消息",
            "aps":{
                "alert":{
                    "title":"请填写ios标题",
                    "body":"请填写ios内容"
                },
                "content-available":0
            },
            "auto_badge":"+1"
        },
      "harmony":{
        "notification":{
          "title":"请填写harmony标题",
          "body":"请填写harmony内容",
          "category":"鸿蒙华为通知消息类别",
          "click_type":"startapp"
        }
      }
    }
}

audience 推送目标用户设置

推送目标用户,表示一条推送将要被推送到哪些用户列表。设置目标用户的方式:cid、别名(alias),tag等等。

注意:audience的参数选择根据请求url决定,与请求url不匹配时会报错,比如:选择接口为/push/single/cid,但audience选择alias,此时推送失败;

参数 类型 描述
cid String Array 根据cid选择推送目标用户时使用
alias String Array 根据别名选择推送目标用户时使用,绑定别名请参考接口
fast_custom_tag String 为用户自定义标签,根据fast_custom_tag选择推送用户时使用,绑定标签请参考接口
tag Json Array tag 指群推接口的用户筛选条件(包含多种类型条件:phone_type 手机类型; region 省市; custom_tag 用户标签),详细格式见接口中参数说明
all String 选择推送应用的所有用户

示例(非all示例,以下参数只能选择一个):

{
    "audience":{
        "cid":[""],
        "alias":[""],
        "fast_custom_tag":"",
        "tag":[{
           "key":"phone_type",
           "values":[
               "android"
           ],
           "opt_type":"and"
        }]
    }
}

示例(all,推送所有用户):

{
    "audience": "all"
}

settings 推送条件设置

名称 类型 是否必需 默认值 描述
ttl Number 2小时 消息离线时间设置,单位毫秒,-1表示不设离线,-1 ~ 3 * 24 * 3600 * 1000(3天)之间
strategy Json {"default":1} 厂商通道策略,详细内容见strategy
speed Number 0 定速推送,例如100,个推控制下发速度在100条/秒左右,0表示不限速
schedule_time Number 定时推送时间,必须是7天内的时间,格式:毫秒时间戳,此功能需要开通VIP,如需开通请点击右侧“技术咨询”了解详情
custom_callback String 自定义回执字段,传入此参数可在回执回调时附加传入的内容,用于自定义的消息标识,此功能需要开通VIP,如需开通请点击右侧“技术咨询”了解详情
filter_notify_off Boolean false 是否过滤通知关闭通知用户,false表示不过滤,true表示过滤
active_days Number 7天 厂商智能配额策略-用户连续活跃天数,单位天,限制3 ~ 15天之间
need_backup Boolean false 厂商智能配额策略-是否需要兜底(离线消息到期后一定时间内通过厂商通道下发),false表示不需要,true表示需要

示例:

{
  "settings": {
    "ttl": 86400000,
    "strategy": {
      "default": 1,
      "ios": 2,
      "vv": 6
    },
    "speed": 100,
    "schedule_time": 1591794372930,
    "custom_callback": "msg-as-you-like-2022112801057743",
    "filter_notify_off": true,
    "active_days": 7,
    "need_backup": true
  }
}

strategy 厂商下发策略选择

功能描述

使用方式:

名称 类型 是否必需 默认值 描述
default Number 1 默认所有通道的策略选择1-4
1: 表示该消息在用户在线时推送个推通道,用户离线时推送厂商通道;
2: 表示该消息只通过厂商通道策略下发,不考虑用户是否在线;
3: 表示该消息只通过个推通道下发,不考虑用户是否在线;
4: 表示该消息优先从厂商通道下发,若消息内容在厂商通道代发失败后会从个推通道下发。
ios Number ios 通道策略1-4,表示含义同上,要推送ios通道,需要在个推开发者中心上传ios证书,建议填写2或4,否则可能会有消息不展示的问题
hw Number 华为 通道策略1-4,表示含义同上
ho Number 荣耀 通道策略1-4,表示含义同上
xm Number 小米 通道策略1-4和6,表示含义同上
6: 表示该消息选用厂商智能配额策略,用户在线时推送个推通道,用户离线时常活跃用户推送个推通道,低活跃用户推送厂商通道。
xmg Number 小米海外 通道策略1-4,表示含义同上
vv Number vivo 通道策略1-4和6,表示含义同上
op Number oppo 通道策略1-4和6,表示含义同上
opg Number oppo海外 通道策略1-4,表示含义同上
mz Number 魅族 通道策略1-4和6,表示含义同上
hoshw Number 鸿蒙华为 通道策略1-4,表示含义同上
st Number 锤子/坚果 通道策略1-4,表示含义同上,需要开通ups厂商使用该通道推送消息
wx Number 微信 通道策略1-4,表示含义同上,需要授权微信小程序使用该通道推送消息

说明:厂商推送策略为 VIP 功能,需升级服务后方可使用。非VIP用户无法设置厂商策略,无需填写strategy 字段,默认所有通道策略都是1 。若须申请修改请点击右侧“技术咨询”了解详情。

说明:厂商智能配额策略为 SVIP 功能,需升级服务后方可使用。若须申请修改请点击右侧“技术咨询”了解详情。

使用示例:

{
    "settings": {
        "strategy":{
            "default":1,
            "ios":4,
            "hw":1
        }
    }
}

push_message 在线个推通道消息内容

通知消息(notification),仅支持安卓系统,iOS系统不展示个推通道下发的通知消息

名称 类型 是否必需 默认值 描述
duration String 手机端通知展示时间段,格式为毫秒时间戳段,两个时间的时间差必须大于10分钟,例如:"1590547347000-1590633747000"
notification Json 通知消息内容,安卓系统和鸿蒙系统支持,iOS系统不展示个推通知消息,与transmissionrevoke三选一,都填写时报错
transmission String 透传消息内容,安卓和iOS均支持,与notificationrevoke 三选一,都填写时报错,长度 ≤ 3072字
revoke Json 撤回消息时使用(仅撤回个推通道消息),与notificationtransmission三选一,都填写时报错(消息撤回请勿填写策略参数)

说明:厂商不支持定时展示效果,传递duration参数将无法下发厂商消息。

notification

名称 类型 是否必需 默认值 描述
title String 通知消息标题,长度 ≤ 50字
body String 通知消息内容,长度 ≤ 256字
big_text String 长文本消息内容,通知消息+长文本样式,与big_image二选一,两个都填写时报错,长度 ≤ 512字
big_image String 大图的URL地址,通知消息+大图样式, 与big_text二选一,两个都填写时报错,URL长度 ≤ 1024字
logo String 通知的图标名称,包含后缀名(需要在客户端开发时嵌入),如“push.png”,长度 ≤ 64字
logo_url String 通知图标URL地址,长度 ≤ 256字
channel_id String Default 通知渠道id,长度 ≤ 64字
channel_name String Default 通知渠道名称,长度 ≤ 64字
channel_level Number 3 设置通知渠道重要性(可以控制响铃,震动,浮动,闪灯等等)
android8.0以下
0,1,2:无声音,无振动,不浮动
3:有声音,无振动,不浮动
4:有声音,有振动,有浮动
android8.0以上
0:无声音,无振动,不显示;
1:无声音,无振动,锁屏不显示,通知栏中被折叠显示,导航栏无logo;
2:无声音,无振动,锁屏和通知栏中都显示,通知不唤醒屏幕;
3:有声音,无振动,锁屏和通知栏中都显示,通知唤醒屏幕;
4:有声音,有振动,亮屏下通知悬浮展示,锁屏通知以默认形式展示且唤醒屏幕;
click_type String 点击通知后续动作,
目前支持以下后续动作,
intent:打开应用内特定页面(intent和want字段必须填写一个)
url:打开网页地址,
payload:自定义消息内容启动应用
payload_custom:自定义消息内容不启动应用
startapp:打开应用首页,
none:纯通知,无后续动作
intent String click_type为intent时,intent和want必须填写一个 针对安卓系统设置点击通知打开应用特定页面,长度 ≤ 4096字;
示例:intent://com.getui.push/detail?#Intent;scheme=gtpushscheme;launchFlags=0x4000000;
package=com.getui.demo;component=com.getui.demo/
com.getui.demo.DemoActivity;S.payload=payloadStr;end
intent生成请参考
want String click_type为intent时,intent和want必须填写一个 针对鸿蒙系统设置点击通知打开应用特定页面,长度小于1000字节,通知带want传递参数(json格式)
简单示例:
{"deviceId":"","bundleName":"com.getui.push","abilityName":"TestAbility","uri":"https://www.test.com:8080/push/test","action":"com.test.action","parameters":{"name":"Getui","age":12}}
其中parameters部分为附加参数,非必填,action、uri二选一,bundleName非必填,abilityName为必填
want生成请参考
url String click_type为url时必填 点击通知栏消息时,唤起系统默认浏览器打开此链接。必须填写可访问的链接,url长度 ≤ 1024字
示例:https://www.getui.com
payload String click_type为payload/payload_custom时必填 点击通知时,附加自定义透传消息,长度 ≤ 3072字
notify_id Number 覆盖任务时会使用到该字段,两条消息的notify_id相同,新的消息会覆盖老的消息,范围:0-2147483647
ring_name String 自定义铃声,请填写文件名,不包含后缀名(需要在客户端开发时嵌入),个推通道下发有效
客户端SDK最低要求 2.14.0.0
badge_add_num Number 角标, 必须大于0, 个推通道下发有效
此属性目前针对华为和荣耀
华为EMUI 4.1 及以上设备有效
荣耀版本要求 Magic UI 4.0及以上有效
角标数字数据会和之前角标数字进行叠加;
举例:角标数字配置1,应用之前角标数为2,发送此角标消息后,应用角标数显示为3。
客户端SDK最低要求 2.14.0.0
thread_id String 消息折叠分组,设置成相同thread_id的消息会被折叠(仅支持个推渠道下发的安卓消息)。目前与iOS的thread_id设置无关,安卓和iOS需要分别设置。
category string 个推通道华为消息分类,可选值:CATEGORY_PROMO, CATEGORY_RECOMMENDATION, CATEGORY_SOCIAL, CATEGORY_CALL, CATEGORY_EMAIL, CATEGORY_MESSAGE, CATEGORY_NAVIGATION, CATEGORY_REMINDER, CATEGORY_SERVICE, CATEGORY_ALARM, CATEGORY_STOPWATCH, CATEGORY_PROGRESS, CATEGORY_LOCATION_SHARING。
参考:华为消息分类标准 -本地通知适配
客户端SDK最低要求 3.3.1.0

revoke

名称 类型 是否必需 默认值 描述
old_task_id String 需要撤回的taskId
force boolean 在没有找到对应的taskId,是否把对应appId下所有的通知都撤回

示例:
通知消息:

{
    "push_message":{
        "notification":{
            "title":"请填写你的通知标题",
            "body":"请填写你的通知内容",
            "big_text":"请填写你的通知长文本",
            "logo":"logo.png",
            "logo_url":"http://xxxx/a.png",
            "channel_id":"请填写你的channel_id",
            "channel_name":"请填写你的channel_name",
            "channel_level":3,
            "click_type":"intent",
            "intent":"intent:#Intent;action=;end"
        }
    }
}

透传消息:

{
   "push_message":{
        "transmission":"请填写你的透传消息内容"
    }
}

撤回消息:

{
   "push_message":{
        "revoke": {
            "old_task_id": "xxx",
            "force": false
        }
    }
}

push_channel 离线厂商通道消息内容

名称 类型 是否必需 默认值 描述
ios Json ios通道推送消息内容
android Json android通道推送消息内容
mp Json miniProgram通道推送消息内容(只支持透传消息)

ios厂商通道消息

具体参数含义详见苹果APNs文档

名称 类型 是否必需 默认值 描述
type String notify默认通知消息 voip:voip语音推送,notify:apns通知消息,liveactivity:灵动岛推送(不支持p12证书)
laId String 在个推iOS SDK升级到3.0.3.0后,type选择liveactivity时,通过传入该参数选择指定推送的灵动岛
aps Json 推送通知消息内容
auto_badge String 用于计算icon上显示的数字,还可以实现显示数字的自动增减,如“+1”、 “-1”、 “1” 等,计算结果将覆盖badge
payload String 增加自定义的数据
multimedia Json Array 多媒体设置
apns-collapse-id String 使用相同的apns-collapse-id可以覆盖之前的消息

aps

名称 类型 是否必需 默认值 描述
alert Json 通知消息
content-available Number 0 0表示普通通知消息(默认为0);
1表示静默推送(无通知栏消息),静默推送时不需要填写其他参数。
苹果建议1小时最多推送3条静默消息
sound String 自定义铃声,设置为包含后缀名的完整文件名,示例值:ring.mp3
系统铃声,设置为:default
无声,设置为:com.gexin.ios.silence,或不填
category String 在客户端通知栏触发特定的action和button显示
thread-id String ios的远程通知通过该属性对通知进行分组,仅支持iOS 12.0以上版本
timestamp Number type为liveactivity时必填 秒级10位时间戳
event String type为liveactivity时必填且值为update 灵动岛推送事件
content-state Json type为liveactivity时必填 灵动岛推送透传参数,Json内的kv由业务方自定义,客户APP拿到值后自行解析

alert

名称 类型 是否必需 默认值 描述
title String 通知消息标题
body String 通知消息内容
action-loc-key String (用于多语言支持)指定执行按钮所使用的Localizable.strings
loc-key String (用于多语言支持)指定Localizable.strings文件中相应的key
loc-args String Array 如果loc-key中使用了占位符,则在loc-args中指定各参数
launch-image String 指定启动界面图片名
title-loc-key String (用于多语言支持)对于标题指定执行按钮所使用的Localizable.strings,仅支持iOS8.2以上版本
title-loc-args String Array 对于标题,如果loc-key中使用的占位符,则在loc-args中指定各参数,仅支持iOS8.2以上版本
subtitle String 通知子标题,仅支持iOS8.2以上版本
subtitle-loc-key String 当前本地化文件中的子标题字符串的关键字,仅支持iOS8.2以上版本
subtitle-loc-args String Array 当前本地化子标题内容中需要置换的变量参数 ,仅支持iOS8.2以上版本

multimedia说明

该字段为Array类型,最多可设置3个子项,每个参数定义如下所示:

名称 类型 是否必需 默认值 描述
url String 多媒体资源地址
type Number 资源类型(1.图片,2.音频,3.视频)
only_wifi Boolean false 是否只在wifi环境下加载,如果设置成true,但未使用wifi时,会展示成普通通知

示例:

voip语音推送:

{
    "ios":{
        "type":"voip",
        "payload":"自定义消息"
    }
}

apns通知消息

{
    "ios":{
        "type":"notify",
        "payload":"自定义消息",
        "aps":{
            "alert":{
                "title":"通知标题",
                "body":"通知内容"
            },
            "content-available":0,
            "sound":"com.gexin.ios.silence",
            "category":"ACTIONABLE"
        },
        "auto_badge":"+1",
        "multimedia": [{
            "url": "https://xxx",
            "type": 1,
            "only_wifi": false
        }]
    }
}

apns静默推送 可参考苹果APNs文档

{
    "ios":{
        "aps":{
            "content-available":1
        },
        "payload": "自定义消息"
    }
}

apns灵动岛推送 可参考苹果APNs文档

{
    "ios": {
        "type": "liveactivity",
        "aps": {
            "timestamp": 1168364460,
            "event": "update",
            "content-state": {
                "driverName": "Anne Johnson",
                "estimatedDeliveryTime": 1659416400
            },
            "alert": {
                "title": "通知标题",
                "body": "通知内容",
                "sound": "default"
            }
        }
  }
}

android厂商通道消息

更多Android厂商参数,可以参考多厂商参数文档

名称 类型 是否必需 默认值 描述
ups Json android厂商通道推送消息内容

ups

名称 类型 是否必需 默认值 描述
notification Json 通知消息内容,与transmission、revoke三选一,都填写时报错。若希望客户端离线时,直接在系统通知栏中展示通知栏消息,推荐使用此参数。
transmission String 透传消息内容,与notification、revoke 三选一,都填写时报错,长度 ≤ 3072字
revoke Json 撤回消息时使用(仅撤回厂商通道消息,支持的厂商有小米、VIVO),与notification、transmission三选一,都填写时报错(消息撤回请勿填写策略参数)
options Json 第三方厂商扩展内容

说明:撤回小米厂商消息时,请提前在应用配置中配置正确的应用包名

notification

名称 类型 是否必需 默认值 描述
title String 通知栏标题(长度建议取最小集)
小米:title长度限制为50字
魅族:title长度限制32字
OPPO:title长度限制50字
VIVO:title长度限制40英文字符(最大20个汉字(一个汉字等于两个英文字符))
body String 通知栏内容(长度建议取最小集)
HW:content长度限制256字
小米:content长度限制128字
魅族:content长度限制100字
OPPO:content长度限制200字
VIVO:content长度限制100英文字符(最大50个汉字(一个汉字等于两个英文字符))
click_type String 点击通知后续动作,
目前支持以下后续动作,
intent:打开应用内特定页面(厂商都支持),
url:打开网页地址(厂商都支持;华为/荣耀要求https协议,且游戏类应用不支持打开网页地址),
startapp:打开应用首页(厂商都支持)
intent String click_type为intent时必填 点击通知打开应用特定页面,intent格式必须正确且不能为空,长度 ≤ 4096字;【注意:vivo侧厂商限制 ≤ 1024字符】
示例: intent://com.getui.push/detail?#Intent;scheme=gtpushscheme;launchFlags=0x4000000;package=com.getui.demo;component=com.getui.demo/com.getui.demo.DemoActivity;S.payload=payloadStr;S.gttask=;end
intent生成请参考
url String click_type为url时必填 点击通知栏消息时,唤起系统默认浏览器打开此链接。必须填写可访问的链接,url长度 ≤ 1024 【注意:vivo侧厂商限制 ≤ 1000字符】
示例:https://www.getui.com
notify_id Number 消息覆盖使用,两条消息的notify_id相同,新的消息会覆盖老的消息,范围:0-2147483647

revoke

名称 类型 是否必需 默认值 描述
old_task_id String 需要撤回的taskId

options

{
  "constraint":{"key": "value"}
}
名称 类型 描述
constraint String 扩展内容对应厂商通道设置如:ALL,HW,HO,XM(小米国内),XMG(小米海外),VV,OP,OPG(OPPO海外),MZ,UPS(UPS的参数会影响UPS下面的所有机型,比如ST,SN等等)
key String 厂商内容扩展字段
value 具体数据类型 value的设置根据key值决定

详细内容见多厂商参数

通知示例:

{
    "android":{
        "ups":{
            "notification":{
                "title":"厂商通知标题",
                "body":"厂商通知内容",
                "click_type":"url",
                "url":"https://xxx",
                "notify_id":1234
            },
            "options":{
                "HW":{
                    "/message/android/notification/badge/class": "应用入口Activity路径名称",
                    "/message/android/notification/badge/add_num": 1
                },
                "VV":{
                    "/classification": 0
                }
            }
        }
    }
}

透传示例:(仅华为通道支持,其它安卓通道不支持透传消息)

{
    "android":{
        "ups":{
            "transmission":"厂商透传消息",
            "options":{
                "HW":{
                    "/message/android/urgency":"HIGH",
                    "/message/android/category":"PLAY_VOICE"
                }
            }
        }
    }
}

harmony厂商通道消息

名称 类型 是否必需 默认值 描述
notification Json 通知消息内容,与transmission二选一,都填写时报错。若希望客户端离线时,直接在系统通知栏中展示通知栏消息,推荐使用此参数。
transmission String 透传消息内容,与notification二选一,都填写时报错,长度 ≤ 3072字
options Json 第三方厂商扩展内容

notification

名称 类型 是否必需 默认值 描述
title String 通知栏标题
body String 通知栏内容
category String 鸿蒙华为通知消息类别
click_type String 点击通知后续动作,
目前支持以下后续动作,
want:打开应用内特定页面,
startapp:打开应用首页
action String click_type为want时,action和uri必须填一个 点击通知打开应用特定页面
uri String click_type为want时,action和uri必须填一个 点击通知打开应用特定页面
payload String 附加消息,参数必须是json格式

options

{
  "constraint":{"key": "value"}
}
名称 类型 描述
constraint String 扩展内容对应厂商通道设置如:HW
key String 厂商内容扩展字段
value 具体数据类型 value的设置根据key值决定

详细内容见多厂商参数

通知示例:

{
    "harmony":{
        "notification":{
            "title":"鸿蒙通知标题",
            "body":"鸿蒙通知内容",
            "category":"MARKETING",
            "click_type":"startapp"
        },
        "options":{
            "HW":{
                "/pushOptions/testMessage": true
            }
        }
    }
}

透传示例:(仅鸿蒙华为通道支持,但需要在鸿蒙华为后台申请开通)

{
    "harmony":{
        "transmission": "厂商透传消息"
    }
}

miniProgram厂商通道消息

名称 类型 是否必需 默认值 描述
wx Json 微信小程序通道推送消息内容

wx

名称 类型 是否必需 默认值 描述
template_id String 所需下发的订阅模板id
page String 点击模板卡片后的跳转页面,仅限本小程序内的页面。支持带参数,(示例index?foo=bar)。该字段不填则模板无跳转
miniprogram_state String formal 跳转小程序类型:
developer:开发版
trial:体验版
formal:正式版
lang String zh_CN 进入小程序查看”的语言类型:
zh_CN:简体中文
en_US:英文
zh_HK:繁体中文
zh_TW:繁体中文
data Json 模板内容,格式形如 { "key1": { "value": any }, "key2": { "value": any } }的Json对象

透传示例:

{
  "mp":{
    "wx":{
      "template_id":"TEMPLATE_ID",
      "page":"index",
      "miniprogram_state":"formal",
      "lang":"zh_CN",
      "data":{
        "number01":{
          "value":"300766"
        },
        "date01":{
          "value":"2019年03月25日"
        },
        "site01":{
          "value":"每日互动股份有限公司"
        }
      }
    }
  }
}
开发者中心 SDK 下载

文档中心搜索

技术
咨询

微信扫一扫

随时联系技术支持

在线
咨询