帮助中心

中文

后可查看全部文档

帮助文档

新手引导

合作注册

流量管理

开发测试

财务结算

业务规范

GroMore

AdSpark（增长参谋）

成长工具

AdSpark（增长参谋）/技术接入文档/广告投放数据API使用说明/广告投放数据API使用说明（小时级）：v1.0

广告投放数据API使用说明（小时级）：v1.0

最近更新 2024-10-21 18:06:10

快捷接入：服务端SDK

服务端SDK（demo）：目标在于为开发者提供的快速开发库，帮助开发者更便捷的接入投放openAPI，缩短开发者接入时间，减少接入中的问题。通过使用服务端SDK，开发者仅需要进行一些参数赋值即可完成投放数据的上报。

pangle_mktapi_sdk-v1.1.zippangle_mktapi_sdk-v1.1.zip

32.80K

接口介绍

该接口用于开发者将广告投放数据回传给AdSpark(增长参谋)。投放API适用于非巨量引擎、磁力引擎和腾讯广告投放渠道，同时有其他广告投放渠道需求的媒体，具体可参考渠道映射关系

重点提示
上报地址：支持小时级和天级两种方式，上报地址获取方式如本文档第一步->上报地址
上报字段
content-type 使用的方式：application/json，使用错误会导致接口报错
请求签名signature：需要根据分配的secret_key对参数进行加密计算，秘钥获取方式如本文档第一步->签名秘钥
广告平台ad_platform：不同枚举值对应的投放平台不同，不可自定义，详细请参考渠道映射关系
批量接口最大数量限制：单个接口最大接收100条数据，数组超过限制会导致接口报错
回传时效【特别注意】
天级数据：当天数据需要保障最晚在次日凌晨2点前传完，仅支持计算t-1数据，更早日期数据不会加入计算
小时级数据：为了确保数据的准确性和时效性，建议开发者实时回传，最晚支持计算3h内的数据，如下午15点最多只能补传12点的数据，更早日期数据不会加入计算
数据回传要求
若您接入天级数据，则可以查看天级数据报表；若您接入小时级数据，则可以查看小时级和天级数据报表，但小时级数据源生成的天级数据报表数据准确性可能存在一定偏差。为了保障数据准确性和数据查看范围，建议同时接入两种类型数据。
小时级投放API，假如消耗每个小时都重新上传，会根据ad_id进行去重

自助接入入口

AdSpark(增长参谋)->快捷接入->数据接入-> 广告投放数据API->天/小时级API数据接入

只有正式完成接入，即状态是「已接入」的数据才会展示在数据报表，未接入/接入中的数据不会参与运算。

接入操作

第一步：获取数据上报地址、签名秘钥和对外ID

详细获取路径：AdSpark-快捷接入-数据接入-广告投放数据API-天/小时级数据接入

1. 上报地址

以下为AdSpark(增长参谋)提供的数据上报地址，您可以复制地址链接用于后续上报请求。

复制

2. 签名秘钥

下方为AdSpark(增长参谋)分配的secret_key（用于计算signature），根据第二步签名算法的指引生成signature使用：

复制

备注：每次更新接入流程都会重新生成一个secret_key，注意要用最新生成的！否则会出现401002错误码

第二步：数据上报

请参照以下信息，按照请求信息，将需要的参数上报到对应的接口地址，同时，请参照签名计算生成对应的签名，并作为请求body中的signature参数，来保障安全鉴权要求。

请求地址：https://www.csjplatform.com/growth_mkt/open/api/v1/callback_hourly/
请求信息

Method:Post
Content-Type:Application/json

请求上报参数：天级和小时级接口地址不同，字段也有区别

通用字段

字段英文名	字段中文名	类型	是否必填	说明
user_id	媒体主账户ID	string	是	穿山甲开发者平台的媒体账户ID(穿山甲媒体平台右上角显示ID)
signature	数据签名	string	是	通过分配的secret_key用于计算signature，参考下述签名算法模块进行加密
payload	上报数据内容	string	是	JSON字符串数组

payload字段

广告投放渠道说明

payload中含有广告投放渠道ad_platform字段，渠道类型分为广告平台渠道+厂商渠道，不同投放渠道类型对于参数的校验粒度不同。
当前支持渠道以渠道映射关系（自建归因/投放渠道）为准，范围外的渠道会直接拒收，如需添加请联系运营人员支持。注：巨量引擎和腾讯广告平台请通过AdSpark(增长参谋)平台授权方式接入。
上报数据来源
通过投放平台对应的数据报表比如投放账户ID/计划ID/广告组ID等相关信息拉取对应的展现、点击、消耗、包名等必传字段
把获取到的相关数据再回传给AdSpark(增长参谋)数据投放API

投放渠道分类	渠道说明
广告平台渠道	指通过巨量引擎、磁力引擎、腾讯广告等广告平台渠道买量，对应产生的广告展示、点击和消耗等相关数据。
非广告平台渠道	指通过华为、OV、小米等厂商渠道买量，对应产生的买量成本等相关数据。

小时级payload

分类	字段英文名	字段中文名	类型	是否必填-广告平台渠道	是否必填-厂商渠道	说明
通用信息	site_id	在穿山甲平台绑定的应用ID	long	是	是	根据上传的siteID自动绑定包名，以5开头的7位数字
通用信息	ad_platform	广告投放渠道	string	是	是	广告投放渠道映射表渠道映射关系（自建归因/投放渠道）
通用信息	stat_date	发生消耗的日期, 格式: yyyyMMdd	string	是	是
通用信息	stat_hour	发生消耗的小时时间(0-23)	string	是	是
通用信息	package_name	包名	string	是	是
通用信息	os	系统类型	string	是	是	安卓系统对应android ,ios系统对应ios
广告维度信息	advertiser_id	广告主 id	long	是	否	巨量平台对应advertiser_id 广点通平台对应account_id 磁力引擎对应advertiser_id
广告维度信息	advertiser_name	广告主名称	string	否	否	巨量平台对应advertiser_name 广点通平台对应account_name 磁力引擎对应advertiser_name
广告维度信息	campaign_id	广告第一层级，广告组id	long	是	否	巨量平台对应project_id 广点通平台对应campaign_id 磁力引擎对应campaign_id 百度对应campaignId
广告维度信息	campaign_name	广告第一层级，广告组名称	string	否	否	巨量平台对应project_name 广点通平台对应campaign_name磁力引擎对应campaign_name 百度对应campaignName
广告维度信息	ad_id	广告第二层级，广告计划 id	long	是	否	巨量平台对应promotion_id 广点通平台对应adgroup_id 磁力引擎对应unit_id 百度对应adGroupId
广告维度信息	ad_name	广告第二层级，广告计划名称	string	否	否	巨量平台对应promotion_name 广点通平台对应adgroup_name 磁力引擎对应unit_name 百度对应adGroupName
广告维度信息	creative_id	广告创意	long	否	否	巨量平台对应mid，mid是针对巨量引擎，下发的原始素材id，详细说明如下： mid1：图片素材宏参数 mid2：标题素材宏参数 mid3：视频素材宏参数 mid4：搭配试玩素材宏参数 mid5：落地页素材宏参数 mid6：安卓下载详情页素材宏参数广点通平台对应ad_id 磁力引擎对应creative_id 百度对应ideaId
广告维度信息	creative_name	广告创意名称	string	否	否
广告维度信息	ad_status	广告状态	string	否	否
广告维度信息	campaign_status	广告组状态	string	否	否
广告维度信息	campaign_create_time	广告组创建时间，格式：yyyy-MM-dd hh:mm:ss	string	否	否
广告维度信息	campaign_modify_time	广告组最后更新时间，格式：yyyy-MM-dd hh:mm:ss	string	否	否
广告维度信息	ad_create_time	广告计划创建时间，格式：yyyy-MM-dd hh:mm:ss	string	否	否
广告维度信息	ad_modify_time	广告计划更新时间，格式：yyyy-MM-dd hh:mm:ss	string	否	否
广告维度信息	deep_bid_type	投放方式	string	否	否	巨量平台对应deep_bid_type 广点通deep_optimization_action_type 磁力引擎对deep_conversion_type
投放信息	show	展示数	long	是	否
投放信息	click	点击数	long	是	否
投放信息	cost	总花费(RMB分)	long	是	是
投放信息	active	激活数	long	是	否
投放信息	active_cost	激活消耗(RMB分)	long	否	否
投放信息	convert	转化数	long	是	否
投放信息	convert_cost	转化消耗(RMB分)	long	否	否

签名计算

该步骤是通过系统分配的secret_key来计算上报地址中的signature

签名算法

请用上面提供的secret_key以下面的方式生成signature

复制

生成签名

2.1 golang

复制

2.2 Java

复制

2.3 Python

复制

请求示例

curl请求示例

复制

curl响应结果：

复制

第三步：接入检测

请在本页面AdSpark(增长参谋)下方点击接入检测，一键检测数据接入结果。

第四步：接入成功

当您完成接入检测，且返回接入成功信息时，
请点击确认接入并进入【接入成功页面】，正式完成接入。只有正式完成接入，即状态是「已接入」的数据才会展示在数据报表，未接入/接入中的数据不会参与运算。

响应错误码

错误码	错误信息	建议操作
0	success	成功
400006	parameter is unauthorized	未识别信息
400007	parameter is invalid	检查参数格式是否正确
401002	user unauthorized	检查是否有signature参数，若有，请核查signature计算方式是否正确
401004	ad parameter is empty	检查广告维度信息是否为空
401005	ad stat parameter is empty	检查广告投放数据是否为空
401006	time parameter is empty	检查是否有时间参数，若有，请检查时间格式是否正确
401007	required parameter is empty	检查必填参数是否丢失（具体参数请参考第二步第3点-请求参数上报）
401009	platform parameter is empty	检查渠道信息是否为空
401010	request reach limitation error	检查请求参数是否超限
500000	unknown error	服务内部错误，联系AdSpark(增长参谋)
500001	internal error	服务内部错误，联系AdSpark(增长参谋)
500102	illegal request in MW error	服务内部错误，联系增AdSpark(增长参谋)

本篇目录