快捷接入:服务端SDK(demo):目标在于为开发者提供的快速开发库,帮助开发者更便捷的接入投放openAPI,缩短开发者接入时间,减少接入中的问题。通过使用服务端SDK,开发者仅需要进行一些参数赋值即可完成投放数据的上报。
该接口用于开发者将广告投放数据回传给AdSpark(增长参谋)。投放API适用于非巨量引擎、磁力引擎和腾讯广告投放渠道,同时有其他广告投放渠道需求的媒体,具体可参考 渠道映射关系
重点提示
- 上报地址:支持小时级和天级两种方式,上报地址获取方式如本文档第一步->上报地址
- 上报字段
- content-type 使用的方式:application/json,使用错误会导致接口报错
- 请求签名signature:需要根据分配的secret_key对参数进行加密计算,秘钥获取方式如本文档第一步->签名秘钥
- 广告平台ad_platform:不同枚举值对应的投放平台不同,不可自定义,详细请参考渠道映射关系
- 批量接口最大数量限制:单个接口最大接收100条数据,数组超过限制会导致接口报错
- 回传时效【特别注意】
- 天级数据:当天数据需要保障最晚在次日凌晨2点前传完,仅支持计算t-1数据,更早日期数据不会加入计算
- 小时级数据:为了确保数据的准确性和时效性,建议开发者实时回传,最晚支持计算3h内的数据,如下午15点最多只能补传12点的数据,更早日期数据不会加入计算
- 数据回传要求
- 若您接入天级数据,则可以查看天级数据报表;若您接入小时级数据,则可以查看小时级和天级数据报表,但小时级数据源生成的天级数据报表数据准确性可能存在一定偏差。为了保障数据准确性和数据查看范围,建议同时接入两种类型数据。
- 小时级投放API,假如消耗每个小时都重新上传,会根据ad_id进行去重
详细获取路径:AdSpark-快捷接入-数据接入-广告投放数据API-天/小时级数据接入
以下为AdSpark(增长参谋)提供的数据上报地址,您可以复制地址链接用于后续上报请求。
下方为AdSpark(增长参谋)分配的secret_key(用于计算signature),根据第二步签名算法的指引生成signature使用:
备注:每次更新接入流程都会重新生成一个secret_key,注意要用最新生成的!否则会出现401002错误码
请参照以下信息,按照请求信息,将需要的参数上报到对应的接口地址,同时,请参照签名计算生成对应的签名,并作为请求body中的signature参数,来保障安全鉴权要求。
Method:Post
Content-Type:Application/json
字段英文名 | 字段中文名 | 类型 | 是否必填 | 说明 |
user_id | 媒体主账户ID | string | 是 | 穿山甲开发者平台的媒体账户ID(穿山甲媒体平台右上角显示ID) |
signature | 数据签名 | string | 是 | 通过分配的secret_key用于计算signature,参考下述签名算法模块进行加密 |
payload | 上报数据内容 | string | 是 | JSON字符串数组 |
广告投放渠道说明
- 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 | 是 | 是 | |
通用信息 | 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
请在本页面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(增长参谋) |
Online Customer Service24/7 Online Customer Service BotManual customer service, weekdays 10~ 12 o'clock/14~ 19 o'clock