仙果ADX对接文档V2.0.4-Proto

目录

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

1.修订记录

2016-08-04

(1)对应协议文档版本XinGuoV2.0.1.proto版本

2016-09-22

(2)增加了广告数量,同时扩展了已安装的包的信息。对应协议文档版本XinGuoV2.0.2.proto版本

(3)修改了个别参数的类型,扩充了广告的根据包名下发,对应的协议版本是XinGuoV2.0.3.proto版本

(4)增加BidResponse HTML片段支持(2016-12-15)XinGuoV2.0.4.proto版本

1.1 说明

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

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

(3). 您可以通过 http://code.google.com/p/protobuf,获取最新的protocol-buers 技术支持。

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

1.2 接入说明

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

(2). 仙果的实时竞价请求接口:http://www.xxx.com/api,流量方需要把数据post此接口。

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

2 竞价接口

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

2.1 BidRequest

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

对应protobuf:

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

对应protobuf:

optional uint32 major = 1[default = 0]; // 必填!
optional uint32 minor = 2[default = 0]; // 必填!
optional uint32 micro = 3[default = 0]; // 必填!
参数 类型
Body major Object int
Body minor Object int
Body micro Object int

(3)Config 对象

对应protobuf:

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

(4)Device 对象

对应protobuf:

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

(5)AdSlot 对象

对应protobuf:

optional uint32 adslot_width = 1; //广告物料宽
optional uint32 adslot_height = 2; //广告物料高
optional string topics = 3; // 选填 详情数值咨询技术人员...
required uint32 bidfloor= 4;//低价(单位:分)
optional AdType adtype = 5;  // 必填!广告类型
optional 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

(6)App 对象

对应protobuf:

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

(7)Geo对象

对应protobuf:

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

(8)Installpackages对象

对应protobuf:

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

3.1BidResponse

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

(2)BidResponse 对象

对应protobuf:

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

(3)Bid 对象

对应protobuf:

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

注意:当InteractionType 等于HTML时,如果曝光和点击字段存在数值,这种情况必须也要进行上报。

参数 类型
Body Href Object string
Body show_url Object string
Body click_url Object string
Body down_url Object string
Body install_url Object string
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 interaction_type Object InteractionType

4 错误码详情

错误码 解释
0 正常返回
1000 无广告返回
2000 配置信息不正确
3000 API版本号信息错误
4000 Device 对象配置错误
5000 AdSlot 对象配置错误

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,不上报,也不会纳入收益数据

以上所用的媒介类型,所有的参数请以XinGuoV2.0.4.proto为准。