Данный документ описывает схему интеграции CLICKIO SSP (поставщика трафика, далее - CLICKIO) с партнёром-DSP (покупателем трафика, далее - DSP, партнёр) в рамках экосистемы OpenRTB

Текущая версия документа и протокола обмена данными: 2.3.1 от 07.08.2017

Предыдущая версия: 2.0, доступна по ссылке

Стандарт описан на сайте IAB:

https://www.iab.com/guidelines/real-time-bidding-rtb-project/ 

Ссылка на спецификации стандарта:

https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf 

Изменения в текущей версии

Общее описание процесса

Техническое описание

Шаг 1. Cookie matching

1.а. CLICKIO - инициатор мэтчинга

1.b. DSP - инициатор мэтчинга

Шаг 2. Bid request

Шаг 3. Bid response

Шаг 4. Отображение креатива, уведомление DSP о показе, обработка клика по креативу

Пример

Изменения в текущей версии

Bid request

Bid response

Общее описание процесса

CLICKIO предлагает партнёрским DSP выкупить доступное к показу баннерное место, для чего рассылает партнёрам запросы в соответствии со стандартом OpenRTB 2.0. Выигравший определяется путём аукциона второй цены, что означает что выигравший биддер платит стоимость 2го места аукциона.

0. CLICKIO и DSP определяются с базовыми настройками

1. CLICKIO и DSP проводят cookie matching

2. В момент загрузки пользователем страницы с подходящим CLICKIO отправляет запрос к DSP

3. В случае заинтересованности в показе DSP осуществляет ответ с деталями креатива (рекламодатель, максимальная ставка, ссылка на креатив)

4. CLICKIO осуществляет показ креатива выигравшего биддера с указанием цены показа

Техническое описание

Шаг 1. Cookie matching

Каждому немэтченному пользователю в рамках оговоренного интервала мэтчинга системы отправляют друг другу свои id пользователя. Таблица сопоставления может находиться как на стороне CLICKIO, так и на стороне DSP

1.а. CLICKIO - инициатор мэтчинга

        http://adlmerge.com/merge_gpsid/?sid=777&id=%%dsp_user_id%% 

        где %%dsp_user_id%% -- user_id в системе DSP

        sid выдаётся CLICKIO’ом

1.b. DSP - инициатор мэтчинга

        http://adlmerge.com/get_gpsid/?adl_partner_id=162&p_uid=%dsp_user_id% 

        где %%dsp_user_id%% -- user_id в системе DSP

            adl_partner_id выдаётся CLICKIO’ом

Шаг 2. Bid request

[необходим URL от DSP куда слать аукционные запросы]

При подходящем показе (учитывая все настройки из п.0) CLICKIO отправляет партнёру запрос на ставку (bid request) вида:

{

   "id":"6067479328203247616",

   "site":{

      "id":154996,

      "name":"not specified",

      "domain":"not specified",

      "page":"not specified",

      "ref":""

   },

   "user":{

      "id":"5968287750393726849",

      "buyeruid":"CAESEJ3-Svw8-oVvtXkU2FgKaxk"

   },

   "device":{

      "ip":"90.180.79.120",

          "geo":{

"lat":55.75220,

"lon":37.61560,

"country":"RUS",

"city":"",

"type":2

},

      "ua":"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.124 Safari/537.36",

      "flashver":"14.0.0"

   },

   "imp":[

      {

         "id":"2308733901406295",

         "banner":{

            "w":240,

            "h":400

         },

         "ext":{

            "type":"banner",

                 "ctr":0.03421,

 "format":"display",

            "adunit":"351678"

         },

         "bidfloorcur":"RUB",

         "bidfloor":2.0,

         "pmp":{

            "private_auction": 0,

            "deals": [

                                {

                                        "id": "123456",

                                        "at": 1,

                                        "bidfloor": 100,

                                        "bidfloorcur": "RUB"

                                },

                                {

                                        "id": "123457",

                                        "at": 1,

                                        "bidfloor": 120,

                                        "bidfloorcur": "RUB"

                                }

                        ]

         }

      },

      {

         "id":"2308733901406304",

         "banner":{

            "w":200,

            "h":200

         },

         "ext":{

            "type":"banner",

                 "ctr":0.03421,

 "format":"display",

            "adunit":"351678"

         },

         "bidfloorcur":"RUB",

         "bidfloor":2.0,

         "pmp":{

            "private_auction": 0,

            "deals": [

                                {

                                        "id": "123456",

                                        "at": 1,

                                        "bidfloor": 100,

                                        "bidfloorcur": "RUB"

                                },

                                {

                                        "id": "123457",

                                        "at": 1,

                                        "bidfloor": 120,

                                        "bidfloorcur": "RUB"

                                }

                        ]

         }

      },

      {

         "id":"2311594349625431",

         "banner":{

            "w":240,

            "h":400

         },

         "ext":{

            "type":"banner",

                 "ctr":0.03421,

 "format":"display",

            "adunit":"351678"

         },

         "bidfloorcur":"RUB",

         "bidfloor":2.0,

         "pmp":{

            "private_auction": 0,

            "deals": [

                                {

                                        "id": "123456",

                                        "at": 1,

                                        "bidfloor": 100,

                                        "bidfloorcur": "RUB"

                                }

                        ]

         }

      }

   ]

}

В случае, если на странице доступно к показу несколько блоков, все подходящие размеры для всех блоков будут перечислены в одном запросе, поэтому рекомендуется отвечать подходящей ставкой на все полученные imp.id.

В поле imp.ext.adunit указан уникальный ID блока в системе, рекомендуется агрегировать статистику именно по этому полю, а не по паре “домен-размер”.

Цены указываются в рублях в СРМ (float, разделитель - точка), при этом за выигравший показ будет списана сумма CPM/1000.

Шаг 3. Bid response

В ответ на запрос CLICKIO ожидает получить ответ, соответствующий спецификациям OpenRTB 2.0, например:

{

  "id":"14077208324079",

  "bidid":"0967231980dbe9a24747edd0a2bf97d60e6fe722",

  "cur":"RUB",

  "seatbid":[

    {

      "bid":[

        {

          "id":"2eba6a1ed66e43ea27c4efab209866c76fdffe71",

          "impid":"2308733901406304",

          "price":101,

          "nurl":"http://partner.com/uri/?price=${AUCTION_PRICE}",

          "adid":"87",

          "dealid":"123456",

          "crid":"87324246",

          "adm":"<iframe src=\"//partner.com/uri/?clickUrl=${CLICK_URL_ESC}\" width=\"240\" height=\"400\" allowtransparency=\"true\" marginwidth=\"0\" marginheight=\"0\" hspace=\"0\" vspace=\"0\" frameborder=\"0\" scrolling=\"no\"></iframe>",

          "adomain":[

            "advertiser.ru"

          ],

          "ext":{

            "w":200,

            "h":200

          }

        },

        {

          "id":"2eba6a1ed66e43ea27c4efab209866c76fdffe21",

          "impid":"2308733901406295",

          "price":2,

          "nurl":"http://partner.com/uri/?price=${AUCTION_PRICE}",

          "adid":"87",

          "crid":"87324246",

          "adm":"<iframe src=\"//partner.com/uri/?clickUrl=${CLICK_URL_ESC}\" width=\"240\" height=\"400\" allowtransparency=\"true\" marginwidth=\"0\" marginheight=\"0\" hspace=\"0\" vspace=\"0\" frameborder=\"0\" scrolling=\"no\"></iframe>",

          "adomain":[

            "advertiser.ru"

          ],

          "ext":{

            "w":240,

            "h":400

          }

        }

      ]

    }

  ]

}

Для корректной обработки ставки seatbid.bid.impid в биде должны соответствовать imp.id в реквесте.

Шаг 4. Отображение креатива, уведомление DSP о показе, обработка клика по креативу

URL отображаемого креатива (adm) должен на вход принимать ${CLICK_URL_ESC} - заэскейпленный URL системы CLICKIO, через который DSP должна пробрасывать все клики, произошедшие по отображённому креативу. Пример ${CLICK_URL_ESC}: http%3A%2F%2Fid154996.al12.luxup.ru%2Fok%2F8%2F3578248%2F534475%2F14%2F%3Fadd_url%3D1800%7EVIaDjsHW2tPSxNXS1x0_MU8KHUljCwIDPz45O-HdwdHRwcBTBBoPKgBdGxEdwtjcxtjIy8rHGcTd0NzLycDb0huQnIakU5GegIuds4mS1dkbnFSNsZiVk4u9iZbY2tAU0dTE3oKZh61enIqFrJmV3Qo2eEgXM0lkbkgEVAzc3c-chI6_no2WR4ZU19rc38eMhoevh0FGg4Wdr4GI2MMdFdjUl4SCqY-cgpiQoEmV1cHJl5iCc1aZk46SjJSMmZHYEQ%26ssp_landing%3D

После ${CLICK_URL_ESC} должен идти заэскейпленный URL, на который необходимо отправить пользователя после клика по креативу.

Пример

  1. DSP необходимо отправить пользователя на URL http://www.adlabs.ru/
  2. При отображении креатива CLICKIO подставляет http%3A%2F%2Fid154996.al12.luxup.ru%2Fok%2F8%2F3578248%2F534475%2F14%2F%3Fadd_url%3D1800%7EVIaDjsHW2tPSxNXS1x0_MU8KHUljCwIDPz45O-HdwdHRwcBTBBoPKgBdGxEdwtjcxtjIy8rHGcTd0NzLycDb0huQnIakU5GegIuds4mS1dkbnFSNsZiVk4u9iZbY2tAU0dTE3oKZh61enIqFrJmV3Qo2eEgXM0lkbkgEVAzc3c-chI6_no2WR4ZU19rc38eMhoevh0FGg4Wdr4GI2MMdFdjUl4SCqY-cgpiQoEmV1cHJl5iCc1aZk46SjJSMmZHYEQ%26ssp_landing%3D вместо ${CLICK_URL_ESC}
  3. DSP при обработке клика должна отправить пользователя на URL http://id154996.al12.luxup.ru/ok/8/3578248/534475/14/?add_url=1800~VIaDjsHW2tPSxNXS1x0_MU8KHUljCwIDPz45O-HdwdHRwcBTBBoPKgBdGxEdwtjcxtjIy8rHGcTd0NzLycDb0huQnIakU5GegIuds4mS1dkbnFSNsZiVk4u9iZbY2tAU0dTE3oKZh61enIqFrJmV3Qo2eEgXM0lkbkgEVAzc3c-chI6_no2WR4ZU19rc38eMhoevh0FGg4Wdr4GI2MMdFdjUl4SCqY-cgpiQoEmV1cHJl5iCc1aZk46SjJSMmZHYEQ&ssp_landing=http%3A%2F%2Fwww.adlabs.ru%2F

        где:

  1. После всех редиректов пользователь попадает на http://www.adlabs.ru/

nurl вызывается server to server в момент показа креатива, вместо ${AUCTION_PRICE} подставляется выигравшая ставка в рублях в СРМ (float, разделитель дробной части - точка). В момент показа со счёта DMP списывается сумма ${AUCTION_PRICE}/1000.