Создайте ответ

После того как ваше приложение обработает запрос ставки от Google, оно должно сформировать и отправить ответ. В этом руководстве объясняется, как написать код приложения для создания ответа.

Создать сообщение BidResponse

Авторизованные покупатели отправляют BidRequest как тело сообщения HTTP POST . Ответ, который отправляет ваше приложение, должен иметь заголовок Content-Type установленный на application/octet-stream , и тело сообщения, состоящее из сериализованного буфера протокола. Буфер протокола — это сообщение BidResponse , определенное в realtime-bidding.proto . Ваше приложение должно возвращать анализируемый BidResponse в ответ на каждый BidRequest . Тайм-ауты и ответы, которые невозможно проанализировать, считаются ошибками, и Google ограничивает участников торгов из-за высокого уровня ошибок.

Если вы не хотите делать ставку на показ, вы можете установить только processing_time_ms и оставить все остальные поля пустыми. Вы можете получить realtime-bidding.proto со страницы справочных данных .

Идентификатор объявления

В вашем BidResponse креатив указывается в поле buyer_creative_id (ограничение в 64 байта). Даже похожие объявления должны иметь уникальные значения для buyer_creative_id , если они отличаются какими-либо заметными характеристиками, включая, помимо прочего: размер, заявленный URL-адрес, атрибуты объявления и типы поставщиков. Другими словами, вы должны присвоить разные идентификаторы объявлений любым двум объявлениям, которые:

  • Выглядите или ведите себя по-другому.
  • Рендеринг различных изображений.
  • Рендеринг разными способами (например, одно объявление состоит из изображения, а другое содержит Flash).

При разработке приложения вам следует выбрать систематический способ создания идентификаторов, которые будут иметь смысл для типов объявлений, которые вы планируете отправлять.

Атрибуты объявления

Вы должны объявить атрибуты объявления, которые полностью описывают характеристики объявления и его таргетинг, в BidResponse.Ad.attribute . Атрибуты, которые должны быть объявлены: (см. также полный список поддерживаемых атрибутов в файле buy-declarable-creative-attributes.txt ):

  • 7 Tagging: IsTagged
    Объявление содержит пиксель или веб-маяк с целью создания списка идентификаторов файлов cookie для последующего ремаркетинга.
  • 8 Remarketing: IsRemarketing
    Реклама нацелена на потребителей на основе их идентификаторов файлов cookie или идентификаторов устройств, где список идентификаторов файлов cookie или идентификаторов устройств представляет собой группу потребителей, которые ранее взаимодействовали с сайтом, принадлежащим или представленным покупателем.
  • 9 UserInterestTargeting: IsUserInterestTargeted
    Реклама ориентирована на потребителей на основе их идентификаторов файлов cookie или идентификаторов устройств, при этом список идентификаторов файлов cookie или идентификаторов устройств представляет группу потребителей, определенных покупателем как группу с общими интересами.
  • 30 InstreamVastVideoType: Vpaid
    Для показа объявления требуется поддержка VPAID.
  • 32 MraidType: MRAID
    Для отображения объявления требуется MRAID API.

Кроме того, поддерживаются следующие атрибуты, но их объявление не требуется, поскольку Авторизованные покупатели автоматически обнаруживают их и блокируют (или разрешают) ваши объявления на основе обнаруженных значений, а не вашего объявления. См. Creatives API для получения информации о том, как получить обратную связь относительно обнаруженных свойств ваших объявлений.

  • 34 RichMediaCapabilityType: RichMediaCapabilityFlash
    Для показа объявления требуется поддержка Flash.
  • 50 RichMediaCapabilityType: RichMediaCapabilityNonFlash
    Для показа объявления не требуется Flash.
  • 47 RichMediaCapabilityType: RichMediaCapabilitySSL
    Объявление может отображаться на странице SSL. Обратите внимание, что Авторизованные покупатели рассматривают креативы с разными заявленными значениями этого атрибута как отдельные (они будут рассматриваться отдельно и иметь отдельный статус одобрения). Таким образом, если вы назначаете ставку как для версий одного и того же объявления с поддержкой SSL, так и без нее, вам следует объявить этот атрибут соответствующим образом, чтобы это различие правильно отражалось в AdX.

Открытые поля ставок

Ответы на запросы ставок, отправляемые биржевыми и сетевыми участниками торгов, участвующими в Open Bidding, аналогичны ответам Авторизованных покупателей, участвующих в стандартных торгах в режиме реального времени. Клиенты Open Bidding могут указать небольшое количество дополнительных полей, а некоторые существующие поля могут использоваться альтернативно. К ним относятся следующие:

OpenRTB Авторизованные покупатели Подробности
BidResponse.imp[].pmp.deals[].id BidResponse.ad[].adslot[].exchange_deal_id

Идентификатор сделки из пространства имен биржи, связанный с этой ставкой и сообщаемый издателям.

BidResponse.seatbid[].bid[].ext.exchange_deal_type BidResponse.ad[].adslot[].exchange_deal_type

Тип сделки, о которой сообщается издателям, влияет на то, как сделка будет рассматриваться на аукционе.

BidResponse.seatbid[].bid[].ext.third_party_buyer_token BidResponse.ad[].adslot[].third_party_buyer_token Токен, используемый для идентификации информации о конечном конечном покупателе, если биржа в качестве участника Open Bid является посредником. Эти данные получены от стороннего покупателя и должны быть переданы в Google в неизмененном виде в ответе на запрос ставки.

Рекомендации

  • Включите постоянные соединения HTTPS (также известные как «поддержание активности» или «повторное использование соединения») на своих серверах. Установите тайм-аут как минимум на 10 секунд — во многих случаях полезны более высокие значения. Google проверяет это во время начальных тестов задержки вашего приложения, поскольку Авторизованные покупатели отправляют запросы с высокой скоростью и им необходимо избегать накладных расходов на задержку, связанных с установкой отдельного TCP-соединения для каждого запроса.
  • Включите дополнительный URL-адрес отслеживания показов, чтобы отслеживать, когда показ выполняется, а не когда выигрывает система назначения ставок. Из-за разницы между победами и рендерингами это дает более точную статистику отслеживания.

  • В коде системы назначения ставок не должно быть зависимостей от устаревших полей , поскольку это может привести к тому, что ваши ставки будут отклонены с ошибками.
  • Включите BidResponse.Ad.width и BidResponse.Ad.height в свой BidResponse . Ответ на запрос BidResponse , включающий несколько размеров объявления, должен включать значения width и height , иначе он будет исключен из аукциона.
  • Ограничьте размер ответа до 8 КБ. Очень большие ответы могут увеличить задержку сети и привести к тайм-аутам.
  • Следуйте рекомендациям по ставкам на инвентарь iOS, требующий атрибуции SKAdNetwork .

Пример ответа на заявку

Следующие примеры представляют собой удобочитаемые образцы запросов Protobuf и JSON.

Google

OpenRTB JSON

OpenRTB Протобуф

Важно: Сообщения Protobuf, изображенные в примерах, представлены здесь в виде удобочитаемого текста. Однако сообщения передаются по проводу не так. При использовании формата Google или OpenRTB Protobuf принимаются только сериализованные сообщения BidResponse.

Вы можете создать и сериализовать сообщение BidResponse , используя следующий код C++:

BidResponse bid_response;
// fill in bid response with bid information
string post_response;
if (bid_response.SerializeToString(&post_response)) {
  // respond to the POST with post_response as the content
} else {
  // return an error to the POST
}

Укажите креатив

В вашем ответе на ставку указывается креатив, который будет показан в случае победы вашей ставки. Ваша ставка должна включать один из поддерживаемых форматов объявлений (AMP, видео, нативный). В этом примере мы указываем креатив, используя поле html_snippet .

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

  • Объявление, обработанное SDK
    • BidResponse.Ad.sdk_rendered_ad
  • AMP
    • BidResponse.Ad.amp_ad_url
  • видео
    • BidResponse.Ad.video_url или
    • BidResponse.Ad.video_vast_xml
  • Родной
    • BidResponse.Ad.native_ad

Укажите объявление, размещенное на вашем собственном сервере(ах), используя фрагмент HTML в поле html_snippet BidResponse . Фрагмент заключен в iFrame, вставленный в веб-страницу, в результате чего объявление извлекается и отображается при загрузке страницы. Вам необходимо создать фрагмент HTML так, чтобы объявление (баннер или межстраничное объявление) правильно отображалось внутри iFrame и имело размер, соответствующий рекламному месту, на которое вы делаете ставку.

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

  • Объявление представляет собой обычный баннер (не видео, нативный или межстраничный).
  • Участник торгов указал размер в ответе на заявку. Объявление размера требуется всякий раз, когда в запросе присутствует более одного размера.
  • Исключение сделано для межстраничной рекламы. Ширина межстраничных объявлений должна составлять не менее 50 % ширины экрана, а высота — не менее 40 % высоты экрана.

Поле html_snippet поддерживает любой действительный HTML-код, который отображается правильно, но имейте в виду ограничения на указание поля buyer_creative_id в разделе сообщения «Создать ответ на ставку» . Одним из способов использования этого является добавление дополнительной информации в аргументы URL-адресов, которые получаются с ваших серверов в рамках отображения рекламы. Это позволяет вам передавать произвольные данные о показе обратно на ваши собственные серверы.

Большинство правил для HTML-фрагментов, возвращаемых в ответах на запросы ставок, такие же, как и для сторонних объявлений. Дополнительные сведения см. в правилах программы «Авторизованные покупатели» , «Требования к показу сторонних объявлений » и «Объявление URL-адресов перехода по клику в объявлениях» .

Укажите макросы

Фрагмент HTML, определяющий объявление, может включать одну или несколько специальных конструкций, называемых макросами. Во время показа объявления макросы заменяются значениями. Например, ваше клиентское приложение для назначения ставок может использовать макрос WINNING_PRICE , чтобы определить, сколько оно заплатило за объявление, если оно выиграет аукцион. Чтобы проанализировать этот макрос, вам потребуется реализовать приложение, которое расшифровывает подтверждения цен. Дополнительную информацию см. на странице «Расшифровка подтверждений цен» .

Укажите макрос как часть фрагмента HTML в формате %%MACRO%% , где MACRO — это один из поддерживаемых макросов, перечисленных в таблице ниже.

Google требует, чтобы вы использовали макрос CLICK_URL_UNESC или CLICK_URL_ESC в креативе стороннего объявления. Google использует макросы CLICK_URL для отслеживания кликов.

Чтобы использовать макрос, включите его в объявление, чтобы URL-адрес получался при нажатии на него. Возвращаемое значение выборки — это перенаправление на другой URL-адрес, который вы добавляете к CLICK_URL .

Макрос Описание
ADVERTISING_IDENTIFIER Позволяет покупателям получать идентификатор iOS IDFA или рекламный идентификатор Android при показе. Подробности см. в разделе «Расшифровка идентификаторов рекламодателей ».
CACHEBUSTER Строковое представление случайного четырехбайтового целого числа без знака.
CLICK_URL_UNESC

Неэкранированный URL-адрес клика для объявления. Во фрагменте непосредственно за макросом должна следовать экранированная версия стороннего URL-адреса клика.

Например, если сторонний URL-адрес клика — http://my.adserver.com/some/path/handleclick?click=clk , то следующий код можно использовать с одноэкранированной версией стороннего URL-адреса клика. после вызова макроса:

<a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

Во время показа объявления это расширяется до:

<a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

URL-адрес сначала зарегистрирует клик в Google, а затем перенаправит на сторонний URL-адрес клика.

CLICK_URL_ESC

Экранированный URL-адрес клика для объявления. Используйте это вместо CLICK_URL_UNESC если вам нужно сначала передать значение через другой сервер, который затем вернет перенаправление.

Например, во фрагменте HTML можно использовать следующий код:

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a>

Во время показа объявления это расширяется до:

<a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a>

При этом клик будет зарегистрирован на my.adserver.com , который затем будет отвечать за перенаправление на URL-адрес, указанный в параметре google_click_url . Предполагается, что my.adserver.com не экранирует параметр google_click_url .

Вы можете добавить URL-адрес с двойным экранированием после %%CLICK_URL_ESC%% . После того, как my.adserver.com выполняет деэкранирование, к google_click_url добавляется версия URL-адреса с одинарным экранированием. Когда google_click_url будет получен, он снова будет экранирован, а затем перенаправлен.

CLICK_URL_ESC_ESC

URL-адрес объявления с двойным экранированием. Используйте это вместо CLICK_URL_UNESC если вам нужно сначала передать значение через другой сервер, который затем вернет перенаправление.

Например, во фрагменте HTML можно использовать следующий код:

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a>

Во время показа объявления это расширяется до:

<a href="http://my.otheradserver.com/click?google_click_url=http%3A%2F%2Fmy.adserver.com%2Fclick%3Fgoogle_click_url%3Dhttp%3A%2F%2Fgoogle-click-%20url%253F...%2526ad_url%253D"></a>
SCHEME Расширено до http: если запрос ставки не требует SSL или до https: если запрос ставки требует SSL.
SITE Домен URL-адреса контента без экранирования или анонимный идентификатор для анонимного инвентаря.
SITE_URL Устарело. Заменен макросом SITE, который обеспечивает идентичную функциональность.
TZ_OFFSET Смещение часового пояса.
VERIFICATION Различные значения для производства и при сканировании объявления в конвейере проверки. Формат: %%?VERIFICATION:true-val:false-val%% , где для true-val и false-val могут использоваться любые значения, кроме макросов, включая пустые строки. Для Open Bidding мы рекомендуем биржам использовать этот макрос; как только они это сделают, платформам на стороне спроса не придется вносить изменения.

Например, если объявление должно включать %%?VERIFICATION:-1:5000%% , то замена текста будет равна 5000 при показе и -1 в конвейере проверки. Это сделано для того, чтобы помочь различать эти два набора пингов.
WINNING_PRICE Закодированная стоимость показа (то есть цена за установку, а не цена за тысячу показов) в микро валюте аккаунта. Например, выигрышная цена за тысячу показов в размере 5 долларов США соответствует цене за тысячу показов в 5 000 000 микрон или цене за тысячу показов в 5 000 микрон. Декодированное значение WINNING_PRICE в этом случае будет равно 5000. Выигрышная цена указана в CPI.
WINNING_PRICE_ESC WINNING_PRICE с экранированием URL-адреса.

Экранирование URL-адресов в макросах использует следующую схему:

  • Символ пробела заменяется знаком плюс ( + ).
  • Буквенно-цифровые символы (0–9, az, AZ) и символы из набора !()*,-./:_~ остаются неизменными.
  • Все остальные символы заменяются на %XX , где XX — шестнадцатеричное число, представляющее символ.

Ограничения издателя

Издатели используют BidRequest для установления ограничений на разрешенную рекламу. Вы обязаны обеспечить соблюдение ограничений в следующих полях:

  • allowed_vendor_type
  • excluded_attribute
  • excluded_sensitive_category

В одном поле указаны разрешенные функции объявления, а в другом — запрещенные. Никогда не возвращайте объявление с запрещенной функцией. Для разрешенных функций, таких как тип поставщика, возвращайте объявление только в том случае, если его тип поставщика указан в списке allowed_vendor_type в BidRequest . Дополнительные сведения см. в комментариях к этим полям в определении буфера протокола BidRequest .

Если в BidResponse возвращается фрагмент HTML, вам необходимо точно указать поля attribute , category и click_through_url в BidResponse . Если в объявлении указано несколько применимых значений для этих полей, необходимо указать каждое значение. Дополнительную информацию см. в комментариях к этим полям в определении буфера протокола BidResponse . Ответы, в которых эти поля не установлены, отбрасываются.

Возможные значения BidRequest.excluded_attribute ( см.Publisher-excludable-creative-attributes.txt ):

  • 7 Tagging: IsTagged
    Объявления запрещены, если они содержат пиксель или веб-маяк с целью создания списка идентификаторов файлов cookie для последующего ремаркетинга.
  • 8 CookieTargeting: IsCookieTargeted
    Реклама запрещена, если она ориентирована на потребителей на основе их идентификаторов файлов cookie, где список идентификаторов файлов cookie представляет собой набор потребителей, которые ранее взаимодействовали с сайтом, принадлежащим или представленным покупателем.
  • 9 UserInterestTargeting: IsUserInterestTargeted
    Реклама запрещена, если она ориентирована на потребителей на основе их идентификаторов файлов cookie, где список идентификаторов файлов cookie представляет собой набор потребителей, которых покупатель определил как группу с общими интересами.
  • 21 CreativeType: Html
    В объявлениях запрещено использовать поля html_snippet или snippet_template в BidResponse.Ad .
  • 22 CreativeType: VastVideo
    В объявлениях запрещено использовать поле video_url в BidResponse.Ad .
  • 30 InstreamVastVideoType: Vpaid
    Объявления запрещены, поскольку для их показа требуется поддержка VPAID.
  • 32 MraidType: MRAID
    Запрещено показывать рекламу, требующую для отображения MRAID API.
  • 34 RichMediaCapabilityType: RichMediaCapabilityFlash
    Запрещена реклама, требующая поддержки Flash для отображения.
  • 39 RichMediaCapabilityType: RichMediaCapabilityHTML5
    Запрещено показывать объявления, требующие для отображения функций HTML5.
  • 48 RichMediaCapabilityType: RichMediaCapabilityNonSSL
    Объявлениям запрещено отправлять запросы без SSL.

Следовательно, если поле excluded_attribute содержит значение 7, то не следует возвращать объявление, использующее пиксель или веб-маяк для создания списка. Обратите внимание: если объявление делает это, то оно должно установить значение 7 в поле атрибута BidResponse . Аналогично, если поле excluded_attribute содержит значение 48, вам следует возвращать только те объявления, которые могут отображаться на странице SSL (и, соответственно, объявить атрибут 47 RichMediaCapabilityType: RichMediaCapabilitySSL).

Кроме того, поле excluded_sensitive_category в BidRequest использует коды из файла ad-sensitive-categories.txt , доступного на странице справочных данных . Вот расширенные описания некоторых из этих кодов:

  • 3 Politics
    Включает политику или спорные социальные вопросы; не включает рекламу новостных организаций, которые обычно не придерживаются пристрастной точки зрения по вопросам.
  • 4 Dating
    Включает в себя службы знакомств и сообщества онлайн-знакомств.
  • 5 Religion
    Включает религиозную рекламу и рекламу, пропагандирующую или противодействующую религиозным взглядам; не включает астрологию или внеконфессиональную духовность.
  • 7 Video Games (Casual & Online)
    Включает видеоигры, онлайн-игры и загружаемые игры; не включает игровые консоли.
  • 8 Ringtones & Downloadables
    Мобильные надстройки, включая мелодии звонка и другие загружаемые полезные функции, такие как заставки и обои для настольных ПК, а также макеты профилей и графика для социальных сетей.
  • 10 Get Rich Quick
    Схемы, обещающие быстрый заработок.
  • 18 Weight Loss
    Включает потерю веса, диету и сопутствующие продукты и программы; не включает рекламу здорового питания или общую рекламу фитнеса.
  • 19 Cosmetic Procedures & Body Modification
    Включает подтяжки, отсасывания, лазеры, эпиляцию и восстановление волос, татуировки и модификацию тела.
  • 23 Drugs & Supplements:
    Включает фармацевтические препараты, витамины, пищевые добавки и сопутствующие товары розничной торговли; не включает ресурсы, предоставляющие информацию о лекарствах.
  • 24 Sexual & Reproductive Health
    Включает рекламу сексуальной функции и фертильности; не включает нормальные ресурсы беременности.
  • 35 Social Casino Games
    Включает симулированные азартные игры (включая, помимо прочего, покер, игровые автоматы, бинго, лотереи, ставки на спорт, ставки на скачки, а также другие карточные игры и игры казино), в которых нет возможности выиграть что-либо ценное (например, деньги или призы).
  • 36 Significant Skin Exposure
    Рекламные изображения, на которых любая часть человеческого тела от грудины до середины бедра не одета; или тело одето в нижнее белье, купальники, нижнее белье или другую прозрачную одежду или предметы, не относящиеся к одежде, такие как полотенце или простыня.
  • 37 Sensationalism
    Рекламные объявления, целью которых является побудить пользователей кликнуть по ним, взывая к их любопытству, часто с использованием тизерного сообщения с гиперболическими выражениями или образами. Включает рекламу, посвященную сенсационным темам (например, арестам, смертям или разводам знаменитостей) или нацеленную на шокирующий эффект.

Открытое измерение

Open Measurement позволяет указать сторонних поставщиков, которые предоставляют независимые услуги по измерению и проверке рекламы, показываемой в средах мобильных приложений.

Поддерживаемые форматы рекламы в настоящее время включают видео, баннеры и межстраничные объявления. Дополнительную информацию о том, как использовать Open Measurement в ответах на запросы ставок, содержащих эти форматы, можно найти в статье Справочного центра Open Measurement SDK .

Примеры ответов на запросы ставок

В следующих разделах показаны примеры ответов на запросы ставок для разных типов объявлений.

Баннер приложения

Google

OpenRTB JSON

OpenRTB Протобуф

Межстраничное объявление приложения

Google

OpenRTB JSON

OpenRTB Протобуф

Межстраничное видео приложения

Google

OpenRTB Протобуф

Приложение родное

Google

OpenRTB JSON

OpenRTB Протобуф

Веб-видео

Google

Мобильный веб-баннер для системы торгов на бирже

OpenRTB Протобуф