// Tanx广告广告请求数据接口  
// 字段详尽解释请参见 http://sps.corp.alimama.com/ad/ADExchange/DocLib/Tan(X)%20Exchange%20API-PF.pdf  
  
package Tanx;  
  
message BidRequest {  
  
    //------------------------------------------- 协议基础信息  
  
    // 协议版本号, 现在我们支持的版本号为3  
    required int32 version = 1;  
  
    // Tanx系统生成的唯一的竞价ID, 32字节的字符串  
    required string bid = 2;  
  
    //如果属实，那么这是一个测试要求。  
    //DSP 需要反回正常的BidResponse  
    //但是结果是不显示给用户，DSP不会收到一个响应  
    optional uint32 is_test = 11 [default = 0];  
  
    //如果属实，那么这个要求的目的是衡量网络延迟。  
    //DSP需要返回一个空的BidResponse  
    optional uint32 is_ping = 12 [default = 0];  
  
    //------------------------------------------- 浏览者信息  
  
    // tanx系统对于cookie的加密结果, 长度为12个字节  
    // 对于阿里系的DSP, 该字段为未加密的acookie, 长度为24个字节  
    optional string tid = 3;  
  
    // 访问者的IP地址, ipv4 如：192.168.1.1  
    optional string ip = 4;  
  
    // 访问者的代理浏览器类型  
    // 原始用户UA  
    optional string user_agent = 5;  
  
    // 用户时间偏移量   
    // 举个例子, 东八区 timezone_offset = 60 * 8 = 480.  
    optional int32 timezone_offset = 13;  
  
    // 用户垂直类别  
    // 预留字段, 本期留空  
    repeated int32 user_vertical = 14;  
  
    // cookie版本号  
    // tid 字段的版本号  
    optional uint32 tid_version = 19;  
  
    //------------------------------------------- 网页信息  
  
    // 流量来源网站主不要的目标跳转url, 多值  
    // 最大200个字节  
    repeated string excluded_click_through_url = 6;  
  
    // 来源url， 对于没有匿名设置的网站该字段被设置  
    // 对于设置了匿名投递网站, 我们使用anonymous_id  
    optional string url = 7;  
  
    // 网页网站分类  
    // 参见数据字典 Tanx字典文件-网站类别.txt 定义  
    optional uint32 category = 8;  
  
    // 流量所属来源: 区别不同的adx平台  
    // 0: Tanx原生流量 1: Google流量  
    // 参见数据字典 Tanx字典文件-流量来源.txt 定义  
    optional uint32 adx_type = 9 [default = 0];  
  
    // 来源url, 对于设置了域名投递的网站使用这个字段。  
    // 直接使用google的数据  
    optional string anonymous_id = 15;  
  
    // 遵循 ISO 639-1语言编码标准 双字母代码  
    // 比如 en zh ja  
    optional string detected_language = 16;  
  
    // 网站垂直分类的版本号  
    // category 字段版本号  
    optional int32 category_version = 18;  
  
    //------------------------------------------- 广告位信息  
  
    message AdzInfo {  
        // id: 页面广告位编号，从0开始递增  
        // 在返回的时候我们会根据这个字段匹配广告  
        required uint32 id = 1;   
  
        // tanx系统分配广告位的唯一标识  
        // 为当前广告位的pid(阿里内部), 如流量提供方为非阿里系,则此pid为流量提供方在阿里系的虚拟pid  
        required string pid = 2;   
  
        // 广告位的尺寸: widthxheight e.g.200x300  
        optional string size = 3;  
  
        // Tanx建议DSP返回的参与竞价的广告的个数  
        // 默认为2,DSP可以提供小于等于此数据的广告个数,Tan(X)或获取相应的数量广告竞价(竞价结果只有一个胜出)  
        // 给外部的 ad_bid_count 为 1  
        optional uint32 ad_bid_count = 4 [default = 2];  
  
        // 展现形式  
        // 参见数据字典 Tanx字典文件-展现形式.txt 定义  
        // 1 页面固定广告位、2 弹窗广告位、3 页面漂浮广告位  
        repeated uint32 view_type = 5;  
  
        // 屏蔽的创意类型   
        // 参见数据字典 Tanx字典文件-广告创意类型.txt 定义  
        // 1 文字 2 图片 3 Flash 4 视频 5 文字链 6 图文(iframe方式引用) 7 JS广告牌 8 HTML广告 9 Flash不遮盖(动态Flash)  
        repeated uint32 excluded_filter = 6;  
  
        // 流量最低竞标价格, DSP出价需要不小于这个值, 单位为分, 只支持人民币  
        optional uint32 min_cpm_price = 7;  
  
        // 广告位相对位置，已经废弃，请使用view_screen字段  
        // 0：未被检测; 1: 在首屏; 2:不在首屏  
        enum Location {  
            NA = 0;  
            FIRST_VIEW = 1;  
            OTHER_VIEW = 2;  
        }  
        optional Location adz_location = 8 [default = NA];  
  
        // 扩充的广告位相对位置  
        // 0: 无数据; 1-5: 第1-5屏; 6: 第六屏及以外  
        enum ViewScreen {  
            SCREEN_NA     = 0;  
            SCREEN_FIRST  = 1;  
            SCREEN_SECOND = 2;  
            SCREEN_THIRD  = 3;  
            SCREEN_FOURTH = 4;  
            SCREEN_FIFTH  = 5;  
            SCREEN_OTHER  = 6;  
        }  
        optional ViewScreen view_screen = 9 [default = SCREEN_NA];  
    }  
    repeated AdzInfo adzinfo = 10;  
  
    // 屏蔽的敏感类目  
    // 参见数据字典 Tanx字典文件-敏感类别.txt 定义  
    repeated int32 excluded_sensitive_category = 17;  
  
    // 屏蔽的广告行业类目  
    // 参见数据字典 Tanx字典文件-广告类别.txt 定义  
    repeated int32 excluded_ad_category = 20;  
}  
  
  
message BidResponse {  
  
    //------------------------------------------- 协议基础信息  
  
    // 协议版本号, 现在我们支持的版本号为3  
    required int32 version = 1;  
  
    // BidRequest中传过来的bid, 32字节的字符串  
    required string bid = 2;  
  
    //------------------------------------------- 广告信息  
  
    // 广告定义  
    message Ads {  
        // id: 页面广告位编号，需要跟BidRequest中的AdzInfo里的id相对应  
        required uint32 adzinfo_id = 1;  
  
        // 计划的最高竞标价格, 单位为分  
        // 千次展现金额  
        required uint32 max_cpm_price = 2;  
  
        // 每个广告位需要的广告索引,默认为0开始递增,不能超过ad_bid_count数量  
        optional uint32 ad_bid_count_idx = 3;  
  
        // 广告代码片段(aloc)  
        optional string html_snippet = 4;  
  
        // 广告的目标跳转地址  
        // 需要http://或者https://协议头  
        repeated string click_through_url = 5;  
  
        // 广告行业敏感类目和行业类目  
        // 填充返回广告所属的敏感类目id和广告类目id  
        // 如果返回的广告属于敏感类目，请按照数据字典中(敏感类别.txt)的敏感类别id进行填充  
        // 如果返回的广告属于某些广告行业类目，请按照数据字典中(广告类别.txt)的类别id进行填充  
        // Tanx会验证此字段是否与BidRequest中的excluded_sensitive_category字段和excluded_ad_category字段有交集.  
        repeated int32 category = 6;  
  
        // 广告创意类型  
        // 参见数据字典 Tanx字典文件-广告创意类型.txt 定义  
        // 1 文字 2 图片 3 Flash 4 视频 5 文字链 6 图文(iframe方式引用) 7 JS广告牌 8 HTML广告 9 Flash不遮盖(动态Flash)  
        repeated int32 creative_type = 7;  
  
        // network自定义id  
        // only in [_0-9a-zA-Z]  
        // max_length: 128  
        optional string network_guid = 8;  
  
        // DSP需要传递的额外自定义数据  
        // Tanx会在竞价反馈的时候将该字段反馈给DSP  
        // 不可以使用的分隔符为字符G，'\007'  
        // max_length: 128  
        optional string extend_data = 9;  
  
        // 为广告的目标页面的url地址  
        // 并且必须以http://或者https://开头.  
        // destination_url必须是不经过任何加密或者跳转的最终目标地址  
        repeated string destination_url = 10;  
  
        // 广告创意ID  
        // 该字段由DSP设置，用于标记创意的审核状态，长度不超过64字节  
        // 若不同的创意被设置相同的ID，其中某个创意发生问题会导致所有相同ID的创意被拒绝投放  
        // 若同一个创意被设置了不同的ID，会导致该创意被拒绝投放或整个账户被拒绝投放  
        // 该字段不能包含回车换行以及其他不可见字符  
        optional string creative_id = 11;  
    }  
    repeated Ads ads = 3;  
}  
  
  
//只有竞价成功的时候Tanx才会向DSP发送BidResult  
  
message BidResult {  
  
    //------------------------------------------- 协议基础信息  
  
    // 协议版本号, 现在我们支持的版本号为3  
    required int32 version = 1;  
  
    // BidRequest中传过来的bid, 32字节的字符串  
    required string bid = 2;  
  
    //------------------------------------------- 竞价结果信息  
  
    message Res {  
        // id:  下标，从0开始递增(新增)  
        required uint32 adzinfo_id = 1;  
  
        // 每个广告位需要的广告索引,默认为0开始递增,不能超过adcount数量  
        optional uint32 ad_bid_count_idx = 2;  
  
        // 因为Tanx只会向竞价成功的请求发送反馈  
        // 所以这个code只会有0  
        optional int32 result_code = 3 [default = 0];  
  
        // 竞标成功价格 ,单位为分  
        // Tanx会向DSP要的价格，千次展现金额  
        optional uint32 result_price = 4;  
  
        // DSP在竞价过程中发送给Tanx的extend_data字段  
        optional string extend_data = 5;      
    }  
    repeated Res res = 3;  
}