tencent cloud

文档反馈

推送接口

最后更新时间:2024-01-25 11:53:41

    接口说明

    请求方式:POST。
    服务地址/v3/push/app
    接口服务地址与服务接入点一一对应,请选择与您的应用服务接入点对应的 服务地址
    接口功能:Push API 是所有推送接口的统称。Push API 有多种推送目标,推送目标见下文。 所有请求参数通过 JSON 封装上传给后台,后台通过请求参数区分不同的推送目标。如有疑问请参见 服务端错误码
    注意:
    腾讯云移动推送结合业务优化的需求,对全量推送、标签推送和号码包推送的频率进行限制,均调整为 1条/秒,官网控制台将与 API 同步调整。
    如果超过此频率可能会引起推送异常,如相关推送需更高频率,您可以联系 在线客服

    必要参数

    推送必要参数指一条推送消息必需携带的参数。
    
    参数名
    类型
    是否必需
    描述
    audience_type
    String
    推送目标:
    all:全量推送
    tag:标签推送
    token:单设备推送
    token_list:设备列表推送
    account:单账号推送
    account_list:账号列表推送
    package_account_push:号码包推送
    package_token_push:token 文件包推送
    message
    Object
    消息体,请参见 消息体类型
    message_type
    String
    消息类型:
    notify:通知
    message:透传消息/静默消息
    environment
    String
    是(仅 iOS 平台使用)
    用户指定推送环境,仅限 iOS 平台推送使用:
    product: 推送生产环境
    dev: 推送开发环境
    注册打包的环境与推送环境需要保存一致,请参见推送环境选择说明
    upload_id
    Integer
    是(仅号码包推送\\ token 文件包推送时使用)
    号码包或 token 包的上传 ID

    audience_type:推送目标

    推送目标,表示一条推送可以被推送到哪些设备。 Push API 提供了多种推送目标的,例如全量、标签、单设备、设备列表、单账号、账号列表。
    推送目标
    描述
    必需参数及使用说明
    all
    全量推送
    tag
    标签推送
    tag_rules(推荐使用):
    标签组合推送,可设置'与'、'或'、'非'组合规则
    注意:当与 tag_list 二者共存时,tag_list 字段自动无效,参数说明请查看tag_rules 参数说明
    tag_list(后续不再更新):
    推送 tag1 和 tag2 的设备{"tags":["tag1","tag2"],"op":"AND"}
    推送 tag1 或 tag2 的设备{"tags":["tag1","tag2"],"op":"OR"}
    标签列表不能超过512个字符
    token
    单设备推送
    token_list
    如果该参数包含多个 token 只会推送第一个 token
    格式 eg:[“token1”]
    token 字符串长度不能超过36
    token_list
    设备列表群推
    token_list
    最多1000个 token
    格式 eg:["token1","token2"]
    token 字符串长度不能超过36
    注意:若列表超过1000个 token,推送会失败,如需推送更大批量 token,建议您使用上传 Token 包推送
    account
    单账号推送
    account_list
    该参数有多个账号时,仅推送第一个账号
    格式 eg:["account1"]
    account_list
    账号列表群推
    account_list
    最多1000个 account
    格式 eg:["account1","account2"]
    注意:若列表超过1000个 account,推送会失败,如需推送更大批量 account,建议您使用号码包推送
    package_account_push
    号码包推送
    上传号码包推送必填
    package_token_push
    token 文件包推送
    上传 token 文件包推送必填
    全量推送:推送给全部设备。
    {
    "audience_type": "all"
    }
    标签推送(tag_rules 方式):广东和湖南,并且是20200408当天活跃过的男性用户。
    {
    "audience_type": "tag",
    "tag_rules": [
    {
    "tag_items": [
    {
    "tags": [
    "guangdong",
    "hunan"
    ],
    "is_not": false,
    "tags_operator": "OR",
    "items_operator": "OR",
    "tag_type": "xg_auto_province"
    },
    {
    "tags": [
    "20200408"
    ],
    "is_not": false,
    "tags_operator": "OR",
    "items_operator": "AND",
    "tag_type": "xg_auto_active"
    },
    {
    "tags": [
    "male"
    ],
    "is_not": false,
    "tags_operator": "OR",
    "items_operator": "AND",
    "tag_type": "xg_user_define"
    }
    ],
    "operator": "OR",
    "is_not": false
    }
    ]
    }
    单设备推送:推送给 token 为 token1 的设备。
    {
    "audience_type": "token",
    "token_list": [
    "token1"
    ]
    }
    设备列表推送,推送给 token 为 token1 和 token2 的设备。
    {
    "audience_type": "token_list",
    "token_list": [
    "token1",
    "token2"
    ]
    }
    单账号推送:推送给账号为 account1 的设备。
    {
    "audience_type": "account",
    "account_list": [
    "account1"
    ]
    }
    账号列表推送:推送账号为 account1 和 account2 的设备。
    {
    "audience_type": "account_list",
    "account_list": [
    "account1",
    "account2"
    ]
    }

    message_type:消息类型

    针对不同平台,消息类型稍有不同,具体参照下表:
    消息类型
    描述
    支持平台
    特性说明
    notify
    通知栏消息
    Android & iOS
    通知栏展示消息
    注意:该字段与 content-available: 1 互斥,请勿同时使用。
    message
    透传消息/静默消息
    Android(透传消息)
    iOS(静默消息)
    通知栏不展示消息。
    注意:因厂商限制,Android 透传消息只通过移动推送自建通道下发,无法通过厂商通道下发

    message:消息体

    消息体,即下发到客户端的消息。 Push API 对 iOS 和 Android 两个平台的消息有不同处理,需要分开来实现对应平台的推送消息,推送的消息体是 JSON 格式。

    Android 普通消息

    Android 平台具体字段如下表:
    字段名
    类型
    父项目
    默认值
    必需
    参数描述
    title
    String
    message
    消息标题
    content
    String
    message
    消息内容
    accept_time
    Array
    message
    消息将在哪些时间段允许推送给用户。
    单个元素由 "start" 和 "end" 组成的起止时间对组成
    "start" 和 "end" 由 hour (小时)和 min(分钟)描述对应时刻,详细参考具体示例。
    注意:因厂商限制, 仅对移动推送自建通道有效
    thread_id
    String
    message
    通知分组折叠的组别识别名
    注意:因厂商限制, 仅对移动推送自建通道有效
    thread_sumtext
    String
    message
    通知分组折叠后显示的摘要,thread_id 非空时有效
    注意:因厂商限制, 仅对移动推送自建通道有效
    xg_media_resources
    String
    message
    通知栏大图片 url 地址,仅对移动推送自建通道和小米通道生效;
    注意:如需使用小米通道大图通知功能,需先调用小米图片上传接口上传图片文件,获取小米指定的图片地址 pic_url ,再填入移动推送推送对应的参数 xg_media_resources 中。
    xg_media_audio_resources
    String
    message
    音频富媒体元素地址。
    支持 mp3 格式音频,建议大小在5MB以内。
    注意:仅移动推送自建通道支持该参数下发,其他通道不下发该参数
    android
    Object
    message
    安卓通知高级设置结构体,请参见 Android 结构体说明

    Android 结构体说明

    字段名
    类型
    父项目
    默认值
    必需
    参数描述
    n_ch_id
    String
    android
    通知渠道 ID(仅移动推送自建通道生效),请参见 创建通知渠道
    n_ch_name
    String
    android
    通知渠道名称(仅移动推送自建通道生效) ,请参见 创建通知渠道
    xm_ch_id
    String
    android
    小米渠道 ID(仅小米推送通道生效)
    fcm_ch_id
    String
    android
    FCM 渠道 ID(仅 FCM 推送通道生效)
    hw_biz_type
    Integer
    android
    0
    是否开启华为快通知:
    1:开启
    0:关闭
    注意:仅华为通道有效,其需要联系华为商务开通。
    hw_ch_id
    String
    android
    华为渠道 ID(仅 华为推送通道生效)
    hw_category
    String
    android
    华为消息类型标识,确定消息提醒方式,对特定类型消息加快发送,参数详情请参见 华为的请求参数说明 的 category 参数。
    IM:即时聊天
    VOIP:音视频通话
    SUBSCRIPTION:订阅
    
    hw_importance
    
    Integer
    android
    消息的提醒级别,取值如下:
    1:表示通知栏消息预期的提醒方式为静默提醒,消息到达手机后,无铃声震动
    2:表示通知栏消息预期的提醒方式为强提醒,消息到达手机后,以铃声、震动提醒用户。终端设备实际消息提醒方式将根据 hw_category 字段取值或者 智能分类 结果进行调整。
    oppo_ch_id
    String
    android
    OPPO渠道 ID(仅 OPPO 推送通道生效)
    vivo_ch_id
    String
    android
    0
    vivo 渠道 ID:“0”代表运营消息,“1”代表系统消息(仅 vivo 推送通道生效)
    n_id
    Integer
    android
    0
    (该字段已废弃,后续会下线,如需使用覆盖功能请使用覆盖参数:collapse_id) 通知消息对象的唯一标识(移动推送自建通道) (1)大于0:会覆盖先前相同 id 的消息 (2)等于0:展示本条通知且不影响其他消息 (3)等于-1:将清除先前所有消息,仅展示本条消息
    builder_id
    Integer
    android
    0
    本地通知样式标识
    badge_type
    Integer
    android
    -1
    通知角标:
    -2:自动增加1,支持华为设备
    -1:不变,支持华为、vivo 设备
    [0, 100):直接设置,支持华为、vivo 设备
    注意:不同厂商设备的角标适配能力不同,各参数值实现效果请参见角标适配指南
    ring
    Integer
    android
    1
    是否有铃声:
    0:没有铃声
    1:有铃声
    ring_raw
    String
    android
    指定 Android 工程里 raw 目录中的铃声文件名,不需要后缀名。 说明:自定义铃声仅华为、小米、FCM 和移动推送自建通道支持,需配合n_ch_id字段使用,配置步骤可参考 如何设置自定义铃声
    vibrate
    Integer
    android
    1
    是否使用震动:
    0:没有震动
    1:有震动
    lights
    Integer
    android
    1
    是否使用呼吸灯:
    0:不使用呼吸灯
    1:使用呼吸灯
    clearable
    Integer
    android
    1
    通知栏是否可清除
    icon_type
    Integer
    android
    0
    指定通知栏缩略图显示的是应用内图标还是网络资源图标 :
    0:应用内图标,仅对移动推送自建通道有效
    1:网络资源图标,仅移动推送自建通道、FCM、华为、荣耀通道支持
    icon_res
    String
    android
    指定通知栏缩略图的具体图片资源 :
    当 icon_type = 0:填写 Android 应用内的图片资源文件名称(不带文件后缀),仅对移动推送自建通道有效
    当前 icon_type = 1:填写缩略图 url 地址,缩略图格式要求可参见 富媒体通知文档,仅移动推送自建通道、FCM、华为、荣耀通道支持
    style_id
    Integer
    android
    1
    设置是否覆盖指定编号的通知样式
    small_icon
    String
    android
    消息在状态栏显示的图标,若不设置,则显示应用图标
    icon_color
    Integer
    android
    0
    通知栏小图标染色
    仅移动推送自建通道有效
    需要使用 RGB 颜色的十进制值,例如 RGB 颜色 #01e240,请填入123456
    action
    Object
    android
    设置点击通知栏之后的行为,默认为打开 App,详情参考 action 参数说明
    custom_content
    String
    android
    用户自定义的参数(需要序列化为 JSON String)获取方式详见通知点击跳转-客户端获取参数
    说明:
    华为官方通知:「2021年9月30日起停用V2协议」。移动推送已将华为推送协议升级到V5,V5协议不支持通过【附加参数】字段携带自定义参数。如果您集成了华为厂商通道,建议您改用 Intent 方式携带自定义参数,否则将导致自定义参数不能成功通过华为推送通道下发。
    
    show_type
    Integer
    android
    2
    应用前台时,是否展示通知 。 默认展示,仅对移动推送自建通道、FCM 通道有效
    1:不展示
    2:展示
    说明:若取值为1且应用在前台,终端用户对该条推送无感知,但有抵达数据上报
    说明:
    华为官方通知:「2021年9月30日起停用V2协议」。移动推送已将华为推送协议升级到V5,V5协议不支持通过【附加参数】字段携带自定义参数。如果您集成了华为厂商通道,建议您改用 Intent 方式携带自定义参数,否则将导致自定义参数不能成功通过华为推送通道下发。
    
    action
    参数说明
    字段名
    类型
    父项目
    默认值
    必需
    参数描述
    action_type
    Integer
    action
    1
    点击动作类型,
    1:打开 activity 或 App 本身
    2:打开浏览器
    3:打开 App 自定义页面(推荐使用,参考 使用 Intent 方式跳转指引
    activity
    String
    action
    action_type 为1,且需要打开 activity 时必选
    activity 完整名称,例如 com.x.y.PushActivity
    aty_attr
    Object
    action
    action_type 为1,且需要打开 activity 时可选
    activity 属性
    if:Intent 的 Flag 属性,类型为 Integer
    pf:PendingIntent 的 Flag 属性,类型为 Integer
    browser
    Object
    action
    action_type 为2时必选
    打开浏览器操作,
    url:网页地址,仅支持 http、https,类型为 String
    confirm:是否需要用户确认,类型为 Integer
    (1)1:需要确认
    (2)0:不需要确认
    intent
    String
    action
    action_type 为3时必选
    自定义 scheme,例如 xgscheme://com.tpns.push/notify_detail
    完整的消息示例如下:
    {
    "title": "xxx",
    "content": "xxxxxxxxx",
    "xg_media_resources": "xxx" , //此处填富媒体元素地址,例如https://www.xx.com/img/bd_logo1.png?qua=high
    "xg_media_audio_resources":"xxx", //此处填音频富媒体元素地址,例如http://sc1.111ttt.cn/2018/1/03/13/396131227447.mp3
    "thread_id":"活动_id",
    "thread_sumtext":"运营活动",
    "accept_time": [
    {
    "start": {//时间段起始时间,
    "hour": "13",//起始时间 小时值, 取值 [0:24)
    "min": "00"// 起始时间 分钟值, 取值[0:60)
    },
    "end": {//时间段结束时间
    "hour": "14",//结束时间 小时值, 取值 [0:24)
    "min": "00" //结束时间 分钟值,取值[0:60)
    
    }
    },
    {
    "start": {
    "hour": "00",
    "min": "00"
    },
    "end": {
    "hour": "09",
    "min": "00"
    }
    }
    ],
    "android": {
    "n_ch_id": "default_message",
    "n_ch_name": "默认通知",
    "n_id": 0,
    "builder_id": 0,
    "ring": 1,
    "ring_raw": "ring",
    "badge_type":-1,
    "vibrate": 1,
    "lights": 1,
    "clearable": 1,
    "icon_type": 0,
    "icon_res": "xg",
    "style_id": 1,
    "small_icon": "xg",
    "action": {
    "action_type": 1,// 动作类型,1,打开activity或app本身;2,打开浏览器;3,打开Intent
    "activity": "com.x.y.PushActivity",
    "aty_attr": {// activity属性,只针对action_type=1的情况
    "if": 0, // Intent的Flag属性
    "pf": 0 // PendingIntent的Flag属性
    },
    "browser": {
    "url": "https://cloud.tencent.com ", // 仅支持http、https
    "confirm": 1 // 是否需要用户确认
    },
    "intent": "xgscheme://com.tpns.push/notify_detail" //SDK版本需要大于等于1.0.9,然后在客户端的intent配置data标签,并设置scheme属性
    },
    "custom_content":"{\\"key\\":\\"value\\"}"
    }
    }

    iOS 通知消息

    iOS 平台具体字段如下表:
    字段名
    类型
    父项目
    默认值
    必需
    参数描述
    title
    String
    message
    消息标题,此字段会覆盖 alert 下的 title 中的内容。
    content
    String
    message
    消息内容,此字段会覆盖 alert 下的 body 中的内容。
    thread_id
    String
    message
    通知分组折叠的组别识别名
    ios
    Object
    message
    iOS 消息结构体,请参见 iOS 字段说明
    show_type
    Integer
    message
    2
    应用前台时,是否展示通知 。
    1:不展示
    2:展示
    说明:若取值为1且应用在前台,终端用户对该条推送无感知,但有抵达数据上报
    xg_media_resources
    String
    message
    图片、音视频富媒体元素 url 地址,详情请参见 富媒体通知

    iOS 字段说明

    字段名
    类型
    父项目
    默认值
    必需
    参数描述
    aps
    Object
    ios
    苹果推送服务(APNs)特有的消息体字段,请参见 aps 参数说明,其他详细介绍请参见官网 Payload
    custom_content
    String
    ios
    自定义下发的参数,需要序列化为 json string
    aps 参数说明
    
    aps 参数说明
    字段名
    类型
    父项目
    默认值
    必需
    参数描述
    alert
    Object
    aps
    包含标题和消息内容
    badge_type
    Integer
    aps
    用户设置角标数字:
    -1:角标数字不变
    -2:角标数字自动加1
    >=0:设置自定义角标数字
    category
    String
    aps
    下拉消息时显示的操作标识
    mutable-content
    Integer
    aps
    1
    通知拓展参数。
    推送的时候携带 "mutable-content":1,说明是支持 iOS 10 的 Service Extension
    开启后,推送详情中会有抵达数据上报,使用该功能前请按照 通知服务扩展的使用说明 实现 Service Extension 接口,如果不携带此字段则没有抵达数据上报
    sound
    String
    aps
    sound 字段使用情况如下:
    播放系统默认提示音,"sound":"default"
    播放本地自定义铃声,"sound":"chime.aiff"
    静音效果,"sound":"" 或者是去除 sound 字段。
    自定义铃声说明:格式必须是 Linear PCM、MA4(IMA/ADPCM)、alaw,μLaw 的一种,将声频文件放到项目 bundle 目录中,且时长要求30s以下,否则就是系统默认的铃声。
    interruption-level
    String
    aps
    active
    仅对 iOS 15 以后的设备生效,需要在Capability 中打开Time Sensitive Notifications选项,有4个值可以选择设置:
    passive:被动通知,即并不需要及时关注的通知。
    active:主动通知,默认的通知。
    time-sensitive:时效性通知,需要人们立刻注意的通知。
    critical:重要通知,需要立刻关注的通知。
    完整的消息示例如下:
    {
    "title": "xxx",
    "content": "xxxxxxxxx",
    "thread_id":"活动_id",
    "xg_media_resources":"https://www.xx.com/img/bd_logo1.png",
    "show_type":1,
    "ios":{
    "aps": {
    "alert": {
    "subtitle": "my subtitle"
    },
    "badge_type": 5,
    "category": "INVITE_CATEGORY",
    "sound":"default",
    "interruption-level":"time-sensitive",
    "mutable-content":1
    },
    "custom_content":"{\\"key\\":\\"value\\"}"
    }
    }

    Android 透传消息

    透传消息,Android 平台特有,即不显示在手机通知栏中的消息,可以用来实现让用户无感知的向 App 下发带有控制性质的消息。
    注意:
    因厂商限制,Android 透传消息只通过移动推送自建通道下发,无法通过厂商通道下发。
    Android 平台具体字段如下表:
    字段名
    类型
    父项目
    默认值
    是否必需
    参数描述
    title
    String
    message
    命令描述
    content
    String
    message
    命令内容
    android
    Object
    message
    安卓消息结构体
    accept_time
    Array
    message
    消息将在哪些时间段允许推送给用户。
    单个元素由 "start" 和 "end" 组成的起止时间对组成。
    "start" 和 "end" 由 hour (小时)和 min(分钟)描述对应时刻,详细参考具体示例。
    注意:因厂商限制, 仅对移动推送自建通道有效。
    custom_content
    String
    android
    需要序列化为 json string
    具体完整示例:
    {
    "title": "this is title",
    "content": "this is content",
    "android": {
    "custom_content":"{\\"key\\":\\"value\\"}"
    },
    "accept_time": [
    {
    "start": {
    "hour": "13",
    "min": "00"
    },
    "end": {
    "hour": "14",
    "min": "00"
    }
    },
    {
    "start": {
    "hour": "00",
    "min": "00"
    },
    "end": {
    "hour": "09",
    "min": "00"
    }
    }
    ]
    }

    iOS 静默消息

    静默消息,iOS 平台特有,类似 Android 中的透传消息,消息不展示,当静默消息到达终端时,iOS 会在后台唤醒 App 一段时间(小于30s),让 App 来处理消息逻辑。
    具体字段如下表:
    字段名
    类型
    父项目
    默认值
    是否必要
    参数描述
    ios
    Object
    message
    ios 消息结构体
    aps
    Object
    ios
    苹果推送服务(APNs)特有的,其中最重要的键值对如下:
    content-available:标识消息类型(必须为1),类型为 Integer
    不能包含 alert、sound、badge_type 字段,详细介绍请参见 Payload
    注意:content-available: 1与message_type:"notify"字段互斥,请勿同时使用
    custom_content
    String
    ios
    需要序列化为 json string
    具体完整示例:
    {
    "ios":{
    "aps": {
    "content-available": 1
    },
    "custom_content":"{\\"key\\":\\"value\\"}"
    }
    }

    可选参数

    Push API 可选参数是除了audience_typemessage_typemessage以外,可选的高级参数。
    参数名
    类型
    父项目
    必需
    默认值
    描述
    expire_time
    Integer
    86400(24小时)
    消息离线存储时间(单位为秒),最长72小时
    若 expire_time = 0,则表示实时消息
    若 expire_time 大于0,且小于800s,则系统会重置为800s
    若expire_time >= 800s,按实际设置时间存储,最长72小时
    设置的最大值不得超过259200,否则会导致推送失败
    如需调整离线消息时间,请联系 在线客服 申请
    send_time
    String
    当前系统时间
    指定推送时间,可选择未来90天内的时间:
    格式为 yyyy-MM-DD HH:MM:SS
    若小于服务器当前时间,则会立即推送
    仅全量推送、号码包推送和标签推送支持此字段
    multi_pkg
    Boolean
    false
    多包名推送:当 App 存在多个渠道包(例如应用宝、豌豆荚等),并期望推送时所有渠道的 App 都能收到消息,可将该值设置为 true。 注意:该参数默认控制移动推送自建通道的多包名推送,需要实现厂商通道多包名推送详见 厂商通道多包名配置 文档
    loop_param
    Object
    0
    仅全量推送、号码包推送和标签推送支持此字段,详情见下文 loop_param 参数说明
    group_id
    String
    tpns_yyyymmdd,yyyymmdd 代表推送日期
    该字段已废弃,后续会下线,若需要使用聚合统计请使用推送计划字段:plan_id
    plan_id
    String
    推送计划 ID,推送计划创建及使用方式可 参考文档
    tag_rules
    Array
    仅标签推送必需
    标签组合推送,可设置'与'、'或'、'非'组合规则
    注意:当与 tag_list 二者共存时,tag_list 字段自动无效,参数说明请查看 tag_rules 参数说明
    account_list
    Array
    单账号推送、账号列表推送时必需
    若单账号推送:
    要求 audience_type = account
    参数格式:[ "account1" ]
    若账号列表推送:
    参数格式:["account1","account2"]
    最多1000 个 account
    account_push_type
    Integer
    账号推送时可选
    0
    0:往账号的最新的 device 上推送信息
    1:往账号关联的所有 device 设备上推送信息
    account_type
    Integer
    0
    账号类型,需要与推送的账号所属类型一致,取值可参考 账号类型取值表
    token_list
    Array
    单设备推送、设备列表推送时必需
    若单设备推送:
    要求 audience_type=token
    参数格式:[ "token1" ]
    若设备列表推送:
    参数格式:[ "token1","token2" ]
    最多1000个 token
    ignore_invalid_token
    int
    0
    0:代表如果有无效的token则这个接口调用失败
    1:代表忽略无效的token继续进行下发
    注意:仅对 token 列表推送和单 token 推送有效
    push_speed
    Integer
    推送限速设置每秒 X 条,X 取值参数范围1000 - 50000
    仅全量推送、号码包推送和标签推送有效
    collapse_id
    Integer
    系统默认分配一个 collapse_id
    消息覆盖参数,在前一条推送任务已经调度下发后,如果第二条推送任务携带相同的 collapse_id 则会停止前一条推送中尚未下发的移动推送自建通道数据,同时会覆盖展示第一条推送任务的消息。
    已完成任务的 collapse_id 可以通过 单个任务推送信息查询接口 获取。
    目前仅支持全推、标签推送、号码包推送。
    channel_rules
    Array
    推送通道选择策略。
    可自定义该条推送允许通过哪些通道下发,默认允许通过所有通道下发,详细推送策略参考 通道策略
    channel_rules 数组单元素数据结构见下 channel_rules 参数说明
    tpns_online_push_type
    Integer
    0
    在线设备是否通过移动推送自建通道下发:
    0:默认在线走移动推送自建通道下发
    1:在线不优先走移动推送自建通道下发
    force_collapse
    Boolean
    false
    对于不支持消息覆盖的 OPPO 、vivo 通道的设备,是否进行消息下发。
    false:不下发消息
    true:下发消息
    说明:
    对于 collapse_id,有以下使用条件:
    暂不支持用户自定义此参数,需要移动推送生成的 collapse_id。
    目前仅支持移动推送自建通道、APNS 通道、小米通道、魅族通道以及华为系统版本 EMUI10 及以上的设备。
    对于华为通道,覆盖消息时携带自定义参数需要使用 intent 方式,如使用 custom_content 方式携带自定义参数,接口层会进行拦截。
    目前 OPPO 通道 vivo 通道不支持覆盖消息。当新创建覆盖消息时可通过 force_collapse 字段设置为 false 来关闭 vivo、OPPO 通道的下发。

    tag_rules 参数说明

    字段
    类型
    父项目
    必填
    描述
    tag_items
    Array
    tag_rules
    标签规则,参见 tag_items 说明
    operator
    String
    tag_rules
    tag_rules 数组内各元素的运算符,第一个 tag_rules 元素的 operator 为无效数据,第二个 tag_rules 元素的 operator 作为第一个和第二个 tag_rules 元素之间的运算符。
    OR: 或运算
    AND:且运算
    is_not
    Boolean
    tag_rules
    是否对 tag_items 数组的运算结果进行非运算。
    true:进行非运算
    false:不进行非运算。

    tag_items 说明

    字段
    类型
    父项目
    必填
    描述
    tags
    Array
    tag_items
    具体标签值,类型:string,如 tag1,guangdong 等。
    is_not
    Boolean
    tag_items
    是否对 tag 数组的运算结果进行非运算。
    true:非运算
    false:不进行非运算
    tags_operator
    String
    tag_items
    tags 内标签对应的运算符。
    OR:或运算
    AND:且运算。
    items_operator
    String
    tag_items
    tag_items 数组内各元素的运算符,第一个 tag_items 元素的 items_operator 为无效数据,第二个 tag_items 元素的 items_operator 作为第一个和第二个 tag_items 元素之间的运算符。
    OR :或运算
    AND :且运算
    注意:不同规则之间运算符逻辑优先级「AND」>「OR」
    tag_type
    String
    tag_items

    tag_type 取值表

    标签名称
    tag_type 取值
    标签名举例
    自定义标签
    xg_user_define
    tag1,tag2 等
    App版本
    xg_auto_version
    1.1.0,1.2.0.1等
    设备省份信息
    xg_auto_province
    guangdong,shanghai 等
    活跃信息
    xg_auto_active
    20200131,20200201等
    XG SDK版本
    xg_auto_sdkversion
    1.1.5.2,1.1.5.3等
    系统语言
    xg_auto_systemlanguage
    zh,en 等
    手机品牌
    xg_auto_devicebrand
    Xiaomi,vivo 等
    手机机型
    xg_auto_deviceversion
    MI 9 SE,vivo X9Plus 等
    国家
    xg_auto_country
    CN,SG 等
    说明:
    详细使用方法可参见 标签推送示例

    channel_rules 参数说明

    字段名
    类型
    父项目
    是否必填
    参数说明
    channel
    String
    channel_rules
    下发推送通道。
    xg:自建通道
    hw:华为通道
    xm:小米通道
    mz:魅族通道
    vivo:vivo 通道
    oppo:OPPO 通道
    apns:APNs 通道
    honor:荣耀通道
    fcm:FCM通道
    disable
    Boolean
    channel_rules
    是否关闭 channel 中对应的通道, 默认打开通道。
    true:关闭
    false:打开

    loop_param 参数说明

    字段名
    类型
    父项目
    是否必填
    注释
    startDate
    String
    loop_param
    循环区间开始日期,可选择未来90天内的时间。格式 YYYY-MM-DD,例如2019-07-01
    endDate
    String
    loop_param
    循环区间截止日期,可选择未来90天内的时间。格式 YYYY-MM-DD,例如2019-07-07
    loopType
    Integer
    loop_param
    循环类型
    天: 1
    周: 2
    月: 3
    loopDayIndexs
    Array
    loop_param
    按天循环:填写[0],表示每天的任务,按周循环:填周几[0-6],如[0, 1, 2]表示每周的星期天,周一,周二进行推送,按月循环:填写日期,如[1,10,20],每个月1,10,20号
    dayTimes
    Array
    loop_param
    具体推送时间,格式 HH:MM:SS,例如["19:00:00", "20:00:00"],表示每天的19点,20点进行推送

    应答参数

    字段名
    类型
    注释
    seq
    Integer
    与请求包一致(如果请求包无该字段,则该字段返回为0)
    push_id
    String
    推送 ID 注意:如果您是循环推送类型,则会返回多个 pushid 放在一个数组类型里
    invalid_targe_list
    Array
    仅对 token 列表推送和单 token 推送 且 ignore_invalid_token 值为1时返回,该字段会存储被过滤的无效 token ,有效 token 会正常下发
    ret_code
    Integer
    错误码,详细参照错误码对照表
    environment
    String
    用户指定推送环境,仅支持 iOS
    product: 生产环境
    dev: 开发环境
    err_msg
    String
    请求出错时的错误信息
    result
    String
    请求正确时
    若有额外数据要返回,则结果封装在该字段的 json 中
    若无额外数据,则可能无此字段

    示例说明

    Android 账号推送请求消息

    {
    "audience_type": "account",
    "account_list": [
    "account1"
    ],
    "multi_pkg":true,
    "push_speed":50000,
    "channel_rules": [
    {
    "channel": "mz",
    "disable": true
    },
    {
    "channel": "xm",
    "disable": false
    }
    ],
    "message_type": "notify",
    "message": {
    "title": "测试标题",
    "content": "测试内容",
    "xg_media_resources": "xxx1" , //此处填富媒体元素地址,例如https://www.xx.com/img/bd_logo1.png?qua=high
    "xg_media_audio_resources":"xxx", //此处填音频富媒体元素地址,例如http://sc1.111ttt.cn/2018/1/03/13/396131227447.mp3
    "accept_time": [
    {
    "start": {//时间段起始时间,
    "hour": "13",//起始时间 小时值, 取值 [0:24)
    "min": "00"// 起始时间 分钟值, 取值[0:60)
    },
    "end": {//时间段结束时间
    "hour": "14",//结束时间 小时值, 取值 [0:24)
    "min": "00" //结束时间 分钟值,取值[0:60)
    
    }
    },
    {
    "start": {
    "hour": "00",
    "min": "00"
    },
    "end": {
    "hour": "09",
    "min": "00"
    }
    }
    ],
    "android": {
    "n_ch_id": "default_message",
    "n_ch_name": "默认通知",
    "n_id": 0,
    "builder_id": 0,
    "ring": 1,
    "ring_raw": "ring",
    "badge_type":-1,
    "vibrate": 1,
    "lights": 1,
    "clearable": 1,
    "icon_type": 0,
    "icon_res": "xg",
    "style_id": 1,
    "small_icon": "xg",
    "action": {
    "action_type": 1,// 动作类型,1,打开 activity 或 app 本身;2,打开浏览器;3,打开 Intent
    "activity": "xxx",
    "aty_attr": {// activity属性,只针对action_type=1的情况
    "if": 0, // Intent的Flag属性
    "pf": 0 // PendingIntent的Flag属性
    },
    "browser": {
    "url": "xxxx ", // 仅支持http、https
    "confirm": 1 // 是否需要用户确认
    },
    "intent": "xxx" //SDK版本需要大于等于1.0.9,然后在客户端的intent配置data标签,并设置scheme属性
    },
    "custom_content":"{\\"key\\":\\"value\\"}"
    }
    }
    }

    账号推送应答消息

    {
    "seq": 0,
    "environment": "product",
    "ret_code": 0,
    "push_id": "3895624686"
    }

    iOS 单设备推送请求消息

    {
    "audience_type": "token",
    "environment":"dev",
    "token_list": [ "05da87c0ae********fa9e08d884aada5bb2"],
    "message_type":"notify",
    "message":{
    "title": "推送标题",
    "content": "推送内容",
    "ios":{
    "aps": {
    "alert": {
    "subtitle": "推送副标题"
    },
    "badge_type": -2,
    "sound":"Tassel.wav",
    "category": "INVITE_CATEGORY"
    
    },
    "custom_content":"{\\"key\\":\\"value\\"}"
    }
    }
    }

    单设备推送应答消息

    {
    "seq": 0,
    "push_id": "427184209",
    "ret_code": 0,
    "environment": "dev",
    "err_msg": "",
    "result": "[0]"
    }

    标签推送场景(tag_rules 方式)

    场景一:广东和湖南,并且是20200408当天活跃过的男性用户 表达式:(xg_auto_province.guangdong 或 xg_auto_province.hunan)与 xg_auto_active.20200408 与 xg_user_define.male
    {
    "audience_type": "tag",
    "tag_rules": [
    {
    "tag_items": [
    {
    "tags": [
    "guangdong",
    "hunan"
    ],
    "is_not": false, //是否对tags内标签计算的结果进行非运算,true-进行非运算,false-不进行非运算
    "tags_operator": "OR", //tags内标签对应的运算符
    "items_operator": "OR", //tag_items内各元素的运算符,第一个元素的items_operator为无效数据,第二个元素的items_operator作为第一个和第二个元素之前的运算符,以此类推
    "tag_type": "xg_auto_province" //tags内标签对应的标签类型
    },
    {
    "tags": [
    "20200408"
    ],
    "is_not": false,
    "tags_operator": "OR",
    "items_operator": "AND",
    "tag_type": "xg_auto_active"
    },
    {
    "tags": [
    "male"
    ],
    "is_not": false,
    "tags_operator": "OR",
    "items_operator": "AND",
    "tag_type": "xg_user_define"
    }
    ],
    "operator": "OR",
    "is_not": false
    }
    ]
    }
    场景二:近3天活跃,并且 App 版本不为1.0.2的华为用户 表达式:(xg_auto_active.20200406 或 xg_auto_active.20200407 或 xg_auto_active.20200408)与 (非 xg_auto_version.1.0.2) 与 xg_auto_devicebrand.huawei
    {
    "audience_type": "tag",
    "tag_rules": [
    {
    "tag_items": [
    {
    "tags": [
    "20200406",
    "20200407",
    "20200408"
    ],
    "is_not": false, //是否对tags内标签计算的结果进行非运算,true-进行非运算,false-不进行非运算
    "tags_operator": "OR", //tags内标签对应的运算符
    "items_operator": "OR", //tag_items内各元素的运算符,第一个元素的items_operator为无效数据,第二个元素的items_operator作为第一个和第二个元素之前的运算符,以此类推
    "tag_type": "xg_auto_active" //tags内标签对应的标签类型
    },
    {
    "tags": [
    "1.0.2"
    ],
    "is_not": true,
    "tags_operator": "OR",
    "items_operator": "AND",
    "tag_type": "xg_auto_verison"
    },
    {
    "tags": [
    "huawei"
    ],
    "is_not": false,
    "tags_operator": "OR",
    "items_operator": "AND",
    "tag_type": "xg_auto_devicebrand"
    }
    ],
    "operator": "OR",
    "is_not": false
    }
    ]
    }