互动广告 API
最近更新:2021-12-15
展开全部
互动广告 API
使用规则
- 本接口仅适用于极光互动广告业务
- 用于提供程序化对接广告位获取符合创建广告位时登记的创意素材以及跳转链接的能力
- 能使用本接口的广告位一定是程序化对接的方式,直链对接无法通过接口获取入口素材以及链接
- 鉴权层级是基于平台级别,使用的鉴权密钥对为 hdtKey 和 hdtSecret
- 能拉取到创意素材的前提是,在程序化广告位创建完成后, 运营已经人工完成所登记的素材元素和跳转链接分配
- 获取到素材后需上报入口曝光、点击等相关事件
鉴权方式
- AD API 采用 HTTP 基本认证的验证方式:通过在 HTTP Header 中增加
Authorization
参数来对校验字符串进行传递验证; - Header 名称是
Authorization
,值是 base64 转换过的username:password
对(中间有个冒号); - 在 AD API 场景中,
username
是 hdtKey,password
是 hdtSecret,可在【控制台】-【互动广告】-【平台设置】内获取,不同平台对应不同的 key 和 secret ; - 上述 base64AuthString 的生成算法为:
base64(hdtKey:hdtSecret)
; - 获取广告 API 和事件上报 API 均采用上述的鉴权方案,如鉴权失败会造成无法拉取到广告素材和事件上报失败。
接口说明
请求URL:https://api-extra.hzjizhun.com/hdt-rtb-server/ads
请求方法:POST
请求示例:
curl -X POST 'https://api-extra.hzjizhun.com/hdt-rtb-server/ads' -H 'Authorization:Basic ZGM4NWNkNzdlYzk0NTJiYTIwNjA4ZmM3NjNmNDUyNzg6ZmJjYmQyZGUwYjIzNjAwMDgwZjAxYjMyMDliZjU5Zjg='
-H 'Content-Type: application/json'
-d '{
"apiVersion":"V1",
"app":{
"jzAdslotId":"4014558972242762",
},
"device":{
"androidId":"50373ad72b7b72916f9287ce600789b8",
"brand":"Huawei",
"imei":["359355041886388"],
"model":"p40pro",
"oaid":"72b7b72916f92",
"osType":"Android",
"osVersion":"10.15.5",
"screenHeight":1024,
"screenWidth":768
},
"location":{
"latitude":34.563,
"longitude":123.876
},
"network":{
"connectionType":"CELL_5G",
"ipv4":"116.24.67.213"
},
"reqId":"c3a9a9478c374e1e893f61d73ed4469c",
"test":true
}'
curl -X POST 'https://api-extra.hzjizhun.com/hdt-rtb-server/ads' -H 'Authorization:Basic ZGM4NWNkNzdlYzk0NTJiYTIwNjA4ZmM3NjNmNDUyNzg6ZmJjYmQyZGUwYjIzNjAwMDgwZjAxYjMyMDliZjU5Zjg='
-H 'Content-Type: application/json'
-d '{
"apiVersion":"V1",
"app":{
"jzAdslotId":"4014558972242762",
},
"device":{
"androidId":"50373ad72b7b72916f9287ce600789b8",
"brand":"Huawei",
"imei":["359355041886388"],
"model":"p40pro",
"oaid":"72b7b72916f92",
"osType":"Android",
"osVersion":"10.15.5",
"screenHeight":1024,
"screenWidth":768
},
"location":{
"latitude":34.563,
"longitude":123.876
},
"network":{
"connectionType":"CELL_5G",
"ipv4":"116.24.67.213"
},
"reqId":"c3a9a9478c374e1e893f61d73ed4469c",
"test":true
}'
此代码块在浮窗中显示
请求字段说明:
参数名 | 字段类型 | 字段定义 | 是否必填 |
---|---|---|---|
apiVersion | String | 调用的API版本,当前版本为V1 | 是 |
app | Object | 广告位信息,用来定位当前拉取广告的广告位信息 | 是 |
jzAdslotId | String | 广告位ID | 是 |
device | Object | 当前设备信息 | 是 |
androidId | String | Android系统ID | 否 |
brand | String | 设备品牌 | 否 |
imei | String[] | 设备IMEI,多卡设备传入多个IMEI | 否 |
model | String | 设备型号 | 否 |
oaId | String | Android广告ID | 否 |
osType | String | 操作系统类型:Android、iOS、other | 是 |
osVersion | String | 操作系统版本 | 是 |
screenHeight | Integer | 屏幕高度(像素) | 否 |
screenWidth | Integer | 屏幕宽度(像素) | 否 |
location | Object | 当前位置信息 | 否 |
latitude | Double | 坐标纬度 | 否 |
longitude | Double | 坐标经度 | 否 |
network | Object | 设备网络信息 | 是 |
ipv4 | String | IPv4地址 | 是 |
connectionType | 是 | 网络连接类型 UNKNOWN: 无法探测当前网络状态 CELL_UNKNOWN: 蜂窝数据接入,未知网络类型 CELL_2G: 蜂窝数据2G网络 CELL_3G: 蜂窝数据3G网络 CELL_4G: 蜂窝数据4G网络 CELL_5G: 蜂窝数据5G网络 WIFI: Wi-Fi网络接入 ETHERNET: 以太网接入 NEW_TYPE: 未知新类型 MOBILE: Android数据流量接入 |
是 |
test | Boolean | 获取广告类型,true 为测试广告素材, false 为正式广告素材 | 是 |
reqId | String | 广告拉取ID,不可重复,建议采用下方实现方式生成 | 是 |
返回示例:
{
"adMaterial":{
"deepLink":"alipays://platformapi/startapp?appId=2021001165601882&page=pages/index/index%3FchannelCode%3dJZXCX",
"description":"这个广告不一样",
"icon":"https://xxx.xxx.com/hdt-res/2jueshika.png",
"images":[
"https://xxx.xxx.com/hdt-res/2jueshika.png",
"https://xxx.xxx.com/hdt-res/3jueshika.png"],
"landingUrl":"http://xxx.xxx.com/ssp-hd-h5/activities/6pVAIQyq",
"reqId":"1eb9df4a45ad48249f0c362d996bfe18",
"title":"极光互动广告",
"downloadUrl":"http://xxx.xxx.com/ssp-hd-h5/activities/haha.apk",
"type":1,
"adTracking" :{
"winUrl":"https://xxx.com/hdt-track/api/ads/wins?req_id=12343",
"exposureUrl":"https://xxx.com/hdt-track/api/ads/exposures?req_id=12343",
"clickUrl":"https://xxx.com/hdt-track/api/ads/clicks?req_id=12343",
"eventsUrl": ["https://xxx.com/hdt-track/api/ads/event1?req_id=12343"]
}
},
"errCode":2000,
"errMsg":"success"
}
{
"adMaterial":{
"deepLink":"alipays://platformapi/startapp?appId=2021001165601882&page=pages/index/index%3FchannelCode%3dJZXCX",
"description":"这个广告不一样",
"icon":"https://xxx.xxx.com/hdt-res/2jueshika.png",
"images":[
"https://xxx.xxx.com/hdt-res/2jueshika.png",
"https://xxx.xxx.com/hdt-res/3jueshika.png"],
"landingUrl":"http://xxx.xxx.com/ssp-hd-h5/activities/6pVAIQyq",
"reqId":"1eb9df4a45ad48249f0c362d996bfe18",
"title":"极光互动广告",
"downloadUrl":"http://xxx.xxx.com/ssp-hd-h5/activities/haha.apk",
"type":1,
"adTracking" :{
"winUrl":"https://xxx.com/hdt-track/api/ads/wins?req_id=12343",
"exposureUrl":"https://xxx.com/hdt-track/api/ads/exposures?req_id=12343",
"clickUrl":"https://xxx.com/hdt-track/api/ads/clicks?req_id=12343",
"eventsUrl": ["https://xxx.com/hdt-track/api/ads/event1?req_id=12343"]
}
},
"errCode":2000,
"errMsg":"success"
}
此代码块在浮窗中显示
返回字段说明:
字段名称 | 字段类型 | 是否必须 | 字段定义 |
---|---|---|---|
deepLink | String | 否 | deepLink唤醒地址 |
description | String | 否 | 描述,对应创建广告位添加名称为描述的元素 |
icon | String | 否 | 图标,对应创建广告位添加名称为图标的元素 |
images | String[] | 否 | 广告图片素材(数组),对应主图元素 |
landingUrl | String | 否 | 落地页地址 |
reqId | String | 是 | 请求id |
title | String | 否 | 广告标题 |
downloadUrl | String | 否 | 下载地址 |
type | Integer | 是 | 跳转类型 1. 跳转落地页地址:landingUrl; 2. 跳转deepLink地址:deepLink ; 3. 跳转下载地址:downloadUrl |
adTracking | Object | 是 | 事件上报信息 |
winUrl | String | 是 | 竞得事件上报接口地址 |
exposureUrl | String | 是 | 曝光事件上报接口地址 |
clickUrl | String | 是 | 点击事件上报接口地址 |
eventsUrl | String[] | 否 | 其它事件上报接口地址 |
广告事件上报
广告素材通过上述接口拉取后,需要对广告的竞得(是否被正常展示到页面中)、曝光(是否被用户看到)、点击(是否被用户点击)等事件进行及时的上报,接入本 API 后,可以上报对应的入口点击事件、曝光事件、竞得事件和其他自定义事件上报。
竞得事件上报
接口地址:接口地址通过广告返回结果中的 adTracking 对象中的 winUrl 字段
请求方式:GET
接口说明:该接口地址中已传递了竞得事件上报所需参数,当客户端使用该广告素材时,直接调用该接口即可
曝光事件上报
接口地址:接口地址通过广告返回结果中的 adTracking 对象中的 exposureUrl 字段
请求方式:GET
接口说明:该接口地址中已传递了曝光事件上报所需参数,当客户端将该广告展示到用户屏幕中时,直接调用该接口即可
点击事件上报接口
接口地址:接口地址通过广告返回结果中的 adTracking 对象中的 clickUrl 字段
请求方式:GET
接口说明:该接口地址中已传递了点击事件上报所需参数,当该广告被用户点击时,直接调用该接口即可
其它事件上报接口
接口地址:接口地址通过广告返回结果中的 adTracking 对象中的 eventsUrl 字段
请求方式:GET
接口说明:如果不存在其它需要上报的事件,则不返回该字段或返回空数组;如果存在其它需要上报的事件,直接遍历该事件上报地址数组,然后逐一调用上报即可
接口异常码对照表
httpStatus | errCode | errMsg | 备注 |
---|---|---|---|
200 | 2000 | SUCCESS | 成功 |
204 | 2001 | NO_DEAL | 成功,但缺少合适素材 |
400 | 4001 | REQUEST_BODY_EMPTY | 请求体为空 |
400 | 4002 | REQUEST_PARAM_ERROR | 请求参数异常 |
400 | 4003 | JZ_APP_ID_NOT_MATCH_JZ_APP_KEY | 应用ID与应用Key不匹配 |
400 | 4004 | JZ_APP_ID_NOT_MATCH_JZ_ADSLOT_ID | 应用ID与广告位ID不匹配 |
400 | 4005 | REQ_ID_EXIST | 请求ID已存在 |
401 | 4011 | AUTH_ERROR | 鉴权失败 |
500 | 5000 | SERVER_ERROR | 服务器异常 |
文档内容是否对您有帮助?