English
Log In
You can then view all documents
AdSpark(增长参谋)/技术接入文档/广告投放数据API使用说明/广告投放数据API使用说明(天级):v1.0
广告投放数据API使用说明(天级):v1.0
Last updated 2023-12-08 17:22:22

快捷接入:服务端SDK

pangle_mktapi_sdk-v1.1.zippangle_mktapi_sdk-v1.1.zip
32.80K

重点提示

  1. 请求签名signature需要根据分配的secret_key对参数计算,然后添加请求body里
  2. 上报地址上报地址分小时级和天级,上报字段略有不同
  3. ad_platform 的枚举值不可自定义,详细请参考。不同枚举值对应的投放平台不同,必传字段也有区别
  4. content-type 使用的方式application/json,使用错误会导致接口报错
  5. 批量接口最大数量限制:单个接口最大接收100条数据,数组超过限制会导致接口报错
  6. 天级数据上报时间:当天数据需要保障最晚在次日凌晨2点前传完,仅支持计算t-1数据,更早日期数据不会加入计算

投放API适用于非巨量引擎、磁力引擎和腾讯广告投放渠道,同时有其他广告投放渠道需求的媒体,具体可参考 渠道映射关系

接入操作

第一步:获取数据上报地址、签名秘钥

上报地址

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

复制

签名秘钥

下方为AdSpark(增长参谋)分配的secret_key(用于计算signature),根据签名算法的指引生成signature使用

复制

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

第二步:数据上报

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

  • 天级接口地址

天级别: https://www.csjplatform.com/growth_mkt/open/api/v1/callback_daily/

  • 请求信息

Method:Post
Content-Type:Application/json

  • 请求上报参数

注意:天级和小时级接口地址不同,字段也有区别
天级: https://www.csjplatform.com/growth_mkt/open/api/v1/callback_daily/


通用字段

字段英文名

字段中文名

类型

是否必填

说明

user_id

媒体主账户ID

string

穿山甲开发者平台的媒体账户ID

signature

数据签名

string


payload

上报数据内容

string

JSON字符串数组

payload字段

广告投放渠道说明

1. payload字段含有广告投放渠道ad_platform字段,渠道类型分为广告平台渠道+厂商渠道,不同投放渠道类型对于参数的校验粒度不同。
2. 当前支持标准渠道以 注意:媒体渠道映射关系 为主,如果有范围外的渠道请联系运营人员支持

注:巨量引擎和腾讯广告平台请通过AdSpark(增长参谋)平台授权方式接入。

投放渠道分类

渠道说明

广告平台渠道

指通过巨量引擎、磁力引擎、腾讯广告等广告平台渠道买量,对应产生的广告展示、点击和消耗等相关数据。

非广告平台渠道

指通过华为、OV、小米等厂商渠道买量,对应产生的买量成本等相关数据。

天级payload

分类

字段英文名

字段中文名

类型

是否必填

-广告平台渠道

是否必填

-厂商渠道

说明

通用信息

site_id

在穿山甲平台绑定的应用ID

long

根据上传的siteID自动绑定包名

通用信息

ad_platform

广告投放渠道

string

!!! 注意:媒体渠道映射关系 ,广告投放渠道映射表

通用信息

stat_date

发生消耗的日期, 格式: yyyyMMdd

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

广告维度信息

campaign_name

广告第一层级,广告组名称

string

巨量平台对应project_name,广点通平台对应campaign_name,磁力引擎对应campaign_name

广告维度信息

ad_id

广告第二层级,广告计划 id

long

巨量平台对应promotion_id,广点通平台对应adgroup_id,磁力引擎对应unit_id

广告维度信息

ad_name

广告第二层级,广告计划名称

string

巨量平台对应promotion_name,广点通平台对应adgroup_name,磁力引擎对应unit_name

广告维度信息

creative_id

广告创意

long

巨量平台对应mid,广点通平台对应ad_id,磁力引擎对应creative_id

mid是针对巨量引擎,下发的原始素材id,详细说明如下:

mid1:图片素材宏参数

mid2:标题素材宏参数

mid3:视频素材宏参数

mid4:搭配试玩素材宏参数

mid5:落地页素材宏参数

mid6:安卓下载详情页素材宏参数

广告维度信息

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


签名计算

该步骤为了计算上报地址中的signature

签名算法

json

复制

生成签名

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(增长参谋)



Contents
Contact us