仙果ADX对接文档V2.0.5-JSON

目录

  • 仙果ADX对接文档V2.0.5-JSON
  • 1修订记录
  • 1.1 说明
  • 1.2 接入说明
  • 2 竞价接口
  • 2.1 BidRequest
  • 3.1BidResponse
  • 4错误码详情
  • 5类型
  • 6曝光和点击数据

1修订记录

2016-11-15

(1)ADX-JSON版本修订开始(Ver:2.0.3)

2016-12-15

(2)增加BidResponse HTML片段支持,同时也增加了广告审核物料广告ID与创意ID(Ver:2.0.4)

2017-06-08

(3)请求头部增加SSP_ID和MediumID参数,同时也增加了数据加密协议(Ver:2.0.5)

2017-09-13

(4)Bid对象中新增开始下载(downStart_url)和开始安装(installStart_url)属性

1.1 说明

(1). 该技术文档分别帮助DSP和SSP使用仙果广告的实时竞价接口。通过广告家的接口所传递的参数,匹配出最合适的广告。

(2). 仙果广告和DSP及SSP之间实时交互,使用标准的HTTP协议,通过POST方式进行交互,交互格式:json

(3). 同时你可以标准的OpenRTB广告交互协议。

1.2 接入说明

(1). (流量方)合作方通过商务流程: 将贵方的媒介产品报备给仙果广告进行效验。

(2). 仙果的实时竞价请求接口: http://www.xxx.com/api ,流量方需要把数据加密后post此接口(加密协议详情请咨询技术人员)。

(3). 流量方联系技术人员进行联调测试: 系统会给合作方所提供相关的测试数值,如:SSP_ID,Medium_ID,MADS_ID。

(4).HTTP请求头部参数!!!(必填)

int SSP_ID = 1;  // 必填!(即ssp_id的值)
int MediumID = 2;  // 必填!(即medium_id的值)
参数 类型
Body SSP_ID Object int
Body MediumID Object int
HttpConnect conn = new HttpConnect();
HashMap<String, String> header = new HashMap<String, String>();
header.put("GType", "GZIP");
header.put("SSP_ID", sspId + "");
header.put("MediumID", mediumId + "");
byte[] response = conn.request(context, url, "POST", "", "", postDataEncrypted, header, 0, "");

2 竞价接口

实时竞价接口URL:http://api2.goalmobi.com/Bid/XianGuoJson.ashx (正式)

2.1 BidRequest

(1)BidRequest是流量合作方发送给仙果请求数据的顶层对象。对象包含所有信息 例如:投标对象信息,版本号信息,配置信息,目标用户信息,设备信息,等等...

string id= 1;//请求ID 必填!接入方自定义请求ID,[a-zA-Z0-9]{32} 
string api_version = 2;  // 必填!API版本,当前版本2.0.5,填写错误会导致 
Config config= 3;// 必填!--需要仙果广告商务提供
Device device= 4;//设备信息-客户端
AdSlot adslot= 5;//广告位信息
App app= 6;//app信息
int adcount= 7;//返回的广告数量。 默认是1
Installpackages installpackages=8;//已安装的应用列表
参数 类型
Body id Object string
Body api_version Object string
Body Config Object Config
Body Device Object Device
Body AdSlot Object AdSlot
Body App Object App
Body adcount Object int
Body installpackages Object Installpackages

(2)Config 对象

int ssp_id = 1;  // 必填!仙果提供此ID
int medium_id = 2;  // 必填!仙果提供此ID
int mads_id = 3;  // 必填!仙果提供此ID
参数 类型
Body ssp_id Object int
Body medium_id Object int
Body mads_id Object int

(3)Device 对象

string devicetype =1; // 设备类型"PHONE" 手机, "TABLET" 平板
string ostype =2;  // 操作系统类型 // Android,// iOS
string os_version = 3;  // 必填!操作系统版本 如:4.0.1
string vendor = 4;  // 必填!设备厂商名称 
string model = 5;  // 必填!设备型号 
SpType sptype = 6;  // 必填!运营商
string imei = 7[default = ""]; //必填! Android手机设备的IMEI
string mac = 8[default = ""]; //必填! Android非手机设备的WiFi网卡MAC址
string imei_md5 = 9; //必填! Android手机设备的IMEI,经过MD5加密
string android_id = 10[default = ""]; //必填!Android手机设备系统ID
int screen_width = 11; //设备屏幕宽
int screen_height = 12; //设备屏幕高
string imsi = 13; //必填!手机设备的IMSI
string ip=14; // 必填!手机客户端IP
ConnectionType connectiontype = 15;  // 必填!联网类型
Geo geo = 16;//设备位置信息,经纬度以及省市信息
string ua=17; // 客户端User-Agent
string idfa=18; // 必填!IOS 设备的idfa 值
string udid=19; // IOS设备的openudid 值
string idv=20; // IOS 设备的idv 值
参数 类型
Body devicetype Object string
Body ostype Object string
Body os_version Object string
Body vendor Object string
Body model Object string
Body sptype Object SpType
Body imei Object string
Body mac Object string
Body imei_md5 Object string
Body android_id Object string
Body screen_width Object int
Body screen_height Object int
Body imsi Object string
Body ip Object string
Body connectiontype Object ConnectionType
Body geo Object Geo
Body ua Object string
Body idfa Object string
Body udid Object string
Body idv Object string

(4)AdSlot 对象

int adslot_width = 1; //广告物料宽
int adslot_height = 2; //广告物料高
string topics = 3; // 选填 详情数值咨询技术人员.....
int bidfloor= 4;//低价(单位:分)
AdType adtype = 5;  // 必填!广告类型
String[] packagename = 6;  // 选填,如果填充此值,意味着返回广告此包名的广告
参数 类型
Body adslot_width Object int
Body adslot_height Object int
Body topics Object string
Body bidfloor Object int
Body adtype Object AdType
Body packagename Object String[]

(5)App 对象

string App_packagename= 1;//App包名
string appname = 2;//App名称
string cat = 3;//app分类
参数 类型
Body App_packagename Object string
Body appname Object string
Body cat Object string

(6)Geo对象

double longitude = 1;//经度-非必传
double latitude = 2;//纬度-非必传
string province = 3;//省份-必须
string city = 4;//城市-非必传
参数 类型
Body longitude Object double
Body latitude Object double
Body province Object string
Body city Object string

(7)Installpackages对象

byte[] packagename = 1;//应用包名
byte[] appname = 2;//应用名称
byte[] app_ver = 3;//应用版本号
参数 类型
Body packagename Object byte[]
Body appname Object byte[]
Body app_ver Object byte[]

3.1BidResponse

(1)BidResponse是发送给流量合作方回写数据的顶层对象。对象包含所有信息 例如:广告物料信息,请求错误码,竞价价格

(2)BidResponse 对象

string id=1;//此ID就是广告请求的id--合作方唯一ID
List<Bid> bids=2;
int error_code = 3;  //错误码 
int bidprice= 4;//出价 单位(分)
参数 类型
Body id Object string
Body bids Object Bid 类型集合
Body error_code Object int
Body bidprice Object int

4错误码详情

JSON错误码 解释
0 正常返回
1000 无广告返回
2000 配置信息不正确
3000 API版本号信息错误
4000 Device 对象配置错误
5000 AdSlot 对象配置错误
HTTPCODE状态码 解释
202 此请求没有合适的广告源
204 请求字符串不符合要求
207 此流量源没有配置广告源
209 此流量源未配置广告

(2)Bid 对象

string Href = 1; //广告地址--落地页,在客户端进行响应,会经过多次302跳转最终到达目标地址
ArrayList show_url = 2;  // 曝光上报日志URL列表,该地址需要包含宏 %%WIN_PRICE%% ,用于上报成交价,非竞价的直接替换成0。
ArrayList click_url = 3;  // 点击上报URL列表,用户点击后,通知服务器。
ArrayList downStart_url = 4; // 开始下载上报URL列表,用户开始下载时,通知服务器
ArrayList down_url = 5;  // 下载完成上报URL列表,用户下载完成后,通知服务器。
ArrayList installStart_url = 6; //开始安装上报URL列表,用户开始安装时,通知服务器。
ArrayList install_url = 7;  // 安装完成上报URL列表,用户安装完成后,通知服务器。
string title = 8;  // 推广标题
string description = 9;  // 广告描述,
string icon_src = 10;  // 广告图标地址-icon
string image_src = 11;  // 广告图片地址-img
string app_package = 12; // 下载类广告应用包名
int app_size = 13; // 下载类广告应用大小
string adm=14;  // html片段
string cid=15;  // 审核物料广告ID
string crid=16;  //审核物料广告创意ID
InteractionType interaction_type =17;  // 交互类型

注意:

1.曝光上报日志URL列表,该地址需要包含宏 %%WIN_PRICE%% ,用于上报成交价,非竞价的直接替换成0。

2.所有上报地址(曝光、点击、开始下载、下载完成、开始安装和安装完成)都必须支持302跳转。如果状态码为302,则有重定向,读取http Headers 里的Location值即可。

参数 类型
Body Href Object string
Body show_url Object ArrayList
Body click_url Object ArrayList
Body downStart_url Object ArrayList
Body down_url Object ArrayList
Body installStart_url Object ArrayList
Body install_url Object ArrayList
Body title Object string
Body description Object string
Body icon_src Object string
Body image_src Object string
Body app_package Object string
Body app_size Object int
Body adm Object string
Body cid Object string
Body crid Object string
Body interaction_type Object InteractionType

5类型

(1)InteractionType 类型

参数 类型
Body H5 Object string 跳转类广告
Body DOWNLOAD Object string 下载类型广告
Body HTML Object 此交互类型是,是html类型代码

(2)ConnectionType类型

参数 类型
Body CELL_2G Object string
Body CELL_3G Object string
Body CELL_4G Object string
Body CELL_WIFI Object string

(3)SpType类型

参数 类型
Body YD Object string //移动
Body LT Object string //联通
Body DX Object string //电信
Body None Object string//未知

(4) AdType类型

参数 类型
Body currency Object string //通用
Body banner Object string //横幅
Body splash Object string //开屏
Body ingame Object string//插屏
Body feeds Object string//信息流
Body notice Object string//通知栏
Body video Object string//视频

6曝光和点击数据

当供应方或流量方接受到仙果广告返回信息后,如果Bid 对象show_url和click_url不等于空的情况,请循环该字段数值,客户端进行曝光的汇报,如果存在漏报或者不报的情况,如果供应方或流量方合作是按曝光合作方式,我们将不会纳入收益里面。注意:如果供应方或流量方是CPD合作,则必须上报down_url,不上报,也不会纳入收益数据。

注意:跳转类广告上报曝光和点击即可;下载类广告曝光、点击、开始下载、下载完成、开始安装和安装完成都要求上报。

以上所用的媒介类型,所有的参数请以此文档为准,实例请看JSON-DEMO。