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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

После того как ваше приложение обработает запрос ставки от 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 . Атрибуты, которые должны быть объявлены (см. также полный список поддерживаемых атрибутов на странице customer-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
    Для отображения объявления требуется API MRAID.

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

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

Открытые поля торгов

Ответы на заявки, отправленные участниками торгов на бирже и в сети, участвующими в открытых торгах, аналогичны ответам Авторизованных покупателей, участвующих в стандартных торгах в реальном времени. Клиенты 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 Токен, используемый для идентификации информации о конечном покупателе третьей стороны, если биржа в качестве участника открытых торгов является посредником. Это получено от стороннего покупателя и должно быть передано в Google без изменений в ответе на предложение.

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

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

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

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

В следующих примерах представлены удобочитаемые образцы запросов Protobuf и JSON.

Google

OpenRTB JSON

OpenRTB Protobuf

Важно: Сообщения 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 в разделе сообщения Create BidResponse . Одним из способов использования этого является добавление дополнительной информации в аргументы 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 выполнит неэкранирование, к my.adserver.com будет добавлена ​​версия URL с google_click_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-адреса 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 Закодированная стоимость показа (то есть CPI, а не CPM) в микросекундах валюты аккаунта. Например, выигрышная цена за тысячу показов в размере 5 долларов США соответствует 5 000 000 микросекунд CPM или 5 000 микросекунд CPI. Расшифрованное значение 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 Protobuf

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

Google

OpenRTB JSON

OpenRTB Protobuf

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

Google

OpenRTB JSON

OpenRTB Protobuf

Нативное приложение

Google

OpenRTB JSON

OpenRTB Protobuf

Веб-видео

Google

OpenRTB JSON

OpenRTB Protobuf

Мобильный веб-баннер для аукциона на бирже

OpenRTB Protobuf