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

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

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

接口介绍

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

重点提示

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

自助接入入口


接入操作

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

详细获取路径:AdSpark-快捷接入-数据接入-广告投放数据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
  • 请求上报参数:天级和小时级接口地址不同,字段也有区别

通用字段

字段英文名

字段中文名

类型

是否必填

说明

user_id

媒体主账户ID

string

穿山甲开发者平台的媒体账户ID(穿山甲媒体平台右上角显示ID)

signature

数据签名

string

通过分配的secret_key用于计算signature,参考下述签名算法模块进行加密

payload

上报数据内容

string

JSON字符串数组

payload字段

广告投放渠道说明

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

投放渠道分类

渠道说明

广告平台渠道

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

非广告平台渠道

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

天级payload

分类

字段英文名

字段中文名

类型

是否必填

-广告平台渠道

是否必填

-厂商渠道

说明

通用信息

site_id

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

long

根据上传的siteID自动绑定包名,以5开头的7位数字

通用信息

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

百度对应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(增长参谋)



Contents
Contact us