Руководство по интеграции Vungle OpenRTB 2.3

Это версия 2.1.0 (август 2017 г.) руководства по информации Vungle OpenRTB 2.3. В этой строке приводятся подробные сведения по выполнению интеграции с Vungle Exchange с помощью OpenRTB 2.3.

Содержание

1. Запрос и ответ

1.1 Сущности

Все сущности в этом разделе представляют собой подмножество спецификации OpenRTB 2.3.1; при отсутствии каких-либо полей или требований, следует использовать требования по умолчанию данной спецификации.

1.2 Расширение

В целях улучшения обслуживания рекламы Vungle Exchange предоставляет информацию, выходящую за пределы стандартного протокола OpenRTB. Эти расширения не перекрывают, а скорее дополняют существующую реализацию OpenRTB. Расширения разбиты на отдельные объекты (там, где это имеет наибольший смысл).

Все поля расширений инкапсулированы в объект JSON с помощью поля расширения первого уровня с именем 'vungle' объекта OpenRTB 'ext'. Для простоты в последующих разделах этого документа поле 'vungle' опущено. Ниже приводится пример объекта OpenRTB JSON, содержащего расширения Vungle:

{
...
"ext": {
"vungle": {
// Individual extension fields at various rows below.
}
}
}

Например, объект запроса предложения верхнего уровня может выглядеть примерно так:

{
"id": "572c3535ab0af400011a721a",
"imp": [{<impression object>}],
"app": {<application object>},
"device": {<device object>},
"user": {<user object>},
"at": 2,
"tmax": 2000,
"cur": ["USD"],
"bcat": ["IAB7-3"],
"badv": ["google.com"],
"ext": {
"vungle": {
"badvid": ["2f00ca35ab0abe4df11da700c"]
}
}
}

1.3 Версии

Со временем некоторые поля могут устаревать, поэтому в целях обеспечения максимальной совместимости Vungle Exchange будет учитывать все "потерявшие актуальность" поля, указанные в самой последней спецификации Vungle OpenRTB. Все такие поля планируется удалять при следующем обновлении спецификации, после чего Vungle Exchange больше не будет нести ответственности за поддержку устаревших полей.

Все удаленные поля будут оставаться в спецификации с пометкой "deleted" (удалено), указывая на то, что данное поле больше не поддерживается. Мы используем метку "deleted", чтобы дополнить и закрепить семантику спецификации: Каждое определенное когда-либо поле остается уникальным для области, для которой оно было определено, пока данная спецификация остается в силе. Это означает, что если поле 'id' когда-либо устареет и будет удалено в какой-либо конкретной спецификации, оно никогда не будет снова использовано в будущей редакции с другим значением.

1.3.1 Семантические версии

Версии спецификации также будут следовать рекомендациям Semver 2.0.0, а именно:

  • При значительном обновлении версии может нарушаться обратная совместимость; пример: поле "устаревшее" в версии X, "удаляется" в версии X+1.
  • В небольшом обновлении версии обратная совместимость не нарушается; примеры: используемое поле, помеченное как "deprecated" (устаревшее); или обязательное поле, помеченное как необязательное и устаревшее.
  • Обновление с исправлением версии должно не нарушать обратную совместимость; пример: исправление орфографической ошибки в описании спецификации.

1. Запрос

2.1 Обязательные и необязательные поля

Замечания о столбце Обязательное в последующих разделах:

  • Да: при последующем потреблении такого поля всегда предполагается наличие правильно отформатированного непустого значения на основе указанного типа.
  • Нет: при последующем потреблении не предполагается наличие такого поля или проверка правильности соответствующего значения. Обязательная проверка потребителя по значению не требуется для этого типа.
  • По умолчанию: все неупомянутые поля в OpenRTB 2.3.1 по умолчанию относятся к необязательным.

2.2 Согласование протоколов

Vungle Exchange поддерживает связь по протоколу HTTP/2 через согласование протоколов; в противном случае по умолчанию используется протокол HTTP/1.1.

2.3 Заголовки запросов

Каждый запрос предложения будет иметь следующие настраиваемые заголовки HTTP, как указано в протоколе OpenRTB:

X-OpenRTB-Version: 2.3

Vungle Exchange в дополнение к настраиваемым заголовкам HTTP также присоединяет следующие стандартные заголовки:

Content-Type: application/json; charset=utf-8
Accept: application/json 

Наконец, Vungle Exchange присоединяет настраиваемый заголовок, указывающий версию спецификации Vungle OpenRTB:

X-Vungle-OpenRTB-Version: 2

2.4 Объект BidRequest

Поле Тип Обязательный Описание
id строка да

Идентификатор запроса предложения, создаваемый Vungle Exchange; пример: '570b0eb14e67c98f761a0ca0'.

imp

object array

да См. объект Impression.
app object да См. объект Application.
device object да См. объект Device.
at integer да

Тип аукциона; пример: '2' для аукциона второй цены. Vungle Exchange поддерживает только аукцион второй цены, поэтому это значение всегда равно '2'.

tmax integer да

Максимальное время в миллисекундах для отправки полного ответа на предложение; это значение всегда равно '250'.

cur string array нет

Список допустимых валют для аукциона в формате ISO-4217-alpha; пример: ["USD", "CNY", "EUR"]. У нас в настоящее время поддерживается только complete "USD".

bcat string array нет См. OpenRTB 2.3.1, раздел 5.1.
regs object нет См. OpenRTB 2.3.1, раздел 3.2.16.
test integer нет

Определяет, в каком режиме проводится аукцион — в тестовом (1) или в режиме реального времени (0); в аукционах, проводящихся в тестовом режиме, счета не выставляются.

2.4.1 Объект Impression

Поле Тип Обязательный Описание
id строка да Идентификатор объекта Impression, создаваемый Vungle Exchange; пример: '3a06eb14e67c98f761add01'.
displaymanager строка да Менеджер отображения стороны предложения; Vungle использует это поле для указания применяемой технологии SDK, поскольку имеются различия между мобильными платформами SDK; пример: 'Vungle' для iOS, 'VungleDroid' для Android и 'VungleWindows' для Windows, после чего в следующем поле указывается версия SDK.
displaymanagerserver строка да Версия менеджера отображения стороны предложения; используется Vungle для указания версии SDK; пример: '3.3.1'.
bidfloor float да Минимальная цена предложения, при которой предложение будет действительным; пример: '8.72'.
bidfloorcur строка да Валюты для рекламного показа в формате ISO-4217-alpha; пример: 'USD'.
video object нет См. объект Video.
tagid строка нет Идентификатор размещения, соответствующего данному просмотру рекламы; пример: 'placement_name_1af44fda'.
instl integer нет Указывает, является ли рекламный показ полноэкранным/рекламной вставкой (1) или нет (0). В настоящее время Vungle Exchange поддерживает только полноэкранный показ/рекламную вставку (1).
secure integer нет Флаг, указывающий, требуются ли для просмотра рекламы безопасные креативные ресурсы и разметка URL-адреса HTTPS, где 0 = небезопасные и 1 = безопасные.
ext object нет Vungle всегда требует безопасные (1) ресурсы и разметку.

2.4.2 Объект Video

Поле Тип Обязательный Описание
mimes string array да Поддерживаемые типы контента MIME. Vungle Exchange поддерживает только ["video/mp4"].
h integer да Высота видео.
w integer да Ширина видео.
minduration integer нет Минимальное количество секунд, в течение которого должно воспроизводиться видео.
maxduration integer нет Максимальное количество секунд, в течение которого может воспроизводиться видео.
delivery integer array нет Поддерживаемый список методов предоставления видео: (последовательное скачивание или потоковая передача) См. OpenRTB 2.3.1, раздел 5.13.
minbitrate integer нет Минимальная частота предложений в кбит/с Vungle Exchange в настоящее время поддерживает только 250.
maxbitrate integer нет Максимальная частота предложений в кбит/с; пример: 500.
protocols integer array нет См. OpenRTB 2.3.1, раздел 5.8; пример: [2, 5].
boxingallowed integer нет Определяет, разрешена (1) или нет (0) упаковка-преобразование. Это значение всегда равно '1'.
playbackmethod integer array нет См. OpenRTB 2.3.1, раздел 5.9.
startdelay integer нет См. OpenRTB 2.3.1, раздел 5.10. Это значение всегда равно '0'.

2.4.3 Объект Application

Поле Тип Обязательный Описание
id строка да Специфичный для Exchange идентификатор. Для Vungle это идентификатор хранилища приложения; пример: '3709293'.
Этот идентификатор может ничего не значить для DSP, однако может использоваться DSP для сравнения и согласования расхождений в отчетности.
bundle строка да Уникальный рыночный идентификатор; это специфичный для платформы уникальный идентификатор приложения, независимый от Vungle Exchange.
— в Android это имя комплекта или пакета (например, 'com.supercell.hayday').
— в iOS это числовой идентификатор.
publisher object да См. объект Publisher.
name строка нет Имя приложения; пример: 'Hay Day'.
storeurl строка нет URL-адрес хранилища приложения; пример: 'https://itunes.apple.com/us/app/hay-day/id506627515?mt=8#'.
cat string array нет См. OpenRTB 2.3.1, раздел 5.1.
privacypolicy integer нет Определяет, имеет ли приложение политику конфиденциальности (1) или нет (0). Vungle Exchange поддерживает только '1' для этого поля.
paid integer нет Определяет, является ли приложение платным (1) или нет (0).
keywords строка нет Список тегов для приложения публикатора (с разделителями-запятыми)
ext object нет ОПИСАНИЕ

2.4.4 Расширение приложения

Поле Тип Обязательный Описание
altid строка нет Второй специфичный для Vungle Exchange идентификатор, уникальным образом определяющий приложение публикатора; пример: '3a06eb14e67c98f761add01'.
sdk object нет См. объект SDK Extension.
wtags string array нет Белый список тегов приложения публикатора.
btags string array нет Черный список тегов приложения публикатора.
bundleid строка нет Идентификатор комплекта приложения или имя пакета.
tags string array нет Устарело; используйте ключевые слова.

2.4.5 Расширение SDK

Поле Тип Обязательный Описание
name строка да Строка, указывающая семейство SDK агента SDK, установленного в хост-приложении. Например: 'VungleDroid', 'Vungle', or 'VungleWindows'.
ver строка да Строка, описывающая версию агента SDK, установленного в хост-приложении.
plugin строка нет Имя подключаемого модуля SDK, с использованием которого выполнена сборка агента SDK; пример: 'native', 'unity'.
pluginver строка нет Версия подключаемого модуля SDK, с использованием которого выполнена сборка агента SDK; пример: '1.0'.

2.4.6 Объект Publisher

Поле Тип Обязательный Описание
id строка да Идентификатор объекта Publisher, создаваемый Vungle Exchange; пример: '570ffeb14e67998f761a791c'.
name строка нет Имя объекта Publisher; пример: 'Supercell Oy'.
cat string array нет См. OpenRTB 2.3.1, раздел 5.1.

2.4.7 Объект Device

Поле Тип Обязательный Описание
ua строка да Строка пользовательского агента браузера устройства; пример: 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143 Safari/601.1'.
ip строка да Не является обязательным, когда имеется поле ipv6. Это IP-адрес просмотра рекламы; пример: '212.14.27.104'.
ipv6 строка да Не является обязательным, когда имеется поле ip. IPv6-адрес просмотра рекламы; пример: '3ffe:1900:4545:3:200:f8ff:fe21:67cf'.
h integer да Высота экрана устройства в пикселях.
w integer да Ширина экрана устройства в пикселях.
connectiontype строка да См. OpenRTB 2.3.1, раздел 5.18.
ifa строка да Идентификатор, который разрешено использовать рекламодателю в открытом тексте; пример: 'e4fe9bdecaa047b6908dffba3fa184f2'.
geo object нет См. объект Geo.
make строка нет Производитель устройства.
model строка нет Модель устройства.
os строка нет ОС устройства; пример: 'iOS', 'Android'. Значение перечисления:
- 'iOS'
- 'Android'
- 'Windows'
osv строка нет Версия ОС устройства; пример: '9.1', '8.0'.
dnt integer нет Определяет ли устройство опцию "Не отслеживать" (1) или нет (0).
lmt integer нет Определяет ли устройство опцию "Ограниченное отслеживание рекламы" (1) или нет (0).
devicetype строка нет См. OpenRTB 2.3.1, раздел 5.17.
language строка нет Язык устройства в формате ISO-639-1-alpha-2; пример: 'en'.
carrier строка нет Оператор или поставщик услуг Интернета; пример: 'VERIZON'.
ext object нет См. объект Device Extension.

2.4.8 Расширение устройства

Поле Тип Обязательный Описание
tz строка нет Настройки часового пояса устройства, представленные в формате имени часового пояса в базе данных часовых поясов IANA; пример: 'America/Los_Angeles'.
vungleua строка нет Устарело: используйте Application.ext.vungle.sdk
sdcard integer нет Определяет, доступно ли хранилище SD-карт для устройств Android (1) или нет (0).
volume float нет Значение между 0 и 1, указывающее процент объема устройства.
muted integer нет 0 = ложь 1 = истина; требуется перечисление.
idfv строка нет

Идентификатор поставщика на устройствах iOS; алфавитно-цифровая строка, уникальным образом определяющая устройство для поставщика приложения; пример: '00000000-0001-4d3a-8f98-233623cd8d12'.

Одно и то же устройство может содержать различные значения IDFV в зависимости от того, принадлежит ли приложение в запросе предложения другим поставщикам.

marketplace строка нет

Магазин приложений, установленный на устройстве. Возможные значения:

  • 'google'
  • 'apple'
  • 'amazon'
is_sideload_enabled integer нет Логический флаг, указывающий, разрешает ли устройство устанавливать приложения из "неизвестных" источников. Если его значение равно '1' (истина), установка приложений из неизвестных источников разрешена. Если его значение равно '0' (ложь), их установка не разрешена.

2.4.9 Объект Geo

Поле Тип Обязательный Описание
country строка да Код страны в формате ISO-3166-1-alpha-3; пример: 'USA'.
lat float нет Широта устройства; пример: '[-90, 90]'.
long float нет Долгота устройства; пример: '[-180, 180]'.
type integer нет См. OpenRTB 2.3.1, раздел 5.16.
region строка нет Код региона в формате ISO-3166-2; 2-буквенный код штата в США; пример: 'CA'.
city строка нет Название города в свободном формате.
zip строка нет Почтовый индекс.
utcoffset integer нет Местное время в виде число минут +/- относительно UTC (всемирное координированное время).

2.4.10 Объект Regs

Поле Тип Обязательный Описание
coppa integer нет Флаг, указывающий, подпадает ли этот запрос под действие правил COPPA, установленных Федеральной торговой комиссией США, где 0 = нет, 1 = да.
ext object нет Заполнитель для специфичных Vungle Exchange расширений в OpenRTB.

2.4.11 Объект PMP

Поле Тип Обязательный Описание
private_auction integer нет Индикатор соответствия аукциона местам покупателей, названным в объекте Direct Deals, где 0 = все предложения приняты, 1 = предложения ограничены указанными сделками и соответствующими сроками.
deal object array нет Объекты Array of Deal (раздел 3.2.18), передающие конкретные сделки, применимые данному просмотру.
ext object нет Заполнитель для специфичных Vungle Exchange расширений в OpenRTB.

3. Ответ

3.1 Обязательные и необязательные поля

Замечания о столбце Обязательное в разделе "Ответ":

  • Да: в Vungle Exchange предполагается, что обязательное поле всегда отформатировано в соответствии с указанием, имеет непустое значение и указанный тип; недопустимые значения могут появиться в результате несоответствия правилам аукциона.
  • Рекомендуется: в Vungle Exchange это поле будет использоваться, чтобы облегчить процесс проведения аукциона, когда значение этого поля отформатировано в соответствии с указанием; отсутствие или недопустимое оформление поля не оказывает отрицательного влияния соответствие аукциона установленным требованиям.
  • Нет: в Vungle Exchange не требуется наличие данного поля.
  • По умолчанию: на все неупомянутые поля в OpenRTB 2.3.1 распространяются требования по умолчанию, соответствующие 'No'. Кроме того, все поля должны соответствовать указанному типу; в противном случае они могут оказать отрицательное влияние на соответствие аукциона установленным требованиям.

3.2 Заголовки ответов

Заголовки ответов должны содержать заголовок "Content-Type" с одним из принятых значений из заголовков запросов, указанных выше. Например:

Content-Type: application/json 

3.3 Код состояния ответа

Все ответы должны иметь код 200 или 204. Все другие коды HTTP ответов могут оказать отрицательное влияние на соответствие аукциона DSP установленным требованиям.

3.4 Передача сигнала причины отсутствия предложения

Для DSP рекомендуется отправлять причины отсутствия предложения, когда принимается решение не выставлять предложение. Эта информация поможет Vungle Exchange выявлять и исправлять потенциальные проблемы, препятствующие интеграции. Сигналы отсутствия предложения должны следовать спецификации, указанной в разделе 7.4 протокола OpenRTB 2.3.1. Правильно сформированный сигнал отсутствия предложения с указанием причины отсутствия должен выглядеть примерно так:


{"id": "1234567890", "seatbid": [], "nbr": 2}

3.5 Объект BidResponse

Поле Тип Обязательный Описание
id строка да Идентификатор объекта BidResponse, создаваемый Vungle Exchange; пример: '570ffeb14e67998f761a791c'. Должен совпадать с идентификатором в объекте BidRequest.
bidid строка нет Уникальный идентификатор ответа, создаваемый покупателем, помогающий вести журнал/отслеживание.
cur строка нет Валюта предложения в формате кодов ISO-4217 alpha. В настоящее время Vungle Exchange поддерживает только USD и интерпретирует все значения как доллары США.
seatbid object array да Массив объектов seatbid; требуется 1+, если предложение должно быть сделано.
nbr integer нет Причина отсутствия предложения, указанная в разделе 5.19 спецификации OpenRTB 2.3.1.
ext object нет  

3.5.1 Объект SeatBid

Поле Тип Обязательный Описание
seat строка нет Идентификатор места покупателя, от имени которого сделано это предложение. См. протокол OpenRTB 2.3.1.
bid object array да См. объект Bid. Должно существовать по крайней мере одно предложение.


3.5.2 Объект Bid

Поле Тип Обязательный Описание
id строка да Идентификатор объекта Bid, создаваемый отдельными DSP.
impid строка да Идентификатор просмотра, относящийся к просмотру запроса предложения для которого выставляется предложение. Должен совпадать с идентификатором в объекте Impression запроса предложения.
price float да Цена предложения, выраженная в единицах CPM; пример: '10.30'.
nurl строка нет URL-адрес уведомления о выигрыше, вызываемый Vungle Exchange при выигрыше предложения.
adm строка да Разметка рекламы для обслуживания после выигрыша аукциона. См. раздел Спецификация разметки рекламы.
cid строка рекомендуется Идентификатор кампании с прокси-сервером DSP.
crid строка рекомендуется Идентификатор рекламного элемента с прокси-сервером DSP.
adomain string array рекомендуется Домены рекламодателя для проверки списка блокировки; пример: ["supercell.com"].
bundle строка рекомендуется Уникальный рыночный идентификатор; это специфичный для платформы уникальный идентификатор приложения, независимый от Vungle Exchange.
— в Android это имя комплекта или пакета (например, 'com.supercell.hayday').
— в iOS это числовой идентификатор.
h integer рекомендуется Высота рекламного элемента.
w integer рекомендуется Ширина рекламного элемента.
cat string array нет Категории содержимого IAB; См. OpenRTB 2.3.1, раздел 5.1.
iurl строка нет URL-адрес потерянного уведомления.
dealid строка нет Ссылка на deal.id из объекта BidRequest, если это предложение относится к прямой сделке на частном рынке.
adid строка нет Идентификатор предварительно загруженной рекламы, которая должна быть обслужена, если данное предложение выиграет.
ext object нет  

4. Примеры

4.1 Пример запроса


{
    "id": "58ed309efa8936087efd1349",
    "imp": [{
        "id": "58ed309efa8936087efd134a",
        "video": {
            "mimes": ["video/mp4"],
            "minduration": 5,
            "maxduration": 30,
            "protocols": [2, 5],
            "w": 1080,
            "h": 1920,
            "startdelay": 0,
            "linearity": 1,
            "minbitrate": 250,
            "maxbitrate": 2500,
            "boxingallowed": 1,
            "playbackmethod": [1, 2, 3, 4],
            "delivery": [1, 2],
            "pos": 7
        },
        "displaymanager": "Vungle",
        "displaymanagerver": "3.3.5",
        "instl": 1,
        "bidfloor": 15,
        "bidfloorcur": "USD"
    }],
    "app": {
        "id": "56b8e577819502560b000033",
        "name": "test-pub-app-name",
        "bundle": "1045826890",
        "storeurl": "https://itunes.apple.com/us/app/id1234567?mt=8",
        "cat": [
            "IAB1"
        ],
        "privacypolicy": 1,
        "publisher": {
            "id": "test-pub-app-id",
            "name": "test-pub-app-name",
            "cat": [
                "IAB1"
            ]
        },
        "ext": {
            "vungle": {
                "altid": "5fff577819502560b000033",
                "btags": ["real money gambling", "social casino"],
                "wtags": ["targeted tag", "social"]
            }
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_4 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12H141",
        "geo": {
            "lat": 47.46,
            "lon": -122.16,
            "type": 1,
            "country": "USA",
            "region": "WA",
            "city": "San Francisco",
            "zip": "94103"
        },
        "dnt": 0,
        "lmt": 0,
        "ip": "192.168.1.1",
        "devicetype": 1,
        "make": "Samsung",
        "model": "SM-J200G",
        "connectiontype": 2,
        "os": "iOS",
        "osv": "8.0",
        "w": 1080,
        "h": 1920,
        "js": 1,
        "language": "en",
        "ifa": "test-ifa",
        "ext": {
            "vungle": {
                "isSdCardAvailable": 1,
                "vungleua": "VungleDroid/3.3.5",
                "tz": "Europe/Kaliningrad",
                "sdcard": 1,
                "volume": 0.13333334,
                "muted": 1
            }
        }
    },
    "bcat": ["IAB7-3", "IAB7-5", "IAB7-28", "IAB7-29", "IAB7-30", "IAB7-39", "IAB7-41", "IAB7-42"],
    "at": 2,
    "cur": ["USD"],
    "tmax": 250
}

4.2 Пример ответа


{
  "id": "58ed309efa8936087efd1349",
  "bidid": "5508",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "7735",
      "bid": [
        {
          "id": "5508",
          "impid": "58ed309efa8936087efd134a",
          "price": 50,
          "nurl": "http://bidder.com/won?price=${AUCTION_PRICE}",
          "adm": "http://bidder.com/vast?id=${AUCTION_ID}",
          "cid": "554d550b418461cc3700014d",
          "crid": "57767c29a63510e75f000073"
        }
      ]
    }
  ]
}

5. Спецификация разметки рекламы

Vungle Exchange поддерживает в первую очередь три типа разметок: VAST, MRAID и собственную разметку рекламы Vungle Ad Markup. Каждая из них имеет свою спецификацию верхнего уровня, которая может рассматриваться как допустимая разметка с учетом требований производительности, она также должна соответствовать дополнительным требованиям ниже.

5.1 VAST

Следующий тег должен отображаться в первых 100 байтах поля 'adm' или в полезных данных ответа 'nurl':

<VAST version="2.0">

5.2 Макрозамена

Vungle Exchange поддерживает макрозамену для цены предложения в поле nurl объекта Bid в ответе на предложение. Например:


"nurl": "http://bidder.com/won?price=${AUCTION_PRICE}"
Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 0 из 0
Еще есть вопросы? Отправить запрос

Комментарии