1. Push API v3

1.1. Push API 概述

• Push API 是所有推送接口的统称

• Push API 有多种推送目标，推送目标如下：

  • 全量推送
  • 标签推送
  • 单设备推送
  • 设备列表推送
  • 单账号推送
  • 账号列表推送

• 所有推送目标都采用相同的 URL 发起请求，URL：https://openapi.xg.qq.com/v3/push/app

• 所有请求参数通过 JSON 封装上传给后台，后台通过请求参数区分不同的推送目标

  ​

1.2. 调用地址

https://openapi.xg.qq.com/v3/push/app

1.3. Push API 必要参数

推送必要参数指一条推送消息必需携带的参数

1.3.1. audience_type：推送目标

推送目标，表示一条推送可以被推送到哪些设备

Push API 提供了多种推送目标的，比如：全量、标签、单设备、设备列表、单账号、账号列表

• 全量推送：推送给全部设备

  {
    "audience_type": "all"
  }
  

• 标签推送：推送给同时设置了"tag1"和”tag2“标签的设备

  {
    "audience_type": "tag",
    "tag_list": {
        "tags": [
            "tag1",
            "tag2"
        ],
        "op": "AND"
    }
  }
  

• 单设备推送：推送给token为"token1"的设备

  {
    "audience_type": "token",
    "token_list": [
        "token1"
    ]
  }
  

• 设备列表推送，推送给token为"token1"和"token2"的设备

  {
    "audience_type": "token_list",
    "token_list": [
        "token1",
        "token2"
    ],
    "push_id": "0"
  }
  

• 单账号推送：推送给账号为"account1"的设备

  {
    "audience_type": "account",
    "account_list": [
        "account1"
    ]
  }
  

• 账号列表推送：推送账号为"account1"和"account2"的设备

  {
    "audience_type": "account_list",
    "account_list": [
        "account1",
        "account2"
    ],
    "push_id": "0"
  }
  

1.3.2. platform：推送平台

当前支持 Android、iOS 两个平台的推送

其关键字分别为："android", "ios"

• 推送到安卓平台：

  {
    "platform": "android"
  }
  

• 推送到iOS平台：

  {
    "platform": "ios"
  }
  

1.3.3. message_type：消息体类型

针对不同平台，消息类型稍有不同，具体参照下表：

1.3.4. message：消息体

消息体，即下发到客户端的消息

Push API 对 iOS 和 Android 两个平台的消息有不同处理，需要分开来实现对应平台的推送消息，推送的消息体是 JSON格式

Android普通消息

Android平台具体字段如下表：

完整的消息示例如下：

{
    "title": "xxx",
    "content": "xxxxxxxxx",
    "xg_media_resources": "xxx1" , //此处填富媒体元素地址，例如https://www.xx.com/img/bd_logo1.png?qua=high

    "accept_time": [
        {
            "start": {
                "hour": "13",
                "min": "00"
            },
            "end": {
                "hour": "14",
                "min": "00"
            }
        },
        {
            "start": {
                "hour": "00",
                "min": "00"
            },
            "end": {
                "hour": "09",
                "min": "00"
            }
        }
    ],
    "android": {
        "n_id": 0,
        "builder_id": 0,
        "ring": 1,
        "ring_raw": "ring",
        "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版本需要大于等于3.2.3，然后在客户端的intent配置data标签，并设置scheme属性
        },
        "custom_content": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

iOS普通消息

iOS平台具体字段如下表：

完整的消息示例如下：

{
    "title": "xxx",
    "content": "xxxxxxxxx",
    "ios":{
        "aps": {
            "alert": {
                "subtitle": "my subtitle"
            },
            "badge_type": 5,
            "category": "INVITE_CATEGORY"
        },
        "custom1": "bar",
        "custom2": [
            "bang",
            "whiz"
        ],
        "xg": "oops"
    }
}

Android透传消息

透传消息，Android平台特有，即不显示在手机通知栏中的消息，可以用来实现让用户无感知的向App下发带有控制性质的消息

Android平台具体字段如下表：

具体完整示例：

{
    "title": "this is title",
    "content": "this is content",
    "android": {
       "custom_content": {
          "key1": "value1",
          "key2": "value2"
             }
    },
    "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":{
        "aps": {
            "content-available": 1
        },
        "custom": {
            "key1": "value1",
            "key2": "value2"
        },
        "xg": "oops"
    }
}

1.3.5. Push API 可选参数

Push API 可选参数是除了 audience_type、platform、message_type、message 以外，可选的高级参数

1.3.6. Push API应答参数

1.3.7. Push API 请求完整示例

Android标签推送请求消息

POST /v3/push/app HTTP/1.1
Host: openapi.xg.qq.com
Content-Type: application/json
Authorization: Basic YTViNWYwNzFmZjc3YTplYTUxMmViNzcwNGQ1ZmI1YTZhOTM3Y2FmYTcwZTc3MQ==
Cache-Control: no-cache
Postman-Token: 4b82a159-afdd-4f5c-b459-de978d845d2f
{
    "platform": "android",
    "audience_type": "tag",
    "tag_list": {
        "tags": [
            "tag1",
            "tag2"
        ],
        "op": "AND"
    },
    "message_type": "notify",
    "message": {
        "title": "this is title",
        "content": "this is content",
        "custom_content": {
            "key1": "value1",
            "key2": "value2"
        },
        "accept_time": [
            {
                "start": {
                    "hour": "13",
                    "min": "00"
                },
                "end": {
                    "hour": "14",
                    "min": "00"
                }
            }
        ]
    }
}

标签推送应答消息

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

1.3.8. iOS单设备推送请求消息

POST /v3/push/app HTTP/1.1
Host: openapi.xg.qq.com
Content-Type: application/json
Authorization: Basic ODhjNzE1Mzc1MDQ0ZDowNGM4NmNhZmI0ZTMxZDU4M2UzYjg0M2VhMDc4YTU5ZQ==
Cache-Control: no-cache
Postman-Token: 71670b5b-3149-4883-a427-d75cf9f42188

{

    "platform": "ios",
    "audience_type": "token",
    "environment":"dev",
    "token_list": [ "55c2ddba664e9abcacea7daab0887939893b18e1a2cf4475c5382f5bcb2ab25b"],
    "message_type":"notify",
    "message":{
     "title": "xxx",
    "content": "https://xg.qq.com/docs/ios_access/ios_faq.html",
    "ios":{
        "aps": {
            "alert": {
                "subtitle": "my subtitle"
            },
            "badge_type": -2,
            "sound":"Tassel.wav",
            "category": "INVITE_CATEGORY"

        },
        "custom1": "bar",
        "custom2": [
            "bang",
            "whiz"
        ],
        "xg": "oops"
    }
 }
}

单设备推送应答消息

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

1.4. 账号类型

账号类型是客户端调用SDK接口绑定，类型如下表所示：

1.5. 错误码

信鸽REST API接口较多，开发者使用过程中不可避难会遇到各种问题，这里提供了常见的错误码释义，对应着是通用基础返回值中的ret_code字段的可能值