公共参数

公共参数

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

公共请求参数

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

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://xxx"
                }
            }
        },
        "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":{"default":1}} 厂商通道策略,详细内容见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相同,新的消息会覆盖老的消息,范围:0-2147483647

示例:
通知消息:

{
    "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 多媒体设置
apns-collapse-id String 使用相同的apns-collapse-id可以覆盖之前的消息

aps

名称 类型 是否必需 默认值 描述
alert Json 通知消息
content-available Number 0 0表示普通通知消息(默认为0);
1表示静默推送(无通知栏消息),静默推送时不需要填写其他参数。
苹果建议1小时最多推送3条静默消息
sound String 通知铃声文件名,如果铃声文件未找到,响铃为系统默认铃声。
无声设置为“com.gexin.ios.silence”或不填
category String 在客户端通知栏触发特定的action和button显示
thread-id String ios的远程通知通过该属性对通知进行分组,仅支持iOS 12.0以上版本

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相同,新的消息会覆盖老的消息,范围:0-2147483647
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://xxx",
          "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 下载

文档中心搜索