优量汇Server Bidding接口文档

1 交互流程

1.1 广告请求和返回流程

STEP1：流量方App调用优量汇SDK接口获取请求buyerId和SDKInfo用于从优量汇后端获取竞价信息
STEP2：流量方ADX携带buyerId和SDKInfo信息请求优量汇后台
STEP3：优量汇后台返回流量方adx竞价回包，其中包含竞价信息和sdk渲染广告的token
STEP4：流量方ADX完成比价后，上传竞价成功/失败及扣费等信息给优量汇后台服务
STEP5：流量方APP使用竞价回包中的token调用优量汇SDK展示广告接口
STEP6：流量方APP调用优量汇SDK曝光上报接口回传竞胜价格

备注：

（1） STEP4和STEP5无严格顺序，且竞价失败后不需要进行STEP5和6；
（2） STEP3开发者收到竞价回包与STEP5使用token拉取广告回包的时延不可超过90s，否则可能无法拉取广告回包；
（3） STEP1和STEP2中获取和携带SDKInfo信息为必传参数，缺失将影响推荐效果，用于优量汇SDK各版本新增功能支持信息补充，建议开发者获取并上传，可及时支持SDK后续迭代版本功能，提升变现效果。

2 接口协议

2.1 调用YLH SDK获取竞价请求buyerID和SDKInfo

• 详见 iOS 接入文档
• 详见 Android 接入文档

2.2 Server端竞价请求协议

2.2.1 竞价请求

采用OpenRTB协议

• 请求路径： https://mi.gdt.qq.com/server_bidding

• 请求方式： POST

• 请求头：

  Content-Type: application/json
  Accept: application/json
  

• Bid请求

• Imp对象

• 视频对象

• 应用程序对象

• 设备对象

• 设备ext对象
  备注：设备ext对象会做校验，ios如无上传信息，可以上传空对象

• 地理对象

• ext对象

2.2.2 竞价响应

• 回包Header

  Content-Type: application/json 
  X-OpenRTB-Version: 2.5或2.3
  

• BidResponse

• SeatBid 对象

• Bid Object

2.2.3 示例

• 请求示例

  {
    "id": "5f0417f6354b680001e94518",
    "imp": [{
        "id": "1",
        "video": {
            "minduration": 0,
            "maxduration": 46,
            "w": 720,
            "h": 1422,
            "linearity": 1,
            "minbitrate": 250,
            "maxbitrate": 15000
        },
        "tagid": "9040714184494018",
        "bidfloor": 1.00,
        "bidfloorcur": "CNY",
        "secure": 1
    }],
    "app": {
        "id": "5afa947e9c8119360fba1bea",
        "name": "VungleApp123",
        "bundle": "com.qq.e.union.demo.union"
    },
    "device": {
        "ua": "Mozilla/5.0 (Linux; Android 9; SM-A207F Build/PPR1.180610.011; wv) AppleWebKit/537.36 KHTML, like Gecko) Version/4.0 Chrome/74.0.3729.136 Mobile Safari/537.36",
        "geo": {
            "lat": -7.2484,
            "lon": 112.7419
        },
        "ip": "115.178.227.128",
        "devicetype": 1,
        "make": "samsung",
        "model": "SM-A207F",
        "os": "android",
        "osv": "9",
        "h": 1422,
        "w": 720,
        "language": "en",
        "connectiontype": 2,
        "ifa": "dd94e183d8790d057fc73d9c761ea2fa",
        "ext": {
            "oaid": "0176863C3B9A5E419BCAF702B37BEFB38B8D05CEA84022FB76BD723BA89D2ED2116F960A73FE1FFB12499E31EF664F5EAE87386F19D8A41390FEBAA5362042BC7A601D4CB006DA4E66"
        }
    },
    "cur": ["CNY"],
    "ext": {
        "buyer_id": "W8IBAhGgFP7LXv2b8wdmSDwVBeBShqIq5gV7fO7-6dP0Pof9HwP0UvxvXRc5D-zMao8rh3m6nuPyI_BCZ52zddpY1-itIMyUmeQXRePiNiIeXpNW4vn6kzlrVHwfVvVfNNHaI_FwczJQZSE4rKF-W2VwFrPM8ISY5hJytk6mWpDt_CIGCx4u9nDTdXFUISduddvJJzHsHRrB6VbtwX3vaKG2d0Y"
    }
  }
  

• 竞价阶段回包-只返回竞争监测链接相关出价信息

• 参与竞价回包示例

  {
    "bidid": "sgorcyoria55s",
    "cur": "CNY",
    "id": "5f0417f6354b680001e94518",
    "seatbid": [{
        "bid": [{
            "bundle": "",
            "cid": "1954948",
            "crid": "1366623",
            "h": 1920,
            "id": "aiknzfwzv345a01",
            "impid": "1",
            "lurl": "https://win.gdt.qq.com/win_notice.fcg?adx_id=6&viewid=ZVcbrgjA7F4NkZu!F3oy4Q3cMNg6wnvSuCwsYpCfPiD1IhGmO5P6aZBdP8r_9udpyWjmXGaOq8b_vQXvPn3MtShVFpZc07qHqTihtZ!rd_Ajsl4RZNYCGtMdmGGGed!f7nosRPUks9LzrvvSmOGgFuuIX0xHS3Xhzb078GHynEz9SpZo!jyUlXvxPMMpBctuknggFEbMhXh42I8wZDt9UNGbomUi4r2b3k2b!oKnz5uuZmWYdyWqu9DFJ5pIqmeNZA0ROFpxGg0212l91GKRkc7nAPhyNt6uujLLAYYHpuoVyeumBhuO3Hqw5Qbx1yA97HspxciEJQrgJcYkQ2WIqET1UffM8wBLXDgJQMz7BX4&win_price=${AUCTION_PRICE}&server_bidding_type=1&win_seat=${AUCTION_SEAT_ID}&loss=${AUCTION_LOSS}&exchange_rate=6.46",
            "nurl": "https://win.gdt.qq.com/win_notice.fcg?adx_id=6&viewid=ZVcbrgjA7F4NkZu!F3oy4Q3cMNg6wnvSuCwsYpCfPiD1IhGmO5P6aZBdP8r_9udpyWjmXGaOq8b_vQXvPn3MtShVFpZc07qHqTihtZ!rd_Ajsl4RZNYCGtMdmGGGed!f7nosRPUks9LzrvvSmOGgFuuIX0xHS3Xhzb078GHynEz9SpZo!jyUlXvxPMMpBctuknggFEbMhXh42I8wZDt9UNGbomUi4r2b3k2b!oKnz5uuZmWYdyWqu9DFJ5pIqmeNZA0ROFpxGg0212l91GKRkc7nAPhyNt6uujLLAYYHpuoVyeumBhuO3Hqw5Qbx1yA97HspxciEJQrgJcYkQ2WIqET1UffM8wBLXDgJQMz7BX4&win_price=${AUCTION_PRICE}&server_bidding_type=1&exchange_rate=6.46&highest_loss_price=${HIGHEST_LOSS_PRICE}",
            "price": 39.62,
            "w": 1080
        }],
        "seat": "Tencent"
    }]
  }
  

• 不参与竞价回包示例

  {"id": "1234567890", "nbr": 10001} //nbr为不参加竞价原因错误码
  

错误码含义请见：https://e.qq.com/dev/help_detail.html?cid=2911&pid=7902

我们提供了在线联调测试工具，对于常见问题，会在返回中提示问题原因，并提供改进建议，提高接入效率，平台地址是：https://utest.gdt.qq.com/devtool/#/tool/stos。

平台需要登录，请使用开发者平台账号登录即可。

2.3 调用优量汇SDK展示广告接口

• 详见 iOS 接入文档
• 详见 Android 接入文档

2.4 竞价成功/失败上报

宏替换：替换=后面整体字符串，例如${AUCTION_LOSS}替换为1

"nurl":"https://win.gdt.qq.com/win_notice.fcg?adx_id=6&viewid=&win_price=${AUCTION_PRICE}&server_bidding_type=1&highest_loss_price=${HIGHEST_LOSS_PRICE}"

"lurl":"https://win.gdt.qq.com/win_notice.fcg?adx_id=6&viewid=&win_price=${AUCTION_PRICE}&server_bidding_type=1&win_seat=${AUCTION_SEAT_ID}&loss=${AUCTION_LOSS}"

• AUCTION_PRICE：竞胜价格，单位：分/千次，精度为小数点后两位，例如：10.12。注：要求使用RSA加密算法进行加密，之后进行base64编码，编码后再进行URL编码
  申请RSA加密公钥请咨询优量汇技术支持或运营经理

• HIGHEST_LOSS_PRICE：竞胜时其他参竞方的最高出价。注：要求使用RSA加密算法进行加密，之后进行base64编码，编码后再进行URL编码
  申请RSA加密公钥请咨询优量汇技术支持或运营经理

• AUCTION_SEAT_ID：竞胜方来源，枚举值为

• AUCTION_LOSS：失败原因 ，枚举值为：