KSOADX-RTB接入文档

简要说明

本文档为WPS参照Open-RTB文档，根据自己的需求进行修改应用的版本，主要是精简了暂时用不到的一些规范内容。

KSOADX-RTB基础

KSOADX-RTB交互图

• 简要说明

  1.发起Bid Request请求广告资源

  2.回复Bid Response或者vast包括必要的广告资源

DATA Format

请求使用JSON格式

​x
Accept: application/json
Content-type: application/json; charset=utf-8
​

Bid Request说明

Bid Request 结构图

BidRequest对象

Imp 对象

Object:Banner 主要规范返回中iurl的尺寸。

Object:Device

Object: Deal 交易信息

Object: App 媒体信息

APP 媒体信息id的枚举值

Object:user 对象

Object:Address 主要规范地址

图片广告

Bid Response

BidResponse结构

Object:BidResponse

Object:SeatBid

Object:Bid

#####其中imprtrackurl或者clicktrackurl中需要返回价格的需要宏替换格式，格式为：http://www.kingsoft.com?price={price}

winnotice宏说明，格式：http://www.kingsoft.com?request_id={request_id}{bid}

#####宏替换的位置可以放在任何位置

价格加密

价格加密采用 google 自定义的加密机制

https://developers.google.com/ad-exchange/rtb/response-guide/decrypt-price#encryptionscheme

wiki：https://github.com/google/openrtb-doubleclick/wiki

java实例代码

xxxxxxxxxx
/**
 * Created by hzg on 2017/7/10.
 */
public class WinnoticeUtil {
    public static final byte[] KEY1 = "kingsoft".getBytes();
​
    public static final byte[] KEY2 = "adx".getBytes();
​
    public static final BigDecimal ZERO = new BigDecimal(0);
​
    public static final BigDecimal ONEHUNDRED = new BigDecimal(100);
​
    public static DoubleClickCrypto.Price clickCrypto = null;
​
    static {
        try {
            DoubleClickCrypto.Keys keys = new DoubleClickCrypto.Keys(
                new SecretKeySpec(KEY1, "HmacSHA1"),
                new SecretKeySpec(KEY2, "HmacSHA1")
            );
            clickCrypto = new DoubleClickCrypto.Price(keys);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
​
    public static String encrytPrice(BigDecimal price) {
        if (price == null) {
            price = ZERO;
        }
        return clickCrypto.encodePriceValue(price.multiply(ONEHUNDRED).doubleValue(), null);
    }
​
    public static String encrytPrice(String price) {
        if (price == null) {
            return encrytPrice(ZERO);
        }
        return encrytPrice(new BigDecimal(price));
    }
​
    public static String replacePrice(String url, Object... param) {
        if (StringUtils.isEmpty(url)) {
            return "";
        }
        return MessageFormat.format(url, param);
    }
​
    public static List<String> replaceUrls(List<String> urls, String price) {
        if (price == null) {
            return replaceUrls(urls, ZERO);
        }
        return replaceUrls(urls, new BigDecimal(price));
    }
​
    public static List<String> replaceUrls(List<String> urls, BigDecimal price) {
        List<String> replaceUrls = Lists.newArrayList();
        if (CollectionUtils.isEmpty(urls)) {
            return replaceUrls;
        }
        for (String url : urls) {
            replaceUrls.add(replacePrice(url, encrytPrice(price)));
        }
        return replaceUrls;
    }
​
    public static void main(String[] args) throws SignatureException {
        //加密
        String cryptoStr = clickCrypto.encodePriceValue(12,null);
        System.out.println(cryptoStr);
        //解密
        System.out.println(clickCrypto.decodePriceValue(cryptoStr));
    }
}
​
输出
XJwszwAM1ShpYgxpFjZCHnpjOT-uc5s7eH0PzA==
12
​

c++ 实例:

http://ads-web.ksosoft.com/doc/kingsoft/wps_price_decrypt_demo.rar

关于广告位信息

媒体广告位bidtype信息

图片说明:移动端图片仅支持jpg/jpeg/png；PC端有部分广告位支持jpg/jpeg/png/gif，若未特殊说明，所传图片均为1张，具体见上方广告位信息素材要求； 若投下载类广告，icon必传，icon尺寸为最低40px 40px大小，为了更好的显示效果建议icon尺寸为 100px 100px；若投首页缩略图，icon必传（否则会被过滤），图片尺寸：108*108。

注意: Banner中wmax，wmin会在每个广告位类型上上浮下浮15%,同理于hmax，hmin。建议使用appid和bidtype来匹配素材尺寸。

其他注意

connectiontype 取值

carrier 取值

请求Example

request

xxxxxxxxxx
{
  "id" : "b52c96bea30646abf8170f333bbd42b9",
  "test": 0,
  "tmax":2000,
  "deal":[{
    "bidfloor":"34",
    "chargetype":1,
  },{
      "bidfloor":"5600",
      "chargetype":2
    }],
  "app":{
    "id":"3",
    "name":"词霸Android",
    "bundle":"com.kingsoft.ciba",
    "ver":"9.0.298"
  },
  "imp": [
    {
      "banner": {
        "h": 250,
        "w": 300,
        "wmax": 1280,
        "hmax": 800,
        "wmin": 120,
        "hmin": 80,
        "bidtype":1
      }
    }
  ],
  "device": {
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2",
    "ip": "123.145.167.10",
    "make":"HUAWEI",
    "model":"HUAWEI NXT-AL10",
    "os":"Android",
    "osv":"6.0",
    "language": "zh",
    "carrier": "中国联通",
    "connectiontype":4,
    "dpidmd5":"84b7ba514e305ac102fc49189c4926ee",
    "macmd5":"84b7ba514e305ac102fc49189c4926ee",
    "imei","862591032242252"
  }
}

response

广告为APP下载

xxxxxxxxxx
{
  "id" : "b52c96bea30646abf8170f333bbd42b9",
  "seatbid":[
    {
      "bid":[{
        "id":"b42c96bea30646abf8170f333bbd42c0",
        "adomain":["jd.com","360buy.com"],
        "bundle":"com.jd.app",
        "iconurl":"http://www.jd.com/icon.png",
        "iurl":["http://www.jd.com/x.jpg"],
        "h":240,
        "w":320,
        "title":"京东618",
        "description":"京东618广告",
        "clickurl":"http://www.jd.com/x.html",
        "imprtrackurl":["http://www.jd.com/trackurl"],
        "clicktrackurl":["http://www.jd.com/clicktrackurl"],
        "price":3000,
        "chargetype":1,
        "isappdownload":1
      },{
        "id":"b42c96bea30646abf8170f333bbd42c5",
        "adomain":["jd.com","360buy.com"],
        "bundle":"com.jd.app",
        "iconurl":"http://www.jd.com/icon.png",
        "iurl":["http://www.jd.com/x.jpg"],
        "h":240,
        "w":320,
        "title":"京东618",
        "description":"京东618广告",
        "clickurl":"http://www.jd.com/x.html",
        "imprtrackurl":["http://www.jd.com/trackurl"],
        "clicktrackurl":["http://www.jd.com/clicktrackurl"],
        "price":3000,
        "chargetype":1,
        "isappdownload":1
      }]
    }
  ]
}
​

广告为图片展示类广告

xxxxxxxxxx
{
  "id" : "b52c96bea30646abf8170f333bbd42b9",
  "seatbid":[
    {
      "bid":[{
        "id":"b42c96bea30646abf8170f333bbd42c0",
        "adomain":["jd.com","360buy.com"],
        "bundle":"com.jd.app",
        "iurl":["http://www.jd.com/x.jpg"],
        "h":240,
        "w":320,
        "title":"京东618",
        "description":"京东618广告",
        "clickurl":"http://www.jd.com/x.html",
        "imprtrackurl":["http://www.jd.com/trackurl"],
        "clicktrackurl":["http://www.jd.com/clicktrackurl"],
        "price":3000,
        "chargeType":1,
        "isappdownload":0,
        "industry":[10001,10012],
        "style":[20001,20003],
        "winnotice":"http://xxx.com/winnotice?request_id={request_id}&bid={bid}&price={price}&ip={ip}&did={did}"
      },{
        "id":"b42c96bea30646abf8170f333bbd42c5",
        "adomain":["jd.com","360buy.com"],
        "bundle":"com.jd.app",
        "iurl":["http://www.jd.com/x.jpg"],
        "h":240,
        "w":320,
        "title":"京东618",
        "description":"京东618广告",
        "clickurl":"http://www.jd.com/x.html",
        "imprtrackurl":["http://www.jd.com/trackurl"],
        "clicktrackurl":["http://www.jd.com/clicktrackurl"],
        "price":3000,
        "chargeType":1,
        "isappdownload":0,
        "industry":[10001,10012],
        "style":[20001,20003],
        "winnotice":"http://xxx.com/winnotice?request_id={request_id}&bid={bid}&price={price}&ip={ip}&did={did}"
      }]
    }
  ]
}
​

图片广告无填充时

xxxxxxxxxx
{
  "id" : "b52c96bea30646abf8170f333bbd42b9"
}

WPS广告样式参考

• WPS Android 开屏

• WPS Android 信息流大卡、信息流三图卡

• WPS Android 信息流单图卡

• WPS Android 首页缩略图

• WPS iOS 开屏

• WPS iOS 信息流大卡

• WPS iOS 信息流单图卡

• WPS iOS 首页缩略图