LeadsADX API 说明
LeadsADX 开放了三种接收流量的 API, 分别是用于 Open RTB 协议流量的 Bid API、用于开发者流量的 Publisher API 和用于 APP 流量的 SDK API。
Bid API
Open RTB 协议 iAB 组织制定的在线广告交易协议，行业内多数 SSP 和 AD Exchange 系统均使用该协议进行交易。
LeadsADX Bid API 是遵循 Open RTB 协议的流量接入接口，具体遵循 Open RTB Version 2.5 版本，其它版本的协议可以通过定制化接入。对于 Native 格式广告，遵循 Open RTB Native Version 1.2 规范。对于 Video 广告，遵循 iAB VAST Version 4.0 版本。
请求
请求地址
https://{LeadsADX_EXCHANGE_DOMAIN}/ad/bid/{SUPPLY_TOKEN}其中:
- {LeadsADX_EXCHANGE_DOMAIN}: LeadsADX 的交易域名; 实际使用时，需要将用于交易的域名 DNS 解析到 LeadsADX 的 Exchange 系统;
- {SUPPLY_TOKEN}: LeadsADX 系统为每个 Supply 生成的 SUPPLY_TOKEN，在系统 Supply 管理列表内可以复制，交易时通过该 TOKEN 识别流量来自于哪位 Supply。
请求方法
HTTP POST
请求体
请求体（Request Body）格式为 JSON 对象，具体结构及字段定义， 参考 Open RTB Version 2.5 规范中的 Bid Request 章节。
响应
LeadsADX 系统接收到 Bid 流量后，按系统内设置的规则将流量发给一个或多个上游 DSP 或 ADX，接收上游出价并实施竞价，将胜出的 AD 返回给流量方。如果没有有效出价，则返回流量方无 AD 填充。
响应码
根据竞价结果，响应码是以下之一：
- 200： 有 AD 填充，具体信息在响应体内给出;
- 204： 无 AD 填充;
- 400： 无效请求，同时在响应体内给出信息提示。
响应体
响应体（Response Body) 格式为 JSON，具体结构及定义， 参考 Open RTB Version 2.5 规范中的 Bid Response 章节。
无 AD 填充(响应码 204)时，响应体为空。
Publisher API
对于不支持 Open RTB 协议的开发者流量，可通过 Publisher API 接入 LeadsADX 系统。开发者在 LeadsADX 中创建了广告位后，系统会为每个广告位生成一个 Placement Token，开发者可以通过该 Token 将流量接入到 LeadsADX 系统，接入后可以通过 LeadsADX 系统进行流量的管理和优化。
请求
请求地址
https://{LeadsADX_EXCHANGE_DOMAIN}/ad/pub/{PLACEMENT_TOKEN}其中:
- {LeadsADX_EXCHANGE_DOMAIN}: LeadsADX 的交易域名; 实际使用时，需要将用于交易的域名 DNS 解析到 LeadsADX 的 Exchange 系统;
- {PLACEMENT_TOKEN}: LeadsADX 系统为每个 Placement 生成 PLACEMENT_TOKEN，在系统 Placement 管理列表内可以复制，交易时通过该 TOKEN 识别流量来自于哪个 Placement。
请求方法
HTTP POST
请求参数
请求参数（Request Body）格式为 JSON 对象，具体结构及字段定义如下:
| Name | Type | Required | Description |
|---|---|---|---|
| adformat | int | 1=Banner 2=Native 4=Video |
|
| w | int | width | |
| h | int | height | |
| appver | string | App 版本 | |
| ip | string | * | IPv4 address ip 和 ipv6 至少有一个 |
| ipv6 | string | * | IPv6 address ip 和 ipv6 至少有一个 |
| ua | string | Required | User agent |
| country | string | Required | ISO-3166-1 Alpha-3 country code |
| region | string | ||
| city | string | ||
| devicetype | int | Required | 1=Mobile/Tablet 2=Personal Computer 3=Connected TV 4=Phone 5=Tablet 6=Connected Device 7=Set Top Box |
| make | string | * | Device Maker, 品牌 如果 devicetype 是1、4、或者 5, 则本字段为必要字段 |
| model | string | * | Device Model, 型号 如果 devicetype 是1、4、或者 5, 则本字段为必要字段 |
| os | string | * | Device OS 如果 devicetype 是1、4、或者 5, 则本字段为必要字段 |
| osv | string | Device OS version | |
| carrier | string | Mobile carrier, ISP | |
| connectiontype | int | 0=Unknown 1=Ethernet 2=WIFI 3=Cellular Network – Unknown Generation 4=Cellular Network – 2G 5=Cellular Network – 3G 6=Cellular Network – 4G |
|
| idfa | string | iOS advertising ID | |
| idfamd5 | string | MD5 of iOS advertising ID | |
| idfasha1 | string | SHA1 of iOS advertising ID | |
| gaid | string | Android advertising ID | |
| gaidmd5 | string | MD5 of Android advertising ID | |
| gaidsha1 | string | SHA1 of Android advertising ID | |
| gid | string | Platform Device ID(例如, Android ID) | |
| gidmd5 | string | MD5 of Platform Device ID | |
| gidsha1 | string | SHA1 of Platform Device ID | |
| did | string | 设备硬件ID（例如, IMEI） | |
| didmd5 | string | MD5 of 设备硬件ID | |
| didsha1 | string | SHA1 of 设备硬件ID | |
| gender | string | O=Unknown M=Male F=Female |
|
| yob | int | 出生年份 | |
| usprivacy | string | OpenRTB Extension for iAB CCPA Compliance FrameworkOpenRTB Extension for U.S. Privacy |
|
| gdpr | int | 0=No 1=Yes |
|
| consent | string | GDPR consent string A string that contains the data structure developed by the GDPR Consent Working Group under the auspices of IAB Europe |
|
| tmax | int | 最大等待时间, 毫秒 | |
| test | int | 0=No（默认） 1=Yes |
响应
LeadsADX 接收到 Publisher API 的请求，结合系统内设置的 Placement Token 对应 APP 和 广告位信息，封装成 Open RTB Bid Request，发送给上游 DSP 或 ADX，接收上游出价并实施竞价，将胜出的 AD 返回给流量方。如果没有有效出价，则返回流量方无 AD 填充。
响应码
可能的响应码有三种：
- 200： 有 AD 填充，具体信息在响应体内给出;
- 204： 无 AD 填充;
- 400： 无效请求，同时在响应体内给出信息提示。
PubAPI响应体
响应体格式为 JSON 对象，对象内结构及定义说明如下：
Response JSON 对象
| Name | Type | Description |
|---|---|---|
| status | int | 0=Error 1=OK 2=No Content |
| message | string | |
| ads | JSON 数组 | 数组每个元素是一个 AD JSON 对象 |
| ext | JSON 对象 | 扩展信息 ext_is_backup=true AD来自LeadsADX系统内设置的保底广告方 ext_is_backup=false AD来自上游DSP或ADX |
AD JSON 对象
| Name | Type | Description |
|---|---|---|
| adformat | int | 1=Banner 2=Native 4=Video |
| adm | string | Banner AD HTML Video AD VAST XML |
| assets | JSON 数组 | 数组每个元素是一个 Asset JSON 对象 仅当 adformat=2 时有效 |
| linkurl | string | 点击跳转链接 仅当 adformat=2 时有效 |
| imptrackers | JSON 数组 | 数组每个元素是字符串，表示一个 Impression Tracker URL 仅当 adformat=2 时有效 |
| clicktrackers | JSON 数组 | 数组每个元素是字符串，表示一个 Click Tracker URL 仅当 adformat=2 时有效 |
| cid | string | Campaign ID |
| crid | string | Creative ID |
| cpm | double | CPM出价 |
Asset JSON 对象
| Name | Type | Description |
|---|---|---|
| id | int | Asset ID |
| title | JSON 对象 | Asset Title |
| img | JSON 对象 | Asset Image |
| data | JSON 对象 | Asset Data |
| video | JSON 对象 | Asset Video |
| adchoices | JSON 对象 | Asset AdChoices Icon |
Asset Title JSON 对象
| Name | Type | Description |
|---|---|---|
| text | string | Asset Title Text |
Asset Image JSON 对象
| Name | Type | Description |
|---|---|---|
| type | int | Asset Image Type 1=Icon 3=Main Image |
| url | string | Asset Image URL |
| w | int | Asset Image Width |
| h | int | Asset Image Height |
Data JSON 对象
| Name | Type | Description |
|---|---|---|
| type | int | Asset Data Type 1: sponsored 2: desc 3: rating, 0~5 4: likes 5: downloads 6: price 7: saleprice 8: phone 9: address 10: desc2 11: displayurl 12: ctatext |
| value | string | Asset Data Value |
Video JSON 对象
| Name | Type | Description |
|---|---|---|
| vasttag | string | Asset Video VAST Tag |
AdChoices Icon JSON 对象
| Name | Type | Description |
|---|---|---|
| imageurl | string | URL of the AdChoices icon |
| clickurl | string | Link to the custom privacy page |
| legaltext | string | Legal text |
SDK API
开发者也可以通过 SDK，在 APP 内部调用 LeadsADX SDK API，获取 AD 广告填充。
请求
请求地址
https://{LeadsADX_EXCHANGE_DOMAIN}/ad/sdk/{PLACEMENT_TOKEN}其中:
- {LeadsADX_EXCHANGE_DOMAIN}: LeadsADX 的交易域名; 实际使用时，需要将用于交易的域名 DNS 解析到 LeadsADX 的 Exchange 系统;
- {PLACEMENT_TOKEN}: LeadsADX 系统为每个 Placement 生成 PLACEMENT_TOKEN，在系统 Placement 管理列表内可以复制，交易时通过该 TOKEN 识别流量来自于哪个广告位。
请求方法
HTTP POST
请求参数
请求参数（Request Body）格式为 JSON 对象，具体结构及字段定义如下:
| Name | Type | Required | Description |
|---|---|---|---|
| adformat | int | 1=Banner 2=Native 4=Video |
|
| w | int | width | |
| h | int | height | |
| appver | string | App 版本 | |
| make | string | Required | Device Maker, 品牌 |
| model | string | Required | Device Model, 型号 |
| os | string | Required | Device OS |
| osv | string | Device OS version | |
| connectiontype | int | 0=Unknown 1=Ethernet 2=WIFI 3=Cellular Network – Unknown Generation 4=Cellular Network – 2G 5=Cellular Network – 3G 6=Cellular Network – 4G |
|
| ppi | int | Screen size as pixels per linear inch | |
| language | string | ISO-639-1-alpha-2 language code | |
| idfa | string | iOS advertising ID | |
| idfamd5 | string | MD5 of iOS advertising ID | |
| idfasha1 | string | SHA1 of iOS advertising ID | |
| gid | string | Platform Device ID(例如, Android ID) | |
| gidmd5 | string | MD5 of Platform Device ID | |
| gidsha1 | string | SHA1 of Platform Device ID | |
| tmax | int | 最大等待时间, 毫秒 | |
| test | int | 0=No（默认） 1=Yes |
响应
响应码
可能的响应码有三种：
- 200： 有 AD 填充，具体信息在响应体内给出;
- 204： 无 AD 填充;
- 400： 无效请求，同时在响应体内给出信息提示。
SDK API 响应体
响应体参见 Publisher API 响应体
Comments are closed.