Budowanie reakcji
Zadbaj o dobrą organizację dzięki kolekcji
Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Po przetworzeniu przez aplikację żądania stawki od Google musi ona utworzyć i wysłać odpowiedź. Z tego przewodnika dowiesz się, jak napisać kod aplikacji, aby utworzyć odpowiedź.
Tworzenie wiadomości BidResponse
Aby przesłać stawkę, aplikacja do określania stawek musi odpowiedzieć na pytanie o stawkę za pomocą BidResponse zawierającego Bid w skonfigurowanym formacie. Jeśli używasz formatu JSON, w odpowiedzi musisz ustawić nagłówek Content-Type na application/json; charset=utf-8 i w treści umieścić kod JSON BidResponse. Jeśli używasz formatu Protobuf, aplikacja musi ustawić nagłówek Content-Type na wartość application/octet-stream i uwzględnić w treści serializowany element BidResponse.
Aby utworzyć i zserializować obiekt BidResponse w formacie Protobuf, musisz wygenerować i użyć bibliotek Protobuf na podstawie plików openrtb.proto i openrtb-adx.proto, które implementują odpowiednio standardowe pola OpenRTB BidResponse i rozszerzenia Google w Protobuf. Znajdziesz je w sekcji Protokół i dane referencyjne.
Jeśli nie chcesz licytować wyświetlenia, musisz zwrócić pustą odpowiedź HTTP 204. Aplikacja musi zwracać odpowiedź na każde żądanie BidRequest. Przekroczenia limitu czasu i odpowiedzi, których nie można przeanalizować, są traktowane jako błędy, a Google ogranicza działanie licytujących z wysokim współczynnikiem błędów.
Identyfikator kreacji
Pole BidResponse w parametrze BidResponse określa kreację (limit 128 bajtów).BidResponse.seatbid.bid.crid Nawet podobne kreacje muszą mieć unikalne wartości tego pola, jeśli różnią się od siebie pod względem istotnych cech, w tym m.in. rozmiaru, zadeklarowanego adresu URL, atrybutów kreacji i typów dostawców. Innymi słowy, musisz przypisać różne identyfikatory kreacji do 2 reklam, które:
wyglądać lub zachowywać się inaczej;
Renderuj różne obrazy.
wyświetlać się w różny sposób (np. jedna reklama składa się z obrazu, a druga z filmu);
Podczas projektowania aplikacji musisz wybrać systematyczny sposób generowania identyfikatorów, który będzie odpowiedni dla typów kreacji, które planujesz przesłać.
Oznaczenie reklamy
Google zaleca deklarowanie atrybutów kreacji, aby opisywać charakterystykę reklamy i jej kierowanie za pomocą kombinacji BidResponse.seatbid.bid.apis i BidResponse.seatbid.bid.attr lub rozszerzenia BidResponse.seatbid.bid.ext.attribute. Poniżej znajdziesz opis sposobu deklarowania atrybutów:
VPAID
Ustaw wartość BidResponse.seatbid.bid.apis na VPAID_1 lub VPAID_2. W przypadku formatu JSON można ustawić odpowiednio wartość 1 lub 2.
MRAID
Ustaw BidResponse.seatbid.bid.apis na
MRAID_1 lub 3 w przypadku formatu JSON.
SIZELESS
Ustaw BidResponse.seatbid.bid.attr na RESPONSIVE lub 18 w przypadku formatu JSON.
PLAYABLE
Wskazuje to ustawienie wartości BidResponse.seatbid.bid.attr na USER_INTERACTIVE lub 13 w przypadku formatu JSON.
Więcej informacji o tym, jak uzyskać opinię na temat wykrytych właściwości kreacji, znajdziesz w tym artykule.
Pola Otwartego ustalania stawek
Odpowiedzi na stawki wysyłane przez licytujących z giełd i sieci uczestniczących w Otwartym ustalaniu stawek są podobne do odpowiedzi kupujących w Authorized Buyers uczestniczących w standardowym określaniu stawek w czasie rzeczywistym. Klienci korzystający z Otwartego ustalania stawek mogą określić niewielką liczbę dodatkowych pól, a kilka istniejących pól może mieć alternatywne zastosowania. Obejmują one:
Pole
Szczegóły
BidResponse.imp.pmp.deals.id
Identyfikator umowy z przestrzeni nazw giełdy, który jest powiązany z tą stawką i zgłaszany wydawcom.
BidResponse.seatbid.bid.ext.exchange_deal_type
Typ umowy zgłaszany wydawcom, który wpływa na sposób traktowania umowy w aukcji.
Token używany do identyfikowania informacji o kupującym zewnętrznym, jeśli wymiana jako uczestnik Otwartego ustalania stawek jest pośrednikiem. Jest ona uzyskiwana od kupującego zewnętrznego i musi być przekazywana do Google w odpowiedzi na pytanie o stawkę w niezmienionej formie.
Rekomendacje
Włącz na serwerach trwałe połączenia HTTPS (znane też jako „keep-alive” lub „ponowne wykorzystanie połączenia”). Ustaw limit czasu na co najmniej 10 sekund – w wielu przypadkach korzystne są wyższe wartości. Google weryfikuje to podczas wstępnych testów opóźnienia aplikacji, ponieważ Authorized Buyers wysyła żądania z dużą częstotliwością i musi unikać opóźnień związanych z nawiązywaniem osobnego połączenia TCP dla każdego żądania.
Dołącz opcjonalny link monitorujący wyświetlenia, aby śledzić, kiedy wyświetlenie jest renderowane, a nie kiedy wygrywa licytujący. Ze względu na różnicę między wygranymi a wyświetleniami zapewnia to dokładniejsze statystyki śledzenia.
Zadbaj o to, aby kod licytującego nie był zależny od wycofanych pól, co może powodować błędy w licytacjach.
Dołącz do BidResponse elementy BidResponse.seatbid.bid.w i BidResponse.seatbid.bid.h. Żądanie ABidResponse, które zawiera wiele rozmiarów reklam, musi zawierać te pola. W przeciwnym razie zostanie odrzucone z aukcji.
Ogranicz rozmiar odpowiedzi do mniej niż 8 KB. Bardzo duże odpowiedzi mogą zwiększać opóźnienie sieci i powodować przekroczenie czasu oczekiwania.
Ważne: wiadomości Protobuf przedstawione w przykładach są tu reprezentowane jako tekst czytelny dla człowieka. Jednak wiadomości nie są wysyłane w ten sposób. W przypadku korzystania z formatu OpenRTB Protobuf akceptowane będą tylko zserializowane wiadomości BidResponse.
Możesz utworzyć i zserializować wiadomość BidResponse za pomocą tego kodu 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
}
Określanie kreacji
Odpowiedź na stawkę określa kreację, która ma się wyświetlić, jeśli Twoja stawka wygra. Twoja stawka musi obejmować jeden z obsługiwanych formatów reklam (AMP, wideo, reklama natywna). W tym przykładzie określamy kreację za pomocą pola html_snippet.
Możesz też określić kreację, korzystając z jednego z tych pól w zależności od formatu reklamy:
Reklama renderowana przez pakiet SDK
BidResponse.seatbid.bid.ext.sdk_rendered_ad
AMP
BidResponse.seatbid.bid.amp_ad_url
Film
BidResponse.seatbid.bid.adm
Reklama natywna
BidResponse.seatbid.bid.adm_native
Określ reklamę hostowaną na Twoich serwerach, używając fragmentu kodu HTML w polu BidResponse.seatbid.bid.adm. Fragment kodu jest umieszczany w elemencie iframe wstawionym na stronie internetowej, co powoduje pobranie i wyświetlenie reklamy po wczytaniu strony. Musisz utworzyć fragment kodu HTML w taki sposób, aby reklama (banerowa lub pełnoekranowa) była prawidłowo renderowana w elemencie iframe i miała odpowiedni rozmiar w przypadku boksu reklamowego, w którym chcesz wyświetlać reklamy.
Dodatkowo rozmiar reklamy zadeklarowany w odpowiedzi na stawkę musi odpowiadać dokładnie jednej z kombinacji rozmiarów w pytaniu o stawkę, gdy:
Reklama to zwykły baner (nie wideo, natywny ani pełnoekranowy).
Licytujący zadeklarował rozmiar w odpowiedzi na stawkę. Deklaracja rozmiaru jest wymagana, gdy w żądaniu występuje więcej niż 1 rozmiar.
Wyjątkiem są reklamy pełnoekranowe. W przypadku reklam pełnoekranowych szerokość musi wynosić co najmniej 50% szerokości ekranu, a wysokość co najmniej 40% wysokości ekranu.
Kreację z fragmentem kodu HTML możesz określić za pomocą dowolnego prawidłowego kodu HTML, który jest prawidłowo renderowany. Pamiętaj jednak o ograniczeniach dotyczących określania pola crid w sekcji Tworzenie wiadomości BidResponse.
Można go używać do umieszczania dodatkowych informacji w argumentach adresów URL, które są pobierane z serwerów w ramach renderowania reklamy. Dzięki temu możesz przekazywać dowolne dane o wyświetleniu z powrotem na własne serwery.
Makra to sformatowany tekst umieszczony w niektórych polach odpowiedzi na stawkę, które zawierają adresy URL zastępowane odpowiednią wartością w momencie wyświetlania reklamy. Jeśli na przykład Twoja zwycięska stawka zawierała makro AUCTION_PRICE w fragmencie kodu HTML kreacji dołączonej do stawki, makro zostanie zastąpione wartością, którą możesz odszyfrować, aby określić kwotę zapłaconą za wyświetlenie w aukcji.
Makra możesz umieszczać w tych polach:
BidResponse.seatbid.bid.adm
Makra są obsługiwane w przypadku formatów fragmentu kodu HTML, kreacji natywnej, adresu URL filmu i pliku XML VAST wideo.
Użyj tego zamiast BidResponse.seatbid.bid.burl, jeśli potrzebujesz więcej niż 1 adresu URL rozliczeń.
Możesz na przykład umieścić makro w fragmencie kodu HTML, osadzając ${MACRO} w adresie URL używanym do pobierania kreacji, gdzie MACRO jest jednym z obsługiwanych makr opisanych w specyfikacji OpenRTB.
Makra Google
Google obsługuje dodatkowe makra poza tymi, które znajdują się w specyfikacji OpenRTB. Mają one inny format i po osadzeniu w adresie URL będą wyglądać jak %%MACRO%%. Tabela poniżej zawiera opis tych makr:
Makro
Opis
ADVERTISING_IDENTIFIER
Umożliwia kupującym otrzymywanie identyfikatora IDFA w iOS lub identyfikatora wyświetlania reklam na Androidzie podczas renderowania wyświetlenia.
Więcej informacji znajdziesz w sekcji Odszyfrowywanie identyfikatorów reklamodawców.
CACHEBUSTER
Ciąg znaków reprezentujący losową, nieujemną, 4-bajtową liczbę całkowitą.
CLICK_URL_UNESC
Docelowy URL reklamy bez zmiany znaczenia. W fragmencie kodu bezpośrednio po makrze powinna się znajdować wersja adresu URL firmy zewnętrznej do śledzenia kliknięć z zastąpionymi znakami specjalnymi.
Jeśli na przykład klikany URL firmy zewnętrznej to
http://my.adserver.com/some/path/handleclick?click=clk,
to po wywołaniu makra można użyć tego kodu z wersją klikanego adresu URL firmy zewnętrznej ze zmianą znaczenia:
Adres URL najpierw zarejestruje kliknięcie w Google, a potem przekieruje użytkownika na adres URL kliknięcia firmy zewnętrznej.
CLICK_URL_ESC
Adres URL kliknięcia reklamy po zastosowaniu znaków ucieczki. Użyj tego zamiast
CLICK_URL_UNESC, jeśli musisz najpierw przekazać wartość przez inny serwer, który następnie zwróci przekierowanie.
Na przykład w fragmencie kodu HTML można użyć tego kodu:
Spowoduje to zarejestrowanie kliknięcia w my.adserver.com, które następnie przekieruje użytkownika na adres URL przekazany w parametrze google_click_url. Zakładamy, że my.adserver.com usuwa znaki ucieczki z parametru google_click_url.
Po znaku %%CLICK_URL_ESC%% możesz dodać adres URL z podwójnym znakiem ucieczki. Po usunięciu znaków ucieczki przez my.adserver.com do elementu google_click_url zostanie dołączona wersja adresu URL z pojedynczym znakiem ucieczki. Gdy plik google_click_url zostanie pobrany, nastąpi ponowne usunięcie znaków specjalnych, a potem przekierowanie.
CLICK_URL_ESC_ESC
Adres URL reklamy ze zmianą znaczenia. Użyj tego zamiast CLICK_URL_UNESC, jeśli musisz najpierw przekazać wartość przez inny serwer, który następnie zwróci przekierowanie.
Na przykład w fragmencie kodu HTML można użyć tego kodu:
Rozszerzone do http:, jeśli żądanie stawki nie wymaga protokołu SSL, lub do https:, jeśli żądanie stawki wymaga protokołu SSL.
SITE
Domena adresu URL treści po zastosowaniu kodowania URL lub anonimowy identyfikator anonimowego asortymentu reklamowego.
SITE_URL
Rola wycofana. Zastąpione makrem SITE, które zapewnia identyczną funkcjonalność.
TZ_OFFSET
Przesunięcie strefy czasowej.
VERIFICATION
Różne wartości dotyczące produkcji i czasu skanowania kreacji w potoku weryfikacji. Format:%%?VERIFICATION:true-val:false-val%%, gdzie w przypadku true-val i false-val można użyć dowolnych wartości z wyjątkiem makr, w tym pustych ciągów znaków. W przypadku aukcji otwartych zalecamy, aby giełdy używały tego makra. Gdy to zrobią, platformy po stronie popytu nie będą musiały wprowadzać zmian.
Jeśli np. kreacja zawiera ciąg %%?VERIFICATION:-1:5000%%, podczas wyświetlania nastąpi zamiana tekstu na 5000, a w procesie weryfikacji na -1. Ma to na celu odróżnienie tych 2 rodzajów pingów.
WINNING_PRICE
Zakodowany koszt wyświetlenia (czyli CPI, a nie CPM) w mikrojednostkach waluty konta. Na przykład wygrywający CPM w wysokości 5 USD odpowiada CPM w wysokości 5 000 000 mikrojednostek lub CPI w wysokości 5000 mikrojednostek. W tym przypadku zdekodowana wartość WINNING_PRICE wyniesie 5000.
Zwycięska cena jest podana w CPI.
Aby przeanalizować to makro, musisz wdrożyć aplikację, która odszyfruje potwierdzenia ceny. Więcej informacji znajdziesz na stronie Odszyfrowywanie potwierdzeń ceny.
WINNING_PRICE_ESC
Adres URL z kodowaniem WINNING_PRICE.
Google wymaga, aby w kreacji reklamy wyświetlanej przez firmę zewnętrzną używać makra CLICK_URL_UNESC lub CLICK_URL_ESC. Google używa makr CLICK_URL do śledzenia kliknięć.
Zmiana znaczenia w makrach URL odbywa się według tego schematu:
Spacja jest zastępowana znakiem plusa (+).
Znaki alfanumeryczne (0–9, a–z, A–Z) i znaki z zestawu !()*,-./:_~ pozostają bez zmian.
Wszystkie inne znaki są zastępowane znakiem %XX, gdzie XX to szesnastkowa liczba reprezentująca znak.
Ograniczenia i wymagania dotyczące wydawców
Pytanie o stawkę zawiera informacje o rodzajach ograniczeń i wymagań, które wydawcy nakładają na kreacje na aukcji.
BidRequest.bcat
Możesz porównać zablokowane kategorie określone w tym polu z kategoriami wykrytymi w przypadku przesłanych kreacji za pomocą pola detectedCategories interfejsu Real-Time Bidding API.
BidRequest.imp.ext.allowed_vendor_type
BidRequest.imp.secure
W praktyce ta wartość będzie zawsze ustawiona na true, ponieważ Google wymaga obsługi SSL we wszystkich kreacjach.
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
Nigdy nie licytuj reklam zawierających funkcje podlegające ograniczeniom. W przypadku dozwolonych funkcji, takich jak typ dostawcy, zwracaj reklamę tylko wtedy, gdy jej typ dostawcy znajduje się na liście allowed_vendor_type w parametrze BidRequest. W odpowiedzi na stawkę uwzględniaj tylko formaty reklam określone w pytaniu o stawkę przez wypełnienie pól takich jak BidRequest.imp.banner. Więcej informacji znajdziesz w komentarzach do tych pól w BidRequestdefinicji bufora protokołuBidRequest.
Jeśli reklama jest zwracana w BidResponse, musisz dokładnie ustawić pola BidResponse.seatbid.bid.attr, BidResponse.seatbid.bid.cat oraz BidResponse.seatbid.bid.adomain lub BidResponse.seatbid.bid.adm_native.link.url w BidResponse. Jeśli reklama ma kilka odpowiednich wartości w tych polach, musisz uwzględnić każdą z nich. Więcej informacji znajdziesz w komentarzach do tych pól w definicji bufora protokołu BidResponse.
Odpowiedzi, w których nie ustawiono tych pól, są odrzucane.
Open Measurement
Open Measurement umożliwia określanie zewnętrznych dostawców, którzy świadczą niezależne usługi pomiaru i weryfikacji reklam wyświetlanych w aplikacjach mobilnych.
Obsługiwane formaty reklam to reklamy wideo, banery i reklamy pełnoekranowe. Więcej informacji o tym, jak używać Open Measurement w odpowiedzi na reklamę zawierającej te formaty, znajdziesz w artykule w Centrum pomocy na temat pakietu Open Measurement SDK.
Przykładowe odpowiedzi na stawkę
W sekcjach poniżej znajdziesz przykładowe odpowiedzi na żądania stawek w przypadku różnych typów reklam.
id:"550102L8So5v6gi4C00T36"seatbid{bid{id:"U796oSA426V3U666ue8"impid:"1"price:1.057860016822815crid:"test_creative_id_395811"dealid:"0"adm_native{ver:"1.2"assets{id:6img{url:"https://native.test.com/logo?id=123456"w:200h:200type:LOGO}}assets{id:5img{url:"https://native.test.com/image?id=123456"w:800h:800type:MAIN}}assets{id:4data{value:"Galactic Luxury Cruises"type:SPONSORED}}assets{id:3data{value:"Book today"type:CTATEXT}}assets{id:1title{text:"Luxury Mars Cruises"}}assets{id:2data{value:"Visit the planet in a luxury spaceship."type:DESC}}link{url:"https://www.google.com"}}[com.google.doubleclick.bid]{impression_tracking_url:"https://test.com/impression?id=123456"impression_tracking_url:"https://test.com/impression?id=123456"ad_choices_destination_url:"https://test.com/preferences"event_notification_token{payload:"token"}billing_id:73917825312dsa{adrender:true}clickurl:"google.com"}}}cur:"JPY"[com.google.doubleclick.bid_response]{processing_time_ms:17}
OpenRTB JSON
Pokaż przykład
{"id":"550102L8So5v6gi4C00T36","seatbid":[{"bid":[{"id":"U796oSA426V3U666ue8","impid":"1","price":1.057860016822815,"crid":"test_creative_id_395811","dealid":"0","ext":{"impression_tracking_url":["https://test.com/impression?id=123456","https://test.com/impression?id=123456"],"ad_choices_destination_url":"https://test.com/preferences","event_notification_token":{"payload":"token"},"billing_id":"73917825312","dsa":{"adrender":1},"clickurl":["google.com"]},"adm":"{\"ver\":\"1.2\",\"assets\":[{\"id\":6,\"img\":{\"url\":\"https://native.test.com/logo?id=123456\",\"w\":200,\"h\":200,\"type\":2}},{\"id\":5,\"img\":{\"url\":\"https://native.test.com/image?id=123456\",\"w\":800,\"h\":800,\"type\":3}},{\"id\":4,\"data\":{\"value\":\"Galactic Luxury Cruises\",\"type\":1}},{\"id\":3,\"data\":{\"value\":\"Book today\",\"type\":12}},{\"id\":1,\"title\":{\"text\":\"Luxury Mars Cruises\"}},{\"id\":2,\"data\":{\"value\":\"Visit the planet in a luxury spaceship.\",\"type\":2}}],\"link\":{\"url\":\"https://www.google.com\"}}"}]}],"cur":"JPY","ext":{"processing_time_ms":17}}
[null,null,["Ostatnia aktualizacja: 2026-02-23 UTC."],[],["Applications must respond to each `BidRequest` with a parsable `BidResponse`, using Protobuf or an HTTP 204 for no bids. Creatives are identified by a unique `crid`. Ad attributes, such as VPAID and MRAID, are declared in specific fields. Utilize impression tracking URLs and avoid deprecated fields. Open Bidding bid responses are similar to Authorized Buyers. Ad sizes in the response must match the request. Macros are used in URLs. Publisher requirements are specified in the `BidRequest`. The response must accurately reflect these requirements and provide the accurate ad attributes and links.\n"]]
