tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
移动推送
    文档
    Download PDF

    推送接口

    最后更新时间：2023-04-19 11:28:23
    下载PDF

      接口说明

      请求方式：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 中。详情请参见 小米推送富文本消息 文档中的上传大图 API 部分
      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且应用在前台，终端用户对该条推送无感知，但有抵达数据上报
      		•

      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 参数说明

      字段名 类型 父项目 默认值 必需 参数描述
      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_type、message_type、message以外，可选的高级参数。

      参数名 类型 父项目 必需 默认值 描述
      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 取值表

      标签名称 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  
        }
    ]
}
      联系我们

      联系我们，为您的业务提供专属服务。

      联系我们
      技术支持

      如果你想寻求进一步的帮助，通过工单与我们进行联络。我们提供7x24的工单服务。

      提交工单
      7x24 电话支持
      Copyright © 2013-2023 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款