Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.
Обработка запроса
Оптимизируйте свои подборки
Сохраняйте и классифицируйте контент в соответствии со своими настройками.
Взаимодействие в рамках назначения ставок в реальном времени начинается, когда Google отправляет запрос ставки в ваше приложение. В этом руководстве рассказывается, как написать код приложения, чтобы оно могло обрабатывать запросы ставок.
Запрос на синтаксический анализ
Google отправляет запрос ставки, сериализованный в формате OpenRTB JSON или Protobuf и прикрепленный в качестве полезной нагрузки к запросу POST HTTP. Формат полученных данных зависит от конфигурации вашей конечной точки. Пример запроса ставки приведен в этом разделе.
Чтобы получить сериализованный объект BidRequest, необходимо выполнить синтаксический анализ запроса. Если вы используете формат Protobuf, скачайте файлы openrtb.proto и openrtb-adx.proto со страницы Справочные данные и сгенерируйте на их основе библиотеку, которая будет использоваться для анализа сообщения BidRequest. Например, следующий код C++ анализирует запрос, заданный полезной нагрузкой POST в строке:
Получив BidRequest, вы можете работать с ним как с объектом, извлекая и интерпретируя нужные поля. Например, в C++ итерация по сделкам в OpenRTB `BidRequest` может выглядеть следующим образом:
Вы получаете запрос ставки, когда рекламный инвентарь издателя соответствует одной или нескольким вашим конфигурациям предварительного таргетинга. BidRequest.imp.ext.billing_id будут указаны платежные идентификаторы всех допущенных покупателей и соответствующие настройки предварительного таргетинга. Кроме того, для инвентаря, относящегося к сделкам, можно найти платежные идентификаторы, связанные с нужными покупателями, с помощью BidRequest.imp.pmp.deal.ext.billing_id. При назначении ставки можно указывать только платежные идентификаторы покупателей, включенных в запрос ставки.
Если в запросе ставки указано несколько платежных идентификаторов, вы должны указать платежный идентификатор покупателя, которому хотите назначить ставку, в поле BidResponse.seatbid.bid.ext.billing_id.
imp {
ext {
// The billing IDs of all of your matching pretargeting configs and eligible child seats are
// stored in a flat list here.
billing_id: 123
billing_id: 456
billing_id: 789
}
pmp {
// All eligible deals are stored in a single flat list.
deal {
id: 1000
ext {
// The specific billing IDs eligible to bid on this deal are indicated here.
billing_id: 789
}
...
}
deal {
id: 2000
ext {
billing_id: 123
billing_id: 456
}
...
}
}
...
}
...
Как определить заблокированные категории
При назначении ставки креатив не должен относиться к категориям, заблокированным издателем. В противном случае ставка будет отфильтрована.
Чтобы узнать, какие категории были заблокированы для показа, проверьте поле BidRequest.bcat. В нем указываются категории из классификации, настроенной для вашего аккаунта.
Ниже приведен пример заблокированных категорий на основе настроенной классификации категорий объявлений.
Классификация контента IAB 1.0
// Bid request{// Indicates the blocked categories using IAB Content 1.0 Taxonomy."bcat":["IAB9-9",// Cigars"IAB8-18"// Wine]"imp":{...}}
Классификация категорий объявлений Google
// Bid request{// Indicates the blocked categories using Google Ad Category Taxonomy."bcat":["10138",// Cigar and tobacco collecting"10080",// Tobacco"11649",// Wine"10674",// Wine collecting"13008"// Wine clubs]"imp":{...}}
Определение контекстных категорий
Запросы ставок могут содержать поля тематических категорий, которые описывают сайт или приложение, где выполняется показ. В этих полях также используются таксономии категорий объявлений, но они представляют контекст показа, а не ограничения для креатива. В этих полях может использоваться не та же таксономия, что и в поле BidRequest.bcat. Эти категории могут быть предоставлены Google или издателем. Использование тематических категорий может улучшить оценку показов, контекстный таргетинг и безопасность бренда.
Контекстные категории, обнаруженные Google
Google заполняет следующие поля категориями контента IAB, определенными для сайта, приложения или страницы:
Массив идентификаторов категорий контента, описывающих текущую страницу или представление приложения.
Точная классификация, используемая для этих полей в определенном запросе ставки, указывается в полях BidRequest.site.cattax или BidRequest.app.cattax. Поля категорий контекстного таргетинга не всегда заполняются из-за настроек издателя или нормативных требований.
Дополнительную информацию вы найдете в статье Контекстные категории OpenRTB в Google Менеджере рекламы.
Сигналы, заданные издателем
Помимо категорий контекста, определенных Google, запросы ставок могут содержать сигналы, предоставленные издателем, которые также описывают контекст показа. В отличие от категорий контекста, определяемых Google, эти сигналы заполняются только в том случае, если они предоставлены издателем. Эти сигналы отправляются в объектах BidRequest.site.content и BidRequest.app.content, например content.data.segment и content.genre. Классификация, используемая для записей content.data.segment, указывается в поле content.data.ext.segtax. Дополнительную информацию вы найдете в статье Сигналы, предоставленные издателем (PPS), для назначения ставок в реальном времени (RTB).
Файлы словарей
В запросе ставки используются идентификаторы, определенные в файлах словаря, которые доступны на странице Справочные данные.
Макросы URL системы назначения ставок
При необходимости в URL конечной точки назначения ставок можно вставить некоторую информацию из BidRequest с помощью макросов. Если вы настроите URL конечной точки с одним или несколькими макросами, они будут развернуты, если эта информация присутствует в запросе ставки. Это может быть полезно, например, если вы хотите выполнить балансировку нагрузки на основе информации в BidRequest.
Чтобы запросить поддержку новых макросов, обратитесь к менеджеру аккаунта.
Макрос
Описание
%%GOOGLE_USER_ID%%
Заменяется идентификатором пользователя Google, который указан в поле BidRequest.user.id. Например, URL системы назначения ставок http://google.bidder.com/path?gid=%%GOOGLE_USER_ID%% будет заменен на http://google.bidder.com/path?gid=dGhpyBhbiBleGFtGxl во время запроса.
Если идентификатор пользователя Google неизвестен, подставляется пустая строка, и результат выглядит примерно так:
http://google.bidder.com/path?gid=
%%HAS_MOBILE%%
Заменяется на 1, если запрос ставки поступил с мобильного устройства, и на 0 в противном случае. Определяется значением BidRequest.device.devicetype, где мобильные устройства обозначаются как HIGHEND_PHONE (4) или Tablet (5).
%%HAS_VIDEO%%
Заменяется на 1, если запрос ставки содержит видеоинвентарь, и на 0 в противном случае. Это зависит от того, заполнено ли поле BidRequest.imp.video в запросе ставки.
%%IS_CTV%%
Заменяется на 1, если запрос ставки поступил с подключенного телевизора, и на 0 в противном случае. Это зависит от значения BidRequest.device.devicetype. В Protobuf подключенные телевизоры обозначаются как CONNECTED_TV, CONNECTED_DEVICE или SET_TOP_BOX, что соответствует целочисленным значениям 3, 6 или 7 в JSON.
%%HOSTED_MATCH_DATA%%
Заменяется значением на основе BidRequest.user.buyeruid.
%%MOBILE_IS_APP%%
Заменяется на 1, если запрос ставки относится к инвентарю в мобильном приложении, и на 0 в противном случае. Это зависит от того, заполнено ли поле BidRequest.app.
Как найти идентификатор мобильного приложения в URL транзакции
URL транзакций в мобильных приложениях выглядят следующим образом:
mbappgewtimrzgyytanjyg4888888.com
Используйте декодер base-32, чтобы расшифровать часть строки, выделенную жирным шрифтом (gewtimrzgyytanjyg4888888).
Вы можете использовать онлайн-декодер, но вам придется заменить строчные буквы на заглавные, а символы 8 в конце – на =.
Расшифровка этого значения:
GEWTIMRZGYYTANJYG4======
Результат:
1-429610587
Строка 429610587 – это идентификатор приложения iFunny для iOS.
Вот ещё один пример. URL, на который вы пожаловались:
mbappgewtgmjug4ytmmrtgm888888.com
Расшифровка этого значения:
GEWTGMJUG4YTMMRTGM======
Результат:
1-314716233
Результат 314716233 – это идентификатор приложения TextNow для iOS.
Как найти название мобильного приложения по URL транзакции
Вот пример получения названия приложения. URL, на который вы пожаловались:
Результат соответствует приложению для Android slither.io.
Поля Open Bidding
Запросы ставок, которые отправляются покупателям, использующим биржи и сети и участвующим в Open Bidding, похожи на запросы, которые отправляются Авторизованным покупателям, участвующим в стандартном назначении ставок в реальном времени. Клиенты, использующие Open Bidding, получат несколько дополнительных полей, а некоторые существующие поля могут использоваться по-другому. К ним относятся:
OpenRTB
Сведения
BidRequest.imp.ext.dfp_ad_unit_code
Содержит код сети издателя в Менеджере рекламы, за которым следует иерархия рекламных блоков, разделенная косой чертой.
Например, это может выглядеть так: /1234/cruises/mars.
BidRequest.user.data.segment
Повторяющиеся пары "ключ-значение", отправленные издателем участнику аукциона на бирже.
Если в поле BidRequest.user.data.name указано значение “Publisher Passed”, то значения представляют собой пары "ключ-значение", отправленные издателем.
Как объявить разрешенных поставщиков
Поставщики технологий, которые предоставляют такие услуги, как исследования, ремаркетинг и показ объявлений, могут играть определенную роль во взаимодействии между покупателями и продавцами. Разрешены только поставщики, проверенные Google на соответствие требованиям к взаимодействию с Авторизованными покупателями.
Чтобы понять, BidRequest, и создать BidResponse, вам нужно знать о двух разных способах объявления поставщиков технологий:
Другие поставщики могут участвовать, только если они указаны в BidRequest:
В файле BidRequest поле BidRequest.imp.ext.allowed_vendor_type указывает, каких поставщиков разрешает продавец. Поставщики, которые будут отправлены в allowed_vendor_type, перечислены в файле словаря vendors.txt.
Пример запроса ставки
Ниже приведены человекочитаемые примеры запросов Protobuf и JSON.
Чтобы преобразовать запрос ставки в двоичную форму, как это происходит с полезной нагрузкой POST в реальном запросе, вы можете сделать следующее (на C++). Обратите внимание, однако, что это неприменимо к OpenRTB JSON.
Отзывы в реальном времени доступны Авторизованным покупателям, а также биржам и сетям, использующим Open Bidding.
Проверка в реальном времени заполняет поле BidRequest.ext.bid_feedback на основе результатов одной или нескольких ставок, сделанных вами ранее. С помощью этой функции можно узнать, выиграла ли ставка аукцион, какая минимальная ставка была необходима для победы и т. д. Чтобы включить проверку в реальном времени, обратитесь к менеджеру аккаунта.
Помимо полей, которые по умолчанию отправляются в отзывах об ответах на запросы ставок, вы можете передавать собственные данные в поле BidResponse.seatbid.bid.ext.event_notification_token. event_notification_token – это произвольные данные, известные только покупателю, которые могут помочь в отладке. Например, это может быть новый идентификатор таргетинга или назначения ставок, представляющий новую тактику, или метаданные, связанные с креативом и известные только покупателю. Подробную информацию можно найти в файле буфера протокола расширений OpenRTB.
Когда Авторизованные покупатели отправляют запрос ставки участнику аукциона, он отвечает на него с помощью объекта BidResponse. Если у покупателя включена проверка в реальном времени, то в следующем запросе ставки Авторизованные покупатели отправляют отзыв на ответ в сообщении BidFeedback:
messageBidFeedback{//TheuniqueidfromBidRequest.id.optionalstringrequest_id=1;//Thestatuscodeforthead.Seecreative-status-codes.txtinthe//technicaldocumentationforalistofids.optionalint32creative_status_code=2;//Deprecated.ThisfieldisnotpopulatedandwillberemovedafterMarch,//2025.Ifthebidwontheauction,thisisthepricepaidinyouraccount//currency.Ifthebidparticipatedintheauctionbutwasout-bid,this//istheCPMthatshouldhavebeenexceededinordertowin.Thisisnot//setifthebidwasfilteredpriortotheauction,ifthepublisheror//winningbidderhasoptedoutofpricefeedbackorifyouraccounthas//optedoutofsharingwinningpriceswithotherbidders.Forfirst-price//auctions,minimum_bid_to_winispopulatedinsteadofthisfield.optionaldoubleprice=3[deprecated=true];//Theminimumbidvaluenecessarytohavewontheauction,inyouraccount//currency.Ifyourbidwontheauction,thisisthesecondhighestbid//thatwasnotfiltered(includingthefloorprice).Ifyourbiddidn't win//theauction,thisisthewinningcandidate's bid. This field will only be//populatedifyourbidparticipatedinafirst-priceauction,andwillnot//bepopulatedifyourbidwasfilteredpriortotheauction.optionaldoubleminimum_bid_to_win=6;//Billableeventratemultiplierthatwasappliedtothisbidduring//ranking.Theadjustmentreflectsthelikelihoodthatyourbidwould//generateabillableevent(namely,theadrenderssuccessfully)ifitwon//theauction,relativetotheprobabilitythatotherbidsgeneratea//billableeventiftheywontheauction.Thisadjustmentcanbelargeror//smallerthan1.Thisaffectsthefinalrankingintheauctiononly;in//particular,thismultiplierdoesnotaffectthepaymentorwhetherthe//bidclearsanyfloorprice.optionalfloatbillable_event_rate_bid_adjustment=13[default=1];//WhenapublisherusesanRTBauctionandwaterfall-basedSDKmediationon//thesamequery,thewinnerofthereal-timeauctionmustalsocompetein//amediationwaterfall(whichisorderedbyprice)towintheimpression.//Ifthebidparticipatedintheauctionandtherewasnowaterfall,the//valueofthisfieldis0.Ifthebidparticipatedintheauctionand//therewasawaterfall,thevalueofthisfieldisapricerepresentinga//samplebidfromtheeligiblemediationnetworksthatwerehigherthanthe//auctionwinner,weightedbyexpectedfillrate.Thisfieldcanbeused//inconjunctionwithminimum_bid_to_wintotrainbiddingmodels.TheCPM//isinyouraccountcurrency.optionaldoublesampled_mediation_cpm_ahead_of_auction_winner=8;messageEventNotificationToken{//Thecontentsofthetoken.optionalstringpayload=1;}//Thetokenincludedinthecorrespondingbid.optionalEventNotificationTokenevent_notification_token=4;//ThecreativeIDincludedinthecorrespondingbid.optionalstringbuyer_creative_id=5;}
В этом сообщении в первую очередь нужно проверить поле bid_feedback.creative_status_code. Значение кода можно найти в файле creative-status-codes.txt. Обратите внимание, что если вы выиграете ставку, то можете отказаться от отзывов о цене. Подробнее о том, как отказаться от участия в программе…
В отзыве в реальном времени указывается идентификатор запроса ставки и один из следующих элементов:
Результат аукциона
Проверка в реальном времени
Покупатель не назначил ставку.
Переход произойдет автоматически.
Покупатель назначил ставку, которая была отфильтрована до начала аукциона.
Покупатель назначил ставку, которая выиграла аукцион.
Цена клиринга и код статуса креатива 1.
Если показ в приложении не состоялся и был возвращен код статуса креатива 83, то издатель приложения мог использовать каскад медиации, и поэтому выигравшая ставка конкурировала с другими источниками спроса в каскадной цепочке возврата издателя. Подробнее о том, как использовать sampled_mediation_cpm_ahead_of_auction_winner при назначении ставок…
Пример
Ниже приведен пример ответа в реальном времени, который можно увидеть в поддерживаемых протоколах.
Создайте модель назначения ставок для аукционов первой цены
После назначения ставки на аукционе первой цены вы получите отзыв в реальном времени, в том числе поля minimum_bid_to_win и sampled_mediation_cpm_ahead_of_auction_winner, если ставка не была отфильтрована. Эти сигналы можно использовать для корректировки логики назначения ставок, чтобы определить, насколько выше или ниже должна была быть ставка, чтобы выиграть показ.
minimum_bid_to_win – минимальная ставка, которая могла бы выиграть аукцион назначения ставок в реальном времени. Если вы выиграли аукцион, это будет самая низкая ставка, с которой вы могли бы победить. Если вы проиграли аукцион, это будет выигрышная ставка.
sampled_mediation_cpm_ahead_of_auction_winner. Если в цепочке медиации есть другие сети, то значением этого поля будет цена, представляющая собой пример ставки от одной из допущенных сетей медиации, которая была выше, чем у победителя аукциона, взвешенная по ожидаемому заполнению. Если ни одна из сетей в цепочке медиации не заполнена или издатель не использует медиацию SDK, будет установлено значение 0.
Принцип работы
Чтобы описать вычисления, используемые для определения возможных значений minimum_bid_to_win и sampled_mediation_cpm_ahead_of_auction_winner, сначала нужно определить следующее:
Ниже приведены цены за тысячу показов в цепочке медиации в порядке убывания.
\[C_1, C_2, …, C_n\]
Ниже приведены соответствующие коэффициенты заполнения для цен за тысячу показов в цепочке медиации:
\[f_1, f_2, …, f_n\]
Ниже приведена функция, которая используется для определения ожидаемой цены за тысячу показов и ее вероятности для элемента цепочки медиации \(i\)на основе заданного коэффициента заполнения.
\(X_i = \{C_i\) с вероятностью \(f_i\); \(0\) с вероятностью \(1 - f_i\}\)
Итоговая цепочка медиации будет выглядеть следующим образом:
\[\{C_1, C_2, …, C_K, W\}\]
где \(W\) – выигрышная ставка, а \(C_K > W >= C_{K+1}\)
Резервированная цена, или минимальная цена, обозначается как \(F\).
Вторая по величине ставка обозначается как \(R\).
Расчеты для победителя аукциона
Поле
Расчет
minimum_bid_to_win
\(max\{F, R, X_{K+1}, …, X_n\}\)
sampled_mediation_cpm_ahead_ of_auction_winner
\(\{C_i\) с вероятностью \(\prod_{j=1}^{i-1}(1-f_j) \cdot f_i \div \prod_{j=1}^{K}(1-f_j)\}\)
Для \(1 <= i <= K\).
Расчеты для проигравшего участника аукциона
Поле
Расчет
minimum_bid_to_win
\(max\{F, W\}\)
sampled_mediation_cpm_ahead_ of_auction_winner
\(max\{X_1, …, X_K\}\)
Пример с простой цепочкой медиации
Предположим, что издатель использует и назначение ставок в реальном времени, и цепочку медиации SDK следующим образом:
Цепочка медиации SDK
Ожидаемая цена за тысячу показов
Заполняемость
Сеть 1
\(C_1 = $3.00\)
\(f_1 = 5\%\)
Сеть 2
\(C_2 = $2.00\)
\(f_2 = 45\%\)
Сеть 3
\(C_3 = $0.50\)
\(f_3 = 80\%\)
Сеть 4
\(C_4 = $0.10\)
\(f_4 = 85\%\)
Предположим, что аукцион RTB завершился со следующими результатами:
Аукцион RTB
Цена за тысячу показов
Победитель аукциона (W)
1,00 долл. США
Второе место на аукционе (R)
0,05 долл. США
Резервированная/минимальная цена (F)
0 долл. США
Ставка, выигравшая аукцион
Ниже приведен пример того, как рассчитываются значения и вероятности для minimum_bid_to_win и sampled_mediation_cpm_ahead_of_auction_winner в случае выигрыша ставки.
Ниже приведен пример расчета значений и вероятностей для minimum_bid_to_win и sampled_mediation_cpm_ahead_of_auction_winner для проигравших ставок.
minimum_bid_to_win
Probability
\(max(F, W) = $1.00\)
\(100\%\)
sampled_mediation_cpm_ ahead_of_auction_winner
Probability
\(C_1 = $3.00\)
\(f_1 = 5\%\)
\(C_2 = $2.00\)
\((1-f_1) \cdot f_2 =~ 42.8\%\)
\(0\)
\((1-f_1) \cdot (1-f_2) =~ 52.2\%\)
Разделение запросов ставок
Разделение запросов ставок – это процесс, в ходе которого один сложный запрос BidRequest преобразуется в несколько запросов ставок, отправляемых в ваше приложение. Если запрос ставки был преобразован, вы можете определить, какие запросы ставок были частью исходного, поскольку у них будет одинаковое значение в поле BidRequest.ext.google_query_id.
Разделение запросов ставок включено по умолчанию, но вы можете обратиться к менеджеру своего аккаунта, чтобы отключить его.
Форматы объявлений
Некоторые рекламные места поддерживают несколько форматов. При разделении запросов ставок каждый формат отправляется в отдельном запросе, в котором атрибуты, например допустимые платежные идентификаторы, соответствуют формату, указанному в запросе.
Запросы ставок, содержащие следующие форматы, будут разбиты на отдельные запросы:
Баннер
Видео
Аудио
Стандартное
Пример упрощения формата объявления
Ниже приведен пример упрощенного запроса ставки OpenRTB JSON без разделения по форматам объявлений в сравнении с эквивалентным набором разделенных запросов.
Возможность показа объявления для определенного покупателя может быть доступна для сделок разных типов, а также для открытого аукциона. При разделении запросов ставок для сделок один запрос ставки будет отправлен для открытого аукциона, а ещё по одному – для каждого типа сделки с фиксированной ценой. На практике ограничения для объявлений могут различаться в зависимости от типа аукциона и сделки с фиксированной ценой. Например, если возможность показа видеообъявления доступна как на открытом аукционе, так и в рамках сделки с фиксированной ценой, то система назначения ставок получит отдельные запросы ставок для каждого из этих вариантов. При этом ограничения, такие как максимальная длительность объявления и возможность пропуска, могут различаться. В результате выравнивание, примененное к возможности показа рекламы, позволяет вам легче различать ограничения на показ объявлений для открытого аукциона и предложения с фиксированной ценой.
Возможность пропуска и продолжительность видео
В спецификации OpenRTB нет отдельных полей для указания максимальной длины видеообъявлений с возможностью пропуска и без возможности пропуска. В реализации Google для этого используется разделение запросов ставок с помощью существующих полей BidRequest.video.maxduration и BidRequest.video.skip.
Ниже приведен пример того, как видеоинвентарь выравнивается, когда максимальная длительность объявления без возможности пропуска составляет 15, а с возможностью пропуска – 60.
Пример
max_ad_duration
skip (true или false)
Исходный запрос без денормализации
15
true
Упрощенный запрос № 1: объявление без возможности пропуска
15
false
Упрощенный запрос 2: с возможностью пропуска
60
true
Разделение запросов ставок по длительности видеообъявлений с возможностью пропуска выполняется только при соблюдении следующих условий:
Запрос разрешает видео.
Разрешены видео как с возможностью пропуска, так и без нее, и значения максимальной длительности для них различаются.
Этот запрос подходит для частного или открытого аукциона.
Чтобы отказаться от такого преобразования, обратитесь к техническому менеджеру аккаунта. Если эта функция отключена, а издатель разрешает показ видеообъявлений как с возможностью пропуска, так и без возможности пропуска, причем с разной максимальной продолжительностью, то для параметра skip будет задано значение true, а для параметра maxduration – меньшая из двух продолжительностей.
Пакеты видеорекламы
Запросы ставок для пакета видеообъявлений с несколькими возможностями показа рекламы разделяются, чтобы каждый запрос ставки относился к отдельной возможности показа рекламы из этого пакета.
Это позволяет назначать ставки на несколько рекламных мест в одном пакете.
Open Measurement
Open Measurement позволяет указывать сторонних поставщиков, которые предоставляют независимые услуги по отслеживанию и проверке объявлений, показываемых в мобильных приложениях.
Дополнительную информацию о том, как интерпретировать запросы ставок, содержащие сигналы Open Measurement, можно найти в статье Справочного центра, посвященной Open Measurement SDK.
Примеры запросов ставок
В разделах ниже приведены примеры запросов ставок для разных типов объявлений.
[null,null,["Последнее обновление: 2026-11-17 UTC."],[],["Bid requests are HTTP POSTs using OpenRTB Protobuf, replacing the deprecated Google RTB protocol. Parsing involves `ParseFromString()` to access fields in the `BidRequest` object. Billing IDs, found in `BidRequest.imp.ext.billing_id` and `BidRequest.imp.pmp.deal.ext.billing_id`, must be specified in `BidResponse.seatbid.bid.ext.billing_id`. Key information comes from dictionary files. Bid URL macros dynamically insert `BidRequest` data. Complex bid requests can be broken into simpler, flattened requests per format or deal, such as skippable/non-skippable video ads, or video pods. Bidders get real-time feedback. The provided sample requests are used to help the process.\n"]]