Техническая спецификация на подключение к AdSniper DSP

 Версия 4.1. Дата изменений: 17.09.2014. Техническая спецификация на подключение к AdSniper DSP Оглавление 1 Введение 2 Запросы к DSP 2.1 Пример запроса к DSP 2.2 Ответы DSP 3 Матчинг юзеров 3.1. Односторонний матчинг по инициативе DSP 3.2. Односторонний матчинг по инициативе SSP 3.3. Двухсторонний матчинг 1 Введение
Документ описывает подключение SSP (Sell Side Platform) к AdSniper DSP (Demand Side Platform). Интерфейс DSP разработан в соответствии со спецификацией протокола OpenRTB v.2.0. 2 Запросы к DSP
Запрос к DSP представляет собой набор информации: ● о рекламной площадке, ● о посетителе этой рекламной площадки, ● об устройстве, с которого посетитель зашел, ● о списке рекламных мест под рекламу. Запрос к DSP должен быть представлен в json­формате и содержать HTTP­заголовок Content­Type: application/json. 1 2.1 Пример запроса к DSP
{ "site": { "id":"1178", "domain":"example.com", "cat":["IAB19­18"], "pagecat":["IAB19­18"], "page":"http://example.com/example.html", "ref":"http://example2.com/" }, "user": { "id":"b4a31fd031833f6a0039ae9ec327bb97", "buyeruid":"eef0235d35eef023a1eef02325c45d35", "geo": { "country":"UKR", "city":"Kiev" } }, "device": { "ua":"Opera/9.80 (Windows NT 6.1; Win64; x64)Presto/2.12.388 Version/12.14", "ip":"85.159.0.67", "devicetype":2, "language":"ru", "make":"", "model":"", "os":"WindowsNT", "osv":"6.1", "ext": { "screen": { "width":1600, "height":900, "colorDepth":32, "pixelDepth":32 }, "navigator": { "language":"ru", 2 "browserLanguage":"ru", "systemLanguage":"", "userLanguage":"ru", "platform":"Win64", "vendor":"", "timeZone":2, "date":"2013­03­15T14:22:23.898Z", "width":1567, "height":616, "plugins":["Java Deployment Toolkit 7.0.50.6","Java(TM) Platform SE 7 U5","Shockwave Flash","Java Deployment Toolkit 7.0.170.2","Java(TM) Platform SE 7 U17","Silverlight Plug­In","Google Update","Adobe Acrobat"], "flashVersion":"11.6.602" } } }, "cur":["RUB","USD"], "ext":{"ssp_id":"smaclick"}, "id":"DSP­SC­1­b4a31fd031833f6a0039ae9ec327bb97­136335734371499179.21589
221805", "imp": [ { "id":"IMP­SC­1­2442­136335734371370956.76348544657", "banner": { "btype":[], "battr":[], "mimes":["text/html","text/javascript"], "topframe":0, "w":240, "h":400 }, "instl":0, "bidfloor":0, "bidfloorcur":"RUB", "ext": { "teasersCount":4, "w":70, "h":70, "ad_settings": { "show_animation":1, 3 "show_brutal":1, "show_sex":1 }, "formatid": 102400400 } } ], "at":2, "allimps":0 } Полный список категорий площадок (поле cat объекта site), а так же список обязательных полей смотрите в RTB Project OpenRTB API Specification Version 2.0. В дополнение к списку обязательных полей для AdSniper DSP так же обязательными являются следующие: ● site.domain ● device.ip ● device.ua (обязателен в зависимости от текущих настроек таргетинга). Поле imp.ext.formatid отвечает за формат объявления. Список допустимых форматов следующий: ● 102400400 ­ ДСП на свое усмотрение вернет либо 4 тизера, либо баннер размером 240х400 ● 1102400400 ­ ДСП вернет баннер размером 240х400 ● если значение поля formatid совпадает со значением поля teasersCount (imp.ext.teasersCount), то ДСП вернет только тизеры. Причем количество тизеров ­ это значение поля teasersCount. Для запроса баннера без поля formatid достаточно указать размеры баннера и "types":["2"]. Где types: [], ­ тип рекламы (1 ­ тизерная (вернутся или тизеры, или баннер), 2 ­ баннерная, 3 ­ кликандер). 2.2 Ответы DSP
Пример валидного ответа DSP при запросе баннера: { "cur" : "RUB", "id":"DSP­SC­1­b4a31fd031833f6a0039ae9ec327bb97­136368036197012766.25816
244632", "seatbid" : 4 [ { "bid" : [ { "adm" : "<img width='0' height='0' border='0' src='http://example­dsp.com/click'><table cellpadding=\"0\" cellspacing=\"0\" border=\"0\" align=\"center\" width=\"240px\" height=\"400px\"><tr><td>\n<object classid=\"clsid:d27cdb6e­ae6d­11cf­96b8­444553540000\" width=\"240\" height=\"400\" id=\"240x400\" align=\"middle\"><param name=FlashVars value=\"href=http://example­dsp.com/click\" /><param name=\"movie\" value=\"http://example­dsp.com/240x400/Banner.swf\" /><param name=\"quality\" value=\"high\" /><param name=\"bgcolor\" value=\"#ffffff\" /><param name=\"play\" value=\"true\" /><param name=\"loop\" value=\"true\" /><param name=\"wmode\" value=\"window\" /><param name=\"scale\" value=\"showall\" /><param name=\"menu\" value=\"true\" /><param name=\"devicefont\" value=\"false\" /><param name=\"salign\" value=\"\" /><param name=\"allowScriptAccess\" value=\"sameDomain\" />\n<!­­[if !IE]>­­>\n<object type=\"application/x­shockwave­flash\" data=\"http://example­dsp.com/240x400/Banner.swf\" width=\"240\" height=\"400\"><param name=FlashVars value=\"href=http://example­dsp.com/click\" /><param name=\"movie\" value=\"http://example­dsp.com/240x400/Banner.swf\" /><param name=\"quality\" value=\"high\" /><param name=\"bgcolor\" value=\"#ffffff\" /><param name=\"play\" value=\"true\" /><param name=\"loop\" value=\"true\" /><param name=\"wmode\" value=\"window\" /><param name=\"scale\" value=\"showall\" /><param name=\"menu\" value=\"true\" /><param name=\"devicefont\" value=\"false\" /><param name=\"salign\" value=\"\" /><param name=\"allowScriptAccess\" value=\"sameDomain\" />\n<!­­<![endif]­­>\n<a href=\"http://www.adobe.com/go/getflash\"><img src=\"http://www.adobe.com/images/shared/download_buttons/ge
t_flash_player.gif\" alt=\"Get Adobe Flash player\" /></a>\n<!­­[if !IE]>­­>\n</object>\n<!­­<![endif]­­>\n</object></td></tr></
table>", "id" : "1727", "impid" : "IMP­SC­1­2455­136368036197037025.277968496084", "nurl" : "", 5 } "price" : 0.3625152666106872 } ] } ] Пример валидного ответа DSP при запросе тизера: { "cur" : "RUB", "id" : "DSP­SC­1­b4a31fd031833f6a0039ae9ec327bb97­136335734371499179.2158922180
5", "seatbid" : [ { "bid" : [ { "ext" : { "ad_html" : "<img width='0' height='0' border='0' src='http://example­dsp.com/track'>", "teasers" : [ { "ad_html" : "", "lb_click_url" : "http://example­dsp.com/click1", "lb_img_url" : "http://example­dsp.com/img/1.jpg", "lb_title" : "Ешь КИВИ и Худей на 7кг за неделю! Надо только.." } ] }, "id" : "0", "impid" : "IMP­SC­1­2442­136335734371370956.76348544657", "nurl" : "", "price" : 0.0010 } ] } ] } В поле price указывается стоимость бида, то есть цена за 1000 показов. В поле nurl указывается URL, который необходимо вызвать для оповещения о победе данного бида. Например, "nurl" : 6 "http://dsp­nurl.adsniper.ru/?ssp_bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}
&ssp_imp=${AUCTION_IMP_ID}&bid=DSP­SC­1­0c89db94f6e024c9a51b9bf7298b0a5e­13584
9943476097686.50149926543&dsp_price=4.3811612612741078&imp=IMP­SC­1­2431­13584
9943476040360.74106115848&ssp=smaclick" где: Параметр Значение Описание ssp_bid ${AUCTION_BID_ID} идентификатор бида, данное значение
подставляется при вызове nurl макросом на стороне SSP. price ${AUCTION_PRICE} поле со значением win price ­ окончательной ценой выигравшего бида, то есть итоговая сумма для списания за данный бид (1000 показов). Подставляется при вызове nurl макросом на стороне SSP. ssp_imp ${AUCTION_IMP_ID} ID рекламного места, данное значение подставляется при вызове nurl макросом на стороне SSP. bid DSP­SC­1­0c89db94f6
e024c9a51b9bf7298b0
a5e­135849943476097
686.50149926543 bid ID, значение подставляется на стороне DSP. dsp_price 4.3811612612741078 цена за бид, предложенная DSP. Значение подставляется на стороне DSP. imp IMP­SC­1­2431­13584
9943476040360.74106
115848 ID рекламного показа, значение подставляется на стороне DSP. ssp smaclick идентификатор SSP, значение подставляется на стороне DSP. Корректный итоговый вызываемый nurl должен содержать одинаковые значения в следующих полях соответственно: ● ssp_bid должен быть равен bid, ● ssp_imp должен быть равен imp. 7 3 Матчинг юзеров
Существует три варианта синхронизации юзеров между DSP и SSP: 1. односторонний по инициативе DSP, 2. односторонний по инициативе SSP, 3. двухсторонний. Для тех SSP, которые хранят у себя соответствие, характерны все 3 вида синхронизации ID юзеров. А для тех SSP, которые не хранят у себя соответствие, характерны только первый и второй виды матчинга. 3.1. Односторонний матчинг по инициативе DSP
В случае одностороннего матчинга по инициативе DSP, DSP размещает код вызова URL на странице, которую открывает посетитель, куку которого необходимо синхронизировать: http://this_ssp.ru/dspuid?dsp=${DSP_ID}, где DSP_ID ­ идентификатор DSP, который она получает при регистрации в SSP. SSP отвечает на данный вызов редиректом на http://yourdsp.com?ID=${SSP_UID}, подставляя свой ID юзера вместо ${SSP_UID}. Таким образом, DSP получает свою куку при вызове данного URL и ID пользователя SSP параметром в URL. Далее DSP сохраняет у себя соответствие. 3.2. Односторонний матчинг по инициативе SSP
В случае одностороннего матчинга по инициативе SSP происходит следующее: SSP для конкретного ID пользователя вставляет вместе с отображаемой на странице рекламой код вызова URL DSP http://yourdsp.com?ID=${SSP_UID}, при этом подставляя свой ID пользователя вместо ${SSP_UID}. DSP получает свой ID юзера при вызове данного URL и ID пользователя SSP параметром в URL. Далее DSP сохраняет у себя соответствие. 8 3.3. Двухсторонний матчинг
В случае двухстороннего матчинга в начале DSP встраивает код вызова URL на странице, которую открывает посетитель, куку которого необходимо синхронизировать: http://this_ssp.ru/dspuid?dsp=${DSP_ID}, SSP со своей стороны отвечает на данный вызов редиректом на http://yourdsp.com?ID=${SSP_UID}, подставляя свой ID юзера вместо ${SSP_UID}, а также встраивая код вызова URL DSP. При вызове данного URL DSP получает свой ID юзера (куку) и ID пользователя SSP параметром в URL, после чего DSP сохраняет у себя соответствие. Далее DSP делает редирект на SSP при этом подставляя в URL свой ID юзера (для установки аналогичного соответствия на стороне SSP). 9