После того как ваше приложение обработает запрос ставки от Google, оно должно сформировать и отправить ответ. В этом руководстве объясняется, как написать код приложения для создания ответа.
Создать сообщение Protobuf BidResponse
Авторизованные покупатели отправляют BidRequest как тело сообщения HTTP POST . Если ваша конечная точка назначения ставок настроена на использование формата Protobuf, ваше приложение должно отправить ответ с заголовком Content-Type установленным на application/octet-stream , и телом сообщения, состоящим из сериализованного буфера протокола. Буфер протокола — это сообщение BidResponse , определенное в openrtb.proto . Ваше приложение должно возвращать анализируемый BidResponse в ответ на каждый BidRequest . Тайм-ауты и ответы, которые невозможно проанализировать, считаются ошибками, и Google ограничивает участников торгов с высоким уровнем ошибок.
Если вы не хотите делать ставку на показ, вам необходимо вернуть пустой ответ HTTP 204. Вы можете получить openrtb.proto со страницы справочных данных .
Идентификатор объявления
В вашем BidResponse креатив указывается в поле BidResponse.seatbid.bid.crid (ограничение в 64 байта). Даже похожие креативы должны иметь уникальные значения для этого поля, если они отличаются по каким-либо заметным характеристикам, включая, помимо прочего: размер, заявленный URL-адрес, атрибуты креатива и типы поставщиков. Другими словами, вы должны присвоить разные идентификаторы объявлений любым двум объявлениям, которые:
Выглядите или ведите себя по-другому.
Рендеринг различных изображений.
Рендеринг разными способами (например, одно объявление состоит из изображения, а другое — из видео).
При разработке приложения вам следует выбрать систематический способ создания идентификаторов, которые будут иметь смысл для типов объявлений, которые вы планируете отправлять.
Атрибуты объявления
Google рекомендует объявлять атрибуты креатива для описания характеристик вашего объявления и его таргетинга, используя либо комбинацию BidResponse.seatbid.bid.apis и BidResponse.seatbid.bid.attr , либо расширение BidResponse.seatbid.bid.ext.attribute . Ниже описано, как можно объявлять атрибуты:
VPAID
Установите для BidResponse.seatbid.bid.apis значение VPAID_1 или VPAID_2 . Для формата JSON это значение может быть установлено равным 1 или 2 соответственно.
MRAID
Установите для BidResponse.seatbid.bid.apis значение MRAID_1 или 3 для формата JSON.
SIZELESS
Установите для BidResponse.seatbid.bid.attrRESPONSIVE или 18 для формата JSON.
PLAYABLE
На это указывает установка для BidResponse.seatbid.bid.attr значения USER_INTERACTIVE или 13 для формата JSON.
См . ресурс «Креативы» , чтобы узнать, как получить отзыв об обнаруженных свойствах ваших креативов.
Открытые поля ставок
Ответы на запросы ставок, отправляемые биржевыми и сетевыми участниками торгов, участвующими в Open Bidding, аналогичны ответам Авторизованных покупателей, участвующих в стандартных торгах в режиме реального времени. Клиенты Open Bidding могут указать небольшое количество дополнительных полей, а некоторые существующие поля могут использоваться альтернативно. К ним относятся следующие:
OpenRTB
Авторизованные покупатели
Подробности
BidResponse.imp[].pmp.deals[].id
BidResponse.ad[].adslot[].exchange_deal_id
Идентификатор сделки из пространства имен биржи, связанный с этой ставкой и сообщаемый издателям.
Токен, используемый для идентификации информации о конечном конечном покупателе, если биржа в качестве участника Open Bid является посредником. Эти данные получены от стороннего покупателя и должны быть переданы в Google в неизмененном виде в ответе на запрос ставки.
Рекомендации
Включите постоянные соединения HTTPS (также известные как «поддержание активности» или «повторное использование соединения») на своих серверах. Установите тайм-аут как минимум на 10 секунд — во многих случаях полезны более высокие значения. Google проверяет это во время первоначальных тестов задержки вашего приложения, поскольку Авторизованные покупатели отправляют запросы с высокой скоростью и им необходимо избегать накладных расходов на задержку, связанных с установкой отдельного TCP-соединения для каждого запроса.
Включите дополнительный URL-адрес отслеживания показов, чтобы отслеживать, когда показ выполняется, а не когда выигрывает система назначения ставок. Из-за разницы между победами и рендерингами это дает более точную статистику отслеживания.
В коде системы назначения ставок не должно быть зависимостей от устаревших полей , поскольку это может привести к тому, что ваши ставки будут отклонены с ошибками.
Включите BidResponse.seatbid.bid.w и BidResponse.seatbid.bid.h в свой BidResponse . BidResponse на запрос ставки, включающий несколько размеров объявлений, должен включать эти поля, иначе он будет исключен из аукциона.
Ограничьте размер ответа до 8 КБ. Очень большие ответы могут увеличить задержку сети и привести к тайм-аутам.
Важно: Сообщения 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.seatbid.bid.ext.sdk_rendered_ad
AMP
BidResponse.seatbid.bid.amp_ad_url
Видео
BidResponse.seatbid.bid.adm
Родной
BidResponse.seatbid.bid.adm_native
Укажите объявление, которое будет размещено на вашем собственном сервере(ах), используя фрагмент HTML в поле BidResponse.seatbid.bid.adm . Фрагмент заключен в iFrame, вставленный в веб-страницу, в результате чего объявление извлекается и отображается при загрузке страницы. Вам необходимо создать фрагмент HTML так, чтобы объявление (баннер или межстраничное объявление) правильно отображалось внутри iFrame и имело размер, соответствующий рекламному месту, на которое вы делаете ставку.
Кроме того, размер объявления, заявленный в ответе на заявку, должен совпадать ровно с одной из комбинаций размеров в запросе ставки, если:
Объявление представляет собой обычный баннер (не видео, нативный или межстраничный).
Участник торгов указал размер в ответе на заявку. Объявление размера требуется всякий раз, когда в запросе присутствует более одного размера.
Исключение сделано для межстраничной рекламы. Ширина межстраничных объявлений должна составлять не менее 50 % ширины экрана, а высота — не менее 40 % высоты экрана.
Вы можете указать креативный фрагмент HTML, используя любой действительный HTML-код, который отображается правильно, но помните об ограничениях на указание поля crid в разделе сообщения Create BidResponse . Одним из вариантов использования этого является добавление дополнительной информации в аргументы URL-адресов, которые получаются с ваших серверов в рамках отображения рекламы. Это позволяет вам передавать произвольные данные о показе обратно на ваши собственные серверы.
Макросы – это форматированный текст, встроенный в некоторые поля ответа на запрос ставки и содержащий URL-адреса, которые заменяются соответствующим значением во время показа объявления. Например, если ваша выигравшая ставка включала макрос AUCTION_PRICE во фрагмент объявления HTML, включенный в вашу ставку, макрос будет заменен значением, которое вы можете расшифровать, чтобы определить сумму, которую вы заплатили за показ на аукционе.
Вы можете включить макросы в следующие поля:
BidResponse.seatbid.bid.adm
Макросы поддерживаются для фрагментов HTML, собственных форматов, URL-адресов видео и XML-форматов VAST для видео.
Используйте его вместо BidResponse.seatbid.bid.burl , если вам требуется более одного URL-адреса для выставления счетов.
Например, вы можете включить макрос как часть фрагмента HTML, встроив ${MACRO} в URL-адрес, используемый для получения объявления, где MACRO — это один из поддерживаемых макросов, описанных в спецификации OpenRTB .
Макросы Google RTB
Google поддерживает дополнительные макросы, помимо тех, которые указаны в спецификации OpenRTB. Они имеют другой формат и будут выглядеть как %%MACRO%% если будут встроены в URL-адрес. В следующей таблице описаны эти макросы:
Строковое представление случайного четырехбайтового целого числа без знака.
CLICK_URL_UNESC
Неэкранированный URL-адрес клика для объявления. Во фрагменте непосредственно за макросом должна следовать экранированная версия стороннего URL-адреса клика.
Например, если сторонний URL-адрес клика — http://my.adserver.com/some/path/handleclick?click=clk , то следующий код можно использовать с одноэкранированной версией стороннего URL-адреса клика после вызова макроса:
URL-адрес сначала зарегистрирует клик в Google, а затем перенаправит на сторонний URL-адрес клика.
CLICK_URL_ESC
Экранированный URL-адрес клика для объявления. Используйте это вместо CLICK_URL_UNESC , если вам нужно сначала передать значение через другой сервер, который затем вернет перенаправление.
Например, во фрагменте HTML можно использовать следующий код:
При этом клик будет зарегистрирован на сайте 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 можно использовать следующий код:
Расширено до 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-адреса.
Google требует, чтобы вы использовали макрос CLICK_URL_UNESC или CLICK_URL_ESC в креативе стороннего объявления. Google использует макросы CLICK_URL для отслеживания кликов.
Экранирование URL-адресов в макросах использует следующую схему:
Символ пробела заменяется знаком плюс ( + ).
Буквенно-цифровые символы (0–9, az, AZ) и символы из набора !()*,-./:_~ остаются неизменными.
Все остальные символы заменяются на %XX , где XX — шестнадцатеричное число, представляющее символ.
Ограничения и требования издателя
Запрос ставки включает информацию о типах ограничений и требований, которые издатели предъявляют к креативам, участвующим в аукционе.
BidRequest.bcat
Вы можете сравнить заблокированные категории, указанные в этом поле, с категориями, обнаруженными для отправленных вами объявлений, с помощью поля detectedCategories API назначения ставок в реальном времени.
BidRequest.imp.ext.allowed_vendor_type
BidRequest.imp.secure
На практике это всегда будет true поскольку Google требует поддержки SSL для всех объявлений.
BidRequest.imp.{audio/banner/native/video}
BidRequest.imp.{audio/banner/native/video}.api
BidRequest.imp.{audio/banner/native/video}.battr
BidRequest.imp.{audio/banner/video}.mimes
Никогда не делайте ставок, используя объявление, содержащее ограниченную функцию. Для разрешенных функций, таких как тип поставщика, возвращайте объявление только в том случае, если его тип поставщика указан в списке allowed_vendor_type в BidRequest . В вашу ставку следует включать только форматы объявлений, указанные в запросе ставки посредством заполнения таких полей, как BidRequest.imp.banner . Дополнительные сведения см. в комментариях к этим полям в определении буфера протокола BidRequest .
Если объявление возвращается в BidResponse , вам необходимо точно указать поля BidResponse.seatbid.bid.attr , BidResponse.seatbid.bid.cat и BidResponse.seatbid.bid.adomain или BidResponse.seatbid.bid.adm_native.link.url в BidResponse . Если в объявлении указано несколько применимых значений для этих полей, необходимо указать каждое значение. Дополнительную информацию см. в комментариях к этим полям в определении буфера протокола BidResponse . Ответы, в которых эти поля не установлены, отбрасываются.
Открытое измерение
Open Measurement позволяет указать сторонних поставщиков, которые предоставляют независимые услуги по измерению и проверке рекламы, показываемой в средах мобильных приложений.
Поддерживаемые форматы рекламы включают видео, баннеры и межстраничные объявления. Дополнительную информацию о том, как использовать Open Measurement в ответах на запросы ставок, содержащих эти форматы, можно найти в статье Справочного центра Open Measurement SDK .
Примеры ответов на запросы ставок
В следующих разделах показаны примеры ответов на запросы ставок для разных типов объявлений.
id:"96Z599PGNvp7Mr99138Fm0"seatbid{bid{id:"NQb32Ge7Rtt84wFn2p8"impid:"1"price:0.153584adid:"test_creative_id_272596"adomain:"google.com"crid:"test_creative_id_272596"cat:"IAB13-7"burl:"https://test.com/imp?id=123456"adm_native{ver:"1.2"assets{id:1required:truetitle{text:"Luxury Mars Cruises"}}assets{id:2required:truedata{value:"Visit the planet in a luxury spaceship."}}assets{id:3required:falsedata{value:"Book today"}}assets{id:4required:truedata{value:"Galactic Luxury Cruises"}}assets{id:5required:trueimg{url:"https://native.test.com/image?id=123456"w:1200h:627}}link{url:"https://www.google.com"}eventtrackers{event:IMPRESSIONmethod:IMGurl:"https://test.com/event?id=123456"}privacy:"https://adssettings.google.com/whythisad?source=display&reasons=OMITTED"}[com.google.doubleclick.bid]{ad_choices_destination_url:"https://test.com/preferences"billing_id:29846056590dsa{behalf:"TEST_ADVERTISER"paid:"TEST_PAYING_ENTITY"adrender:false}}}bid{id:"4vwb23qm6iqU6w6G978"impid:"1"price:0.153584adid:"test_creative_id_272596"adomain:"google.com"crid:"test_creative_id_272596"cat:"IAB21"burl:"https://test.com/imp?id=123456"adm_native{ver:"1.2"assets{id:1required:truetitle{text:"Luxury Mars Cruises"}}assets{id:2required:truedata{value:"Visit the planet in a luxury spaceship."}}assets{id:3required:falsedata{value:"Book today"}}assets{id:4required:truedata{value:"Galactic Luxury Cruises"}}assets{id:5required:trueimg{url:"https://native.test.com/image?id=123456"w:1200h:627}}link{url:"https://www.google.com"}eventtrackers{event:IMPRESSIONmethod:IMGurl:"https://test.com/event?id=123456"}privacy:"https://adssettings.google.com/whythisad?source=display&reasons=OMITTED"}[com.google.doubleclick.bid]{ad_choices_destination_url:"https://test.com/preferences"dsa{behalf:"TEST_ADVERTISER"paid:"TEST_PAYING_ENTITY"adrender:false}}}seat:"4528:1161:591635"group:false}bidid:"hgu4ev7j-ZK929XM0-79f7-0A23O0VN2CFC"cur:"USD"
OpenRTB JSON
Покажи мне пример
{"id":"96Z599PGNvp7Mr99138Fm0","seatbid":[{"bid":[{"id":"NQb32Ge7Rtt84wFn2p8","impid":"1","price":0.153584,"adid":"test_creative_id_272596","adomain":["google.com"],"crid":"test_creative_id_272596","cat":["IAB13-7"],"burl":"https://test.com/imp?id=123456","ext":{"ad_choices_destination_url":"https://test.com/preferences","billing_id":"29846056590","dsa":{"behalf":"TEST_ADVERTISER","paid":"TEST_PAYING_ENTITY","adrender":0}},"adm":"{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"text\":\"Luxury Mars Cruises\"}},{\"id\":2,\"required\":1,\"data\":{\"value\":\"Visit the planet in a luxury spaceship.\"}},{\"id\":3,\"required\":0,\"data\":{\"value\":\"Book today\"}},{\"id\":4,\"required\":1,\"data\":{\"value\":\"Galactic Luxury Cruises\"}},{\"id\":5,\"required\":1,\"img\":{\"url\":\"https://native.test.com/image?id=123456\",\"w\":1200,\"h\":627}}],\"link\":{\"url\":\"https://www.google.com\"},\"eventtrackers\":[{\"event\":1,\"method\":1,\"url\":\"https://test.com/event?id=123456\"}],\"privacy\":\"https://adssettings.google.com/whythisad?source=display&reasons=OMITTED\"}"},{"id":"4vwb23qm6iqU6w6G978","impid":"1","price":0.153584,"adid":"test_creative_id_272596","adomain":["google.com"],"crid":"test_creative_id_272596","cat":["IAB21"],"burl":"https://test.com/imp?id=123456","ext":{"ad_choices_destination_url":"https://test.com/preferences","dsa":{"behalf":"TEST_ADVERTISER","paid":"TEST_PAYING_ENTITY","adrender":0}},"adm":"{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"text\":\"Luxury Mars Cruises\"}},{\"id\":2,\"required\":1,\"data\":{\"value\":\"Visit the planet in a luxury spaceship.\"}},{\"id\":3,\"required\":0,\"data\":{\"value\":\"Book today\"}},{\"id\":4,\"required\":1,\"data\":{\"value\":\"Galactic Luxury Cruises\"}},{\"id\":5,\"required\":1,\"img\":{\"url\":\"https://native.test.com/image?id=123456\",\"w\":1200,\"h\":627}}],\"link\":{\"url\":\"https://www.google.com\"},\"eventtrackers\":[{\"event\":1,\"method\":1,\"url\":\"https://test.com/event?id=123456\"}],\"privacy\":\"https://adssettings.google.com/whythisad?source=display&reasons=OMITTED\"}"}],"seat":"4528:1161:591635","group":0}],"bidid":"hgu4ev7j-ZK929XM0-79f7-0A23O0VN2CFC","cur":"USD"}
ad{adslot{id:1max_cpm_micros:158000billing_id:41106584355deal_id:1}click_through_url:"google.com"attribute:70buyer_creative_id:"test_creative_id_251451"advertiser_name:"Google"native_ad{headline:"Luxury Mars Cruises"body:"Visit the planet in a luxury spaceship."call_to_action:"Book today"advertiser:"Galactic Luxury Cruises"image{url:"https://native.test.com/image?id=123456"width:1200height:222}app_icon{url:"https://native.test.com/icon?id=123456"width:512height:512}star_rating:4.300000190734863click_link_url:"https://www.google.com"}impression_tracking_url:"https://test.com/imp?id=123456"impression_tracking_url:"https://test.com/imp?id=123456"event_notification_token:"token"skadn{version:"4.0"network:"l6x39K4z"itunesitem:"731305960"sourceapp:"627009739"fidelities{fidelity_type:STOREKIT_RENDERED_ADSnonce:"9216faff-74a9-4b35-badc-66878c35f67c"timestamp:1728975919221signature:"b0USXkmg02Q3v6p301kYOHG36CCOWWdEo52RHRttB9t8PTNi79qL17E4D6h7UeUSuq479oTK13G2Ev34MJlU86C5vY1SMVw2"}fidelities{fidelity_type:VIEW_THROUGH_ADSnonce:"9216faff-74a9-4b35-badc-66878c35f67c"timestamp:1728975919221signature:"4Cf4NH6239z9f3wa8j6420Z7H0UISYxyxN5720444dkq6457I5FY0Jg8bk1xge2P8YgiDp74l2738136v2g1A8D50331IRm0"}source_identifier:1}click_tracking_urls:"https://google.com/rtb/click?imp_id=55d2112c-4947-4da5-bc37-b79ebf4577dd"advertised_app_id:"APP_ID_OMITTED"app_promotion_type:INSTALLS}processing_time_ms:63
[null,null,["Последнее обновление: 2025-02-12 UTC."],[[["Bid responses must be serialized `BidResponse` protocol buffers with the `Content-Type` header set to `application/octet-stream` for Protobuf, and a parsable `BidResponse` is required for each `BidRequest`, while an empty HTTP 204 response signals no bid."],["Each creative needs a unique `crid` (creative ID) limited to 64 bytes, and this ID must be unique across creatives if there are differences in size, declared URL, attributes, vendor types, appearance, behavior, or rendering method."],["Ad characteristics should be declared using `BidResponse.seatbid.bid.apis`, `BidResponse.seatbid.bid.attr`, or `BidResponse.seatbid.bid.ext.attribute`, with specific values indicating VPAID, MRAID, SIZELESS, or PLAYABLE attributes, respectively, and additional attributes from `buyer-declarable-creative-attributes.txt`."],["Responses should remain under 8KB, utilize persistent HTTPS connections with at least a 10-second timeout, and employ `BidResponse.seatbid.bid.burl` or `BidResponse.seatbid.bid.ext.impression_tracking_url` for tracking impressions."],["The `BidResponse` must accurately set creative attributes (`BidResponse.seatbid.bid.attr`), categories (`BidResponse.seatbid.bid.cat`), and advertiser domain (`BidResponse.seatbid.bid.adomain`) or native ad link (`BidResponse.seatbid.bid.adm_native.link.url`), as responses lacking these are discarded."]]],[]]
