互动广告 API

使用规则

  1. 本接口仅适用于极光互动广告业务
  2. 用于提供程序化对接广告位获取符合创建广告位时登记的创意素材以及跳转链接的能力
  3. 能使用本接口的广告位一定是程序化对接的方式,直链对接无法通过接口获取入口素材以及链接
  4. 鉴权层级是基于平台级别,使用的鉴权密钥对为 hdtKey 和 hdtSecret
  5. 能拉取到创意素材的前提是,在程序化广告位创建完成后, 运营已经人工完成所登记的素材元素和跳转链接分配
  6. 获取到素材后需上报入口曝光、点击等相关事件

鉴权方式

  • 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
}'

请求字段说明:

参数名 字段类型 字段定义 是否必填
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"
}

返回字段说明:

字段名称 字段类型 是否必须 字段定义
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 服务器异常

Copyright 2011-2020, jiguang.cn, All Rights Reserved.
粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

Documentation built with MkDocs.