"> 公共参数-个推文档中心

公共参数

公共参数

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

公共请求参数

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

header参数

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

公共返回结构

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

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

推送接口公共消息说明

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

{
    "request_id":"请填写10到32位的id",
    "audience":"all",
    "settings":{
        "ttl":3600000,
        "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://www.baidu.com/"
                }
            }
        },
        "ios":{
            "type":"notify",
            "payload":"自定义消息",
            "aps":{
                "alert":{
                    "title":"请填写ios标题",
                    "body":"请填写ios内容"
                },
                "content-available":0
            },
            "auto_badge":"+1"
        }
    }
}

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"
}

setting 推送条件设置

名称 类型 是否必需 默认值 描述
ttl Number 1小时 消息离线时间设置,单位毫秒,-1表示不设离线,-1 ~ 3 * 24 * 3600 * 1000(3天)之间
strategy Json 厂商通道策略,详细内容见strategy
speed Number 0 定速推送,例如100,个推控制下发速度在100条/秒左右,0表示不限速
schedule_time Number 定时推送时间,格式:毫秒时间戳,此功能需要开通VIP,如需开通请联系 lieg@getui.com

示例:

{
    "ttl": 3600,
    "strategy": {
        "default": 1,
        "ios": 2
    },
    "speed": 100,
    "schedule_time": 1591794372930
}

strategy 厂商下发策略选择

详细介绍见说明

名称 类型 是否必需 默认值 描述
default Number 1 默认所有通道的策略选择1-4
1: 表示该消息在用户在线时推送个推通道,用户离线时推送厂商通道;
2: 表示该消息只通过厂商通道策略下发,不考虑用户是否在线;
3: 表示该消息只通过个推通道下发,不考虑用户是否在线;
4: 表示该消息优先从厂商通道下发,若消息内容在厂商通道代发失败后会从个推通道下发。
其中名称可填写: iossthwxmvvmzop,如有疑问可联系邮箱 lieg@getui.com
ios Number ios通道策略1-4,表示含义同上,要推送ios通道,需要在个推开发者中心上传ios证书,建议填写2或4,否则可能会有消息不展示的问题
st Number 通道策略1-4,表示含义同上,需要开通st厂商使用该通道推送消息
... Number 通道策略1-4,表示含义同上

示例:

{
    "strategy":{
        "default":1,
        "ios":4,
        "st":1
    }
}

push_message 个推通道消息内容

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

名称 类型 是否必需 默认值 描述
duration String 手机端通知展示时间段,格式为毫秒时间戳段,两个时间的时间差必须大于10分钟,例如:"1590547347000-1590633747000"
notification Json 通知消息内容,仅支持安卓系统,iOS系统不展示个推通知消息,与transmission二选一,两个都填写时报错
transmission String 纯透传消息内容,安卓和iOS均支持,与notification 二选一,两个都填写时报错,长度 ≤ 3072

notification

名称 类型 是否必需 默认值 描述
title String 通知消息标题,长度 ≤ 50
body String 通知消息内容,长度 ≤ 256
big_text String 长文本消息内容,通知消息+长文本样式,与big_image二选一,两个都填写时报错,长度 ≤ 512
big_image String 大图的URL地址,通知消息+大图样式, 与big_text二选一,两个都填写时报错,长度 ≤ 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 点击通知后续动作,
目前支持5种后续动作,
intent:打开应用内特定页面,
url:打开网页地址,
payload:启动应用加自定义消息内容,
startapp:打开应用首页,
none:纯通知,无后续动作
intent String click_type为intent时必填 点击通知打开应用特定页面,长度 ≤ 2048;
示例:intent:#Intent;component=你的包名/你要打开的 activity 全路径;S.parm1=value1;S.parm2=value2;end
intent生成请参考
url String click_type为url时必填 点击通知打开链接,长度 ≤ 1024
payload String click_type为payload时必填 点击通知加自定义消息,长度 ≤ 3072
notify_id Number 覆盖任务时会使用到该字段,两条消息的notify_id相同,新的消息会覆盖老的消息

示例:
通知消息:

{
    "push_message":{
        "duration":"1590547347000-1590633747000",
        "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,
            "notify_id":1234,
            "click_type":"intent",
            "intent":"intent:#Intent;action=;end"
        }
    }
}

透传消息:

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

push_channel 厂商通道消息内容

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

ios厂商通道消息

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

名称 类型 是否必需 默认值 描述
type String notify默认通知消息 voip:voip语音推送,notify:apns通知消息
aps Json 推送通知消息内容
auto_badge String 用于计算icon上显示的数字,还可以实现显示数字的自动增减,如“+1”、 “-1”、 “1” 等,计算结果将覆盖badge
payload String 增加自定义的数据
multimedia Json Array 多媒体设置

aps

名称 类型 是否必需 默认值 描述
alert Json 通知消息
content-available Number 0 推送直接带有透传数据,content-available=1表示静默推送,静默推送时不需要填写其他参数,详细参数填写见示例,苹果建议1小时最多推送3条静默消息
sound String 通知铃声文件名,无声设置为“com.gexin.ios.silence”
category String 在客户端通知栏触发特定的action和button显示

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
        }]
    }
}

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

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

android厂商通道消息

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

ups

名称 类型 是否必需 默认值 描述
notification Json 通知消息内容,与transmission 二选一,两个都填写时报错
transmission String 透传消息内容,与notification 二选一,两个都填写时报错,长度 ≤ 3072

notification

名称 类型 是否必需 默认值 描述
title String 第三方厂商通知标题,长度 ≤ 50
body String 第三方厂商通知内容,长度 ≤ 256
click_type String 点击通知后续动作,
目前支持5种后续动作,
intent:打开应用内特定页面,
url:打开网页地址,
payload:启动应用加自定义消息内容,
startapp:打开应用首页,
none:纯通知,无后续动作
intent String click_type为intent时必填 点击通知打开应用特定页面,intent格式必须正确且不能为空,长度 ≤ 2048;
示例:intent:#Intent;component=你的包名/你要打开的 activity 全路径;S.parm1=value1;S.parm2=value2;end
intent生成请参考
url String click_type为url时必填 点击通知打开链接,长度 ≤ 1024
payload String click_type为payload时必填 点击通知加自定义消息,长度 ≤ 3072
notify_id Number 消息覆盖使用,两条消息的notify_id相同,新的消息会覆盖老的消息
options Json Array 第三方厂商通知扩展内容

options

名称 类型 是否必需 默认值 描述
constraint String 扩展内容对应厂商通道设置如:HW,MZ,...
key String 厂商内容扩展字段,单个厂商特有字段,
key目前支持的所有字段:
hw角标设置:badgeAddNum,
badgeClass要设置hw角标,这两个字段需要配合使用 ,hw的icon
op私信 channel,op的消息去重 app_meaasge_id,
vv的消息分类classification, 0 代表运营消息,1代表系统消息,不填默认为0。
xm的channel:目前只有op和xm支持
value 具体数据类型 value的设置根据key值决定。例如,
hw角标设置:key设为badgeAddNum,value:1(原来的角标值+1)key设为badgeClass,value:请写入角标设置的应用类名)
key设为icon,value:请写⼊对应图标地址

通知示例:

{
    "android": {
      "ups": {
        "notification": {
          "title": "厂商通知标题",
          "body": "厂商通知内容",
          "click_type": "url",
          "url": "https://www.baidu.com/",
          "notify_id":1234,
          "options": [
            {
              "constraint": "HW",
              "key": "badgeAddNum",
              "value": "1"
            },
            {
              "constraint": "HW",
              "key": "badgeClass",
              "value": "com.getui.demo.GetuiSdkDemoActivity"
            },
            {
              "constraint": "HW",
              "key": "icon",
              "value": "https://xxx"
            },
            {
              "constraint": "OP",
              "key": "app_message_id",
              "value": "xxx"
            },
            {
              "constraint": "OP",
              "key": "channel",
              "value": "Default"
            },
            {
              "constraint": "VV",
              "key": "classification",
              "value": 0
            },
            {
              "constraint": "XM",
              "key": "channel",
              "value": "xxx"
            }
          ]
        }
      }
    }
}

透传示例:

{
    "android": {
      "ups": {
        "transmission": ""
      }
    }
}
开发者中心 SDK 下载

文档中心搜索