# 推送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 **请求头(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的含义可以参考这个文档：。再重申一下，就是接入SDK时上报的ID，理论上这个ID应该存储于接入方系统的数据库中。 * 推送目标用户如果小于等于2000个，可以将所有目标设备标识放到一个请求里批量推送，推送完成之后建议更换cid和消息内容再进行下次推送。 * 推送目标用户如果大于2000个，需要分批推送，每批目标设备标识个数小于等于2000，保证这些批次的cid相同和消息体内容相同，这样才能将这些批次的请求聚合，方便后续在web端查看消息状态**。** **notification：** | 字段名 | 字段格式 | 是否必传 | 说明 | 限制 | 示例 | | ---------------- | ---- | ---- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | ----------------------------------------- | | title | 字符串 | 是 | 通知标题。 | 长度不超过20个字符 | 新消息通知！ | | alert | 字符串 | 是 | 通知内容。 | 长度不超过50个字符 | 收到一条新的留言，点击查看。 | | extras | 对象 | 是 | 扩展字段，可以自定义 JSON 格式的 Key / Value 信息。这个字段暂时保留，可以先传空对象。 | extras与actionParameters键值对不超过4个 | {} | | actionType | 字符串 | 是 |

点击跳转链接类型。

打开网页："openH5"

打开APP内具体某个页面："openUrl"

自定义协议："custom"，自定义协议需要客户通过actionParameters传参数并解析

| | 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推送数据](/files/-M9SifIW5ZNk9x0VX2OS) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://growingio.gitbook.io/mp/developers/open-api/push-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.