> For the complete documentation index, see [llms.txt](https://growingio.gitbook.io/mp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://growingio.gitbook.io/mp/developers/open-api/push-api.md).

# 推送API

## 1. 概述

为满足广大客户更灵活创建推送的诉求，GrowingIO 提供了一套创建推送的API。本文档旨在说明一些调用流程，逻辑及相关接口说明。

## 2. 认证

为保证数据安全，GrowingIO所有的API服务，请求Head中需要携带 Token。

Token 获取详见：[“GrowingIO接口认证”](https://docs.growingio.com/v3/product-manual/projectmange/projectmange/api-token)

## 3. 使用注意

1. 接口调用频率限制：单个 Token 调用限制 1200次/分钟。
2. 推送单条最大目标数限制：单次调用接口 audience 列表长度限制 2000 条。
3. 接口地址中的project\_uid就是项目ＵID，指的是访问项目的时候，页面 URL 以 /projects/:project\_uid 开头，例如 [https://www.growingio.c](https://www.growingio.com/admin/projects/nxog09md/dashboard)[o](https://www.growingio.com/admin/projects/nxog09md/dashboard)[m/admin/p](https://www.growingio.com/admin/projects/nxog09md/dashboard)[rojects/nxo](https://www.growingio.com/admin/projects/nxog09md/dashboard)[g0](https://www.growingio.com/admin/projects/nxog09md/dashboard)[9md/dashboard](https://www.growingio.com/admin/projects/nxog09md/dashboard) 中的 "nxog09mx"。
4. 接口参数中productId的获取方式：访问官网进入到推送的应用配置页面，点击目标推送应用的详细配置，浏览器地址栏的URL类似这样：[https://www.growingio.com/projects/nxog09md/marketing-automation/manage/product/configuration/QPDM8loN](https://www.growingio.com/projects/nxog09md/mp/marketing-automation/manage/product/configuration/QPDM8loN)，最后面的"QPDM8loN"就是productId。

## 4. 接口说明

地址：POST    <https://www.growingio.com/api/v1/projects/:project\\_id/meta/marketing\\_push>

**请求头(http header)：**

| 字段名           | 是否必传 | 说明                                | 示例                                                                     |
| ------------- | ---- | --------------------------------- | ---------------------------------------------------------------------- |
| Content-Type  | 是    | 固定传json类型                         | application/json                                                       |
| X-Client-Id   | 是    | 项目公钥，参考上面认证部分的文档                  | 06b3f5ec564f590eb7435a8940c4f431                                       |
| Authorization | 是    | Token+空格+真正的token，获取方式参考上面认证部分的文档 | Token J8GL8w3gXUyZGMlEhme3acaCJKAHryzASR1WuHu2DrbUOS89HzaDdHIjCbizdgS8 |

**请求对象：**

| 字段名          | 字段格式  | 是否必传 | 说明                                                                                                                  | 限制          | 示例                                   |
| ------------ | ----- | ---- | ------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------ |
| cid          | 字符串   | 是    | cid 用于标示同一批推送消息。cid 相同的推送消息会聚合到同一个消息记录里，便于后续查看数据。同一个cid，同样的请求参数推送服务器不会生成新的推送任务，用于防止 api 调用端重试造成服务端的重复推送。建议使用 UUID 。 | 长度不超过64个字符  | 61b757af-f877-4e15-84f2-0f0eef69277c |
| name         | 字符串   | 是    | 推送名称。建议使用 业务含义名称 + 时间戳 ，不可重复，便于在管理后台查看使用。                                                                           | 长度不超过200个字符 | 用户召回推送20190716170520                 |
| packageName  | 字符串   | 是    | 推送应用包名。可以在应用管理后台获取，注意 sdk 上传的包名需要和后台配置的一致！                                                                          |             | com.growingio.PushTest               |
| productId    | 字符串   | 是    | 推送应用唯一标示，因为packageName苹果和安卓可能重复，使用productId能唯一标识出一个应用                                                               |             | QPDM8loN                             |
| audience     | 字符串数组 | 是    | 推送目标列表。                                                                                                             |             | 登录用户ID。一次推送最多 2000 个。                |
| notification | 对象    | 是    | 推送消息体。                                                                                                              |             | -                                    |
| options      | 对象    | 是    | 推送配置项。                                                                                                              |             | -                                    |

**使用建议：**

* 推送目标放在audience字段里，填入接入方系统里的登录用户ID，登录用户ID的含义可以参考这个文档：<https://docs.growingio.com/v3/introduction/datamodel/usermodel/loginuser>。再重申一下，就是接入SDK时上报的ID，理论上这个ID应该存储于接入方系统的数据库中。
* 推送目标用户如果小于等于2000个，可以将所有目标设备标识放到一个请求里批量推送，推送完成之后建议更换cid和消息内容再进行下次推送。
* 推送目标用户如果大于2000个，需要分批推送，每批目标设备标识个数小于等于2000，保证这些批次的cid相同和消息体内容相同，这样才能将这些批次的请求聚合，方便后续在web端查看消息状&#x6001;**。**

**notification：**

| 字段名              | 字段格式 | 是否必传 | 说明                                                                                                                       | 限制                              | 示例                                        |
| ---------------- | ---- | ---- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | ----------------------------------------- |
| title            | 字符串  | 是    | 通知标题。                                                                                                                    | 长度不超过20个字符                      | 新消息通知！                                    |
| alert            | 字符串  | 是    | 通知内容。                                                                                                                    | 长度不超过50个字符                      | 收到一条新的留言，点击查看。                            |
| extras           | 对象   | 是    | 扩展字段，可以自定义 JSON 格式的 Key / Value 信息。这个字段暂时保留，可以先传空对象。                                                                     | extras与actionParameters键值对不超过4个 | {}                                        |
| actionType       | 字符串  | 是    | <p>点击跳转链接类型。</p><p>打开网页："openH5"</p><p>打开APP内具体某个页面："openUrl"</p><p>自定义协议："custom"，自定义协议需要客户通过actionParameters传参数并解析</p> |                                 | openUrl                                   |
| actionTarget     | 字符串  | 是    | 点击跳转路径。                                                                                                                  |                                 | com.growingio.push                        |
| actionParameters | 对象   | 是    | 点击跳转携带参数，以键值对形式传递。value不允许为null，不使用参数的情况下请传空对象                                                                           | extras与actionParameters键值对不超过4个 | {"key1": "value1", "key2": "value2"} 或 {} |

**options**

| 字段名            | 类型  | 说明                                           | 示例   |
| -------------- | --- | -------------------------------------------- | ---- |
| apnsProduction | 字符串 | true 表示推送生产环境，false 表示要推送开发环境；如果不指定则为推送生产环境。 | ture |

示例：

{% tabs %}
{% tab title="请求示例" %}

```yaml
{
	"cid": "61b757af-f877-4e15-84f2-0f0eef69277c",
	"name": "用户召回推送20190716170520",
	"packageName": "com.growingio.PushTest",
    "productId": "QPDM8loN",
	"audience": ["d54f5085-a057-4aa0-8463-87a1fe56e9fe", "241131c1-f3ca-4584-99b5-8a5a8c50f9c7"],
	"notification": {
		"title": "新消息通知！",
		"alert": "收到一条新的留言，点击查看。",
		"extras": {
			"key1": "value1",
			"key2": "value2"
		},
		"actionType": "openUrl",
		"actionTarget": "com.growingio.push",
		"actionParameters": {
			"key1": "value1",
			"key2": "value2"
		}
	},
	"options": {
		"apnsProduction": true
	}
}
```

{% endtab %}

{% tab title="成功返回示例" %}

| 字段名    | 字段格式 | 说明                     | 示例                                   |
| ------ | ---- | ---------------------- | ------------------------------------ |
| cid    | 字符串  | 请求参数里的 cid             | 61b757af-f877-4e15-84f2-0f0eef69277c |
| taskId | 字符串  | 任务ID，智能运营模块API单播功能查询使用 | 6gzPgHlS                             |

```c
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

 Response Data  

{
  "cid" : "61b757af-f877-4e15-84f2-0f0eef69277c"
}
```

{% endtab %}

{% tab title="失败返回示例" %}

| 字段名     | 字段格式   | 说明   | 示例           |
| ------- | ------ | ---- | ------------ |
| code    | int    | 错误码  | 1011         |
| message | string | 错误描述 | 请求速度过快，请稍后再试 |

```c
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8

 Response Data  
 
{
  "code" : 1011
  "message" : "请求速度过快，请稍后再试"
}
```

{% endtab %}
{% endtabs %}

**错误码及原因对照表**

| 错误码  | 错误描述                     | 备注                          |
| ---- | ------------------------ | --------------------------- |
| 1001 | 请求body json校验不通过         |                             |
| 1002 |                          | 自定义异常，描述可能不同                |
| 1010 | 系统内部异常，请稍后再试             | 联系技术支持解决                    |
| 1011 | 请求速度过快，请稍后再试             | API不要请求过快                   |
| 1012 | API token校验不通过           |                             |
| 1013 | 未找到项目                    | 联系技术支持解决                    |
| 1014 | 项目已被禁用                   | 联系技术支持解决                    |
| 1015 | 未找到对应产品，请检查参数packageName |                             |
| 1016 | 重复请求，请检查参数               | 两次请求的参数不能一模一样               |
| 1017 | 目标用户推送必备参数为空             | 请参考推送FAQ(**API推送任务1017**)排查 |
| 1018 | 未知异常，请更换cid后重试           |                             |

## 5. 推送数据

API创建推送暂不支持用户运营平台推送任务列表页查看，推送数据请使用「产品分析」-> 「事件分析」查看，页面填写参数可参考如下：

触达推送名称（新旧版本可能存在GIO\_区别） 对应发送body中的name

![通过事件分析查看API推送数据](https://348272635-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lpwgem-x8KzhBglybzw%2F-M9Sd29Gha4c0xyhinmp%2F-M9SifIW5ZNk9x0VX2OS%2Fimage.png?alt=media\&token=ff84045b-90d2-47ae-a55d-eaaad243f5ef)
