ADFOX SSP v.1.2 : Протокол обмена данными для RTB продажи трафика. Общее описание системы.
1 ADFOX SSP v.1.2 : Протокол обмена данными для RTB продажи трафика. Общее описание системы. ADFOX SSP (sell side platform) продукт для владельцев сайтов, который позволяет им автоматизировать продажи негарантированного (остаточного) трафика и больше зарабатывать на этих продажах. При возможности показа рекламы ADFOX SSP посылает запросы параллельно к нескольким потенциальным покупателям рекламным сетям или DSP системам. Формат данного запроса описывается в данном документе. Потенциальные покупатели подбирают рекламу, подходящую для данного запроса и возвращают ответ, содержащий ставку и ссылку для показа рекламы, которая должна быть запрошена в случае выигрыша аукциона. Результаты ставок внешних покупателей сравниваются с внутренними кампаниями, претендующими на данный запрос, выбирается победитель, чья реклама и показывается на странице. В текущей версии ADFOX SSP владелец сайта в момент начала работы должен иметь акаунты во всех сетях/dsp, претендующих на трафик. В будущем в рамках интерфейса ADFOX SSP возможна реализация формы регистрации новой площадки в сети/dsp через интерфейс SSP. Взаиморасчеты и выплаты между конечной площадкой, которая использует SSPрешение ADFOX, и сетями/dsp осуществляются напрямую через ADFOX. Перед началом работы с каждым из потенциальных покупателей настраивается синхронизация id пользователей ADFOX SSP и сети/dsp. Варианты синхронизации обсуждаются с каждой сетью/dsp, с которыми происходит интеграция. Предпочтительным является вариант, когда потенциальный покупатель (сеть/dsp) предоставляет ссылку, в которую со стороны ADFOX передает id пользователя. В дальнейшем при каждом запросе за ставкой происходит передача id пользователя в ADFOX, по которому сеть/dsp соотносит его с id пользователя в своей системе. Ниже описывается протокол обмена данными что передается при запросе на ставку, допустимые варианты запроса. Протокол основывается на базе Open RTB 2.0
2 ( rsion2.0_final.pdf&can=2&q=), некоторые необязательные по этому стандарту параметры передаются только частью паблишеров или для части запросов. Подобные параметры выделены дополнительно цветом. Примеры запроса и ответа приведены в конце документа. Транспорт: Базовым протоколом между ADFOX SSP и сетью/dsp является HTTP. Для запроса ставок используется HTTP POST. SSL не используется поскольку замедляет работу системы с одной стороны и не требуется, поскольку обмен данными происходит между серверами. Формат данных: JSON. В http запросе передается «Content-- Type: application/json. Также в запросе передается как custom параметром версия openrtb: x-- openrtb-- verision: 2.0 Подробное описание запроса за ставкой. Общее описание: Запрос за ставкой состоит из следующих объектов: Основной объект (bid request object); Объект показа (impression object); Объект баннер / видео (banner object / video object) в зависимости от формата рекламы. Видео-баннер является объектом баннер. Объект видео используется только для in-stream рекламы (pre-post-mid-paus-roll, overlay, etc.); Объект сайт (site object) описывает сайт, с которого происходит запрос за рекламой; Объект издатель (publisher object); Объект устройство (device object); Объект пользователь (user object). Данные объекты находятся в иерархической взаимосвязи между собой. Ниже представлена общая схема взаимосвязей между объектами запроса согласно стандарту OpenRTB 2.0.
4 отдельных объектов: Основной объект запроса (bid request object). Объект верхнего уровня, содержит базовые параметры запроса за ставкой. В ADFOX SSP содержит следующие параметры: id string - Уникальный id запроса за ставкой. imp Array of objects - Объект(ы) показа, допускается несколько, должен быть по крайней мере один. site object - Содержит описание сайта, с которого производится запрос. badv array of strings - Запрет на участие в аукционе определенных рекламодателей: домены верхнего уровня сайтов рекламодателей. user object - tmax Integer 120 Содержит данные о пользователе, которому может быть показана реклама. Максимальное время ожидания ставки в ответ на запрос. Указывается в милисекундах.
5 Объект показа (impression object). Объект imp содержит информацию по тому, что именно является предметом торга. В рамках одного запроса на ставку может содержаться несколько объектов показ, это применяется в том случае, если на торги выставляется одновременный показ на нескольких рекламных местах (синхронные показы рекламы). В большинстве случаев запрос на ставку содержит только один объект показ. id string - banner object - video object - bidfloor Float - Уникальный идентификатор объекта в рамках данного запроса за ставкой (от 1 и выше, при нескольких объектах imp). Ссылка на объект баннер. В рамках одного объекта imp может быть или banner, или video. Одновременное использование banner и video не допускается. Ссылка на объект видео. В рамках одного объекта imp может быть или banner, или video. Одновременное использование banner и video не допускается. Допустимая нижняя граница принимаемых ставок. bidfloorcur string RUB Валюта ставок.
6 Объект баннер (banner object). Описывает параметры возможного показа баннерной рекламы, является частью объекта «показ». Ниже в колонке «значение по» также указывается, как необходимо интерпретировать отсутствие заданных значений. w integer - Ширина в пикселях. h integer - Высота в пикселях. id string - Уникальный идентификатор баннера в рамках данного запроса (от 1 и выше, при нескольких объектах banner). battr Array of integer - Запрет на определенные типы форматов рекламы (например на автоматический расхлоп). Список доступных вариантов в Таблице 4. expdir Array of integer Не расхлопывается Указывает параметры для баннеров типа «расхлоп». Полный список допустимых значений см. в таблице 1.
7 Объект видео (video object). Обязательно включается в объект показ. Не может использоваться одновременно с объектом баннер на одном уровне. При этом объект баннер может быть включен в объект видео для обозначения баннеров, которые показывают одновременно с видео-форматами (companion ads). mimes Array of strings - Допустимые mime-type, например, video/x--flv. linearity integer - minduration integer - maxduration integer - protocol integer - Определяет, какого вида допустима видео-реклама. Полный список значений см. в таблице 2. Минимальная длительность видео-рекламы в секундах. Максимальная длительность видео-рекламы в секундах. Поддерживаемые протоколы ответа для ставок по видеорекламе. w integer - Ширина видео- плеера в пикселях. h integer - Высота видео- плеера в пикселях.
8 Объект сайт (site object). Содержит информацию о сайте, с которого происходит запрос на ставки. id string - name string - Внутренний идентификатор сайта в SSP. сайта (может быть кодировано по запросу издателя). domain string - Домен сайта. page string - URL страницы, на которой может быть показана реклама (может быть пустым значением ). publisher object - См. объект «издатель». Объект издатель (publisher object). id string - Внутренний издателя в SSP. идентификатор name string - издателя (может быть кодировано по запросу издателя). Объект устройство (device object). Используется для передачи технической информации о запросе. В том числе об ip адресе запроса. ip string - ua string - IP адрес, с которого идет запрос за рекламой. User agent браузера, с которого идет запрос за рекламой.
9 Объект пользователь (user object). Может передаваться дополнительно по согласованию площадки с конкретным покупателем трафика. Содержит информацию о пользователе, которому может быть совершен показ рекламы. id string - Id пользователя в ADFOX. buyeruid string - Id пользователя у потенциального покупателя трафика. yob integer - Год рождения пользователя. gender string - keywords string - Пол пользователя: M/F/U = Мужской/ Женский/ Неизвестно. Ключевые слова для характеристики пользователя. customdata string Дополнительные, не описанные выше, данные о пользователе, которые издатель захочет передавать в запросе. Справочные таблицы с указанием вариантов значений параметров в запросе приведены в конце данного документа.
10 Подробное описание ответа на запрос. Формат ответа: Ниже описан формат ответа на запрос ставок, который должен возвращаться от потенциального покупателя. В ответе должен содержаться как минимум один seatbid, содержащий ставку как минимум по одному объекту показ переданному в запросе. Если потенциальный покупатель по какой-либо причине принимает решение не делать ставку (no-bid), в ответ на запрос должен прийти ответ HTTP 204. Основной объект ответа (bid response object). Параметр id string Обязательный - ID запроса за ставкой. seatbid Array of objects Обязательный - Массив ставок по рекламным местам, выставленным на аукцион. Минимум 1 в ответе. bidid String Обязательный - ID ставки. Используется для трекинга на стороне покупателя. cur String Обязательный RUB Валюта ставки.
11 Seatbid object. Параметр bid Array of objects Обязательный - Массив ставок, каждая из которых относится к объекту «показ» в запросе ставок. Объект ответа (Bid object). В каждой ставке атрибут nurl должен содержать URL, который будет запрашиваться при выигрыше ставки. Данный URL при запросе должен также вернуть рекламное сообщение (html для баннеров, VAST XML для видео), которое будет отображено конечному пользователю. Т.е. используется схема Ad Served on the Win Notice согласно OpenRTB 2.0. Параметр id string Обязательный - ID ставки. impid string Обязательный - price float Обязательный - nurl string Обязательный - ID объекта «показ» к которому относится ставка. Ставка в CPM (с плавающей точкой, например, 40.43). URL, который будет запрошен при выигрыше ставки. adomain Array of sting Обязательный - Домен сайта рекламодателя, чья реклама участвует в аукционе. Также URL может содержать макросы, которые будут использоваться для передачи дополнительной информации об итоге аукциона. Список поддерживаемых макросов: $ - идентификатор запроса за ставкой; $ ID объекта «показ»; $ цена, по которой состоялся аукцион.