Budowanie reakcji

Gdy aplikacja przetworzy żądanie stawki od Google, musi utworzyć i wysłać odpowiedź. Ten przewodnik wyjaśnia, jak pisać kod aplikacji na potrzeby kompilacji odpowiedź.

Tworzenie wiadomości Protobuf BidResponse

Authorized Buyers wysyła parametr BidRequest jako treść wiadomości POST HTTP. Jeśli punkt końcowy ustalania stawek jest skonfigurowany do używania w formacie Protobuf, aplikacja musi wysyłać odpowiedź z atrybutem Nagłówek Content-Type został ustawiony na application/octet-stream i treści wiadomości składającej się z bufora zserializowanego protokołu. Protokół bufor to komunikat BidResponse zgodny z definicją openrtb.proto Aplikacja musi zwracać plik, który można przeanalizować BidResponse w odpowiedzi na każde BidRequest. tymczasowe zawieszenie użytkownika i odpowiedzi, których nie można przeanalizować, są uznawane za błędy, a Google ogranicza licytujących z dużym odsetkiem błędów.

Jeśli nie chcesz ustalać stawki za wyświetlenie, możesz ustawić BidResponse.ext.processing_time_ms bez zmian i pozostaw wszystkie inne pola są puste. openrtb.proto możesz uzyskać z danych referencyjnych.

Identyfikator kreacji

Twój element BidResponse określa kreację za pomocą pola BidResponse.seatbid.bid.crid (limit 64 bajtów). Podobne kreacje muszą mieć unikalne wartości w tym polu, jeśli różnią się w żadnych istotnych cech, takich jak rozmiar, zadeklarowany adres URL, atrybutów kreacji i typów dostawców. Innymi słowy, musisz nadać różne identyfikatory kreacji dowolnym 2 reklamami, które:

  • wyglądać lub zachowywać się inaczej;
  • Renderowanie do różnych obrazów.
  • renderowanie w różny sposób (np. jedna reklama składa się z obrazu, a drugi to film).

Projektując aplikację, należy wybrać systematyczny sposób generowanie identyfikatorów dopasowanych do rodzajów planowanych kreacji do przesłania.

Oznaczenie reklamy

Google zaleca zadeklarowanie atrybutów kreacji, by opisać cech i kierowania reklam za pomocą kombinacji BidResponse.seatbid.bid.apis i BidResponse.seatbid.bid.attr lub BidResponse.seatbid.bid.ext.attribute rozszerzenie. Poniżej znajdziesz opis sposobu deklarowania atrybutów:

  • VPAID
    Ustaw BidResponse.seatbid.bid.apis na VPAID_1, lub VPAID_2. W przypadku formatu JSON można ją ustawić na 1 lub 2.
  • MRAID
    Ustaw wartość BidResponse.seatbid.bid.apis na MRAID_1 lub 3 w przypadku formatu JSON.
  • SIZELESS
    Ustaw wartość BidResponse.seatbid.bid.attr na RESPONSIVE lub 18 w przypadku formatu JSON.
  • PLAYABLE
    Jest to sygnalizowane przez ustawienie BidResponse.seatbid.bid.attr do USER_INTERACTIVE lub 13 w przypadku JSON .
.

Zobacz Zasób kreacji , gdzie znajdziesz wyjaśnienie, jak uzyskać opinie na temat wykrytych właściwości za pomocą kreacji.

Pola Otwartego ustalania stawek

Odpowiedzi na stawkę wysyłane przez licytujących z giełd i sieci uczestniczących w otwarciu Określanie stawek jest podobne do tych w Authorized Buyers, którzy uczestniczą w standardowym określania stawek w czasie rzeczywistym. Klienci korzystający z otwartego ustalania stawek mogą podać niewielką liczbę dodatkowych pól, a kilka dotychczasowych pól może mieć inne zastosowanie. Te należy uwzględnić następujące elementy:

OpenRTB Authorized Buyers. Szczegóły
BidResponse.imp[].pmp.deals[].id BidResponse.ad[].adslot[].exchange_deal_id

Identyfikator umowy z przestrzeni nazw giełdy powiązanej z tym i raportowana wydawcom.

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

typ umowy zgłaszanej wydawcom, który ma wpływ na sposób realizacji umowy; traktowanych w aukcji.

BidResponse.seatbid[].bid[].ext.third_party_buyer_token BidResponse.ad[].adslot[].third_party_buyer_token Token służący do identyfikowania informacji o kupującym, jeśli giełda jako uczestnik Otwartego ustalania stawek jest pośrednikiem. Wartość ta jest uzyskiwana od zewnętrznego kupującego i musi zostać przekazana do Google w niezmienionej postaci w odpowiedzi na pytanie o stawkę.

Rekomendacje

  • Włącz stałe połączenia HTTPS (zwane też „utrzymaniem aktywności” lub „ponowne użycie połączenia”) na Twoich serwerach. Ustaw limit czasu na co najmniej 10 sekund – w wielu przypadkach korzystne są wyższe wartości. Google weryfikuje podczas wstępnych testów czasu oczekiwania aplikacji, ponieważ Usługa Authorized Buyers często wysyła żądania i musi unikać narzut czasu oczekiwania związanego z nawiązaniem oddzielnego połączenia TCP dla każdego użytkownika.
  • Dodaj opcjonalny link monitorujący wyświetlenia, aby śledzić, kiedy wyświetlenie zostało wyrenderowane, a nie kiedy wygrał licytujący. Ze względu na różnicę między wygranymi a wyrenderowaniami uzyskujesz dokładniejsze statystyki śledzenia.

  • Upewnij się, że kod licytującego nie jest zależny od wycofanych pól, które mogą powodować błędy w ustalaniu stawek.
  • W pliku BidResponse uwzględnij właściwości BidResponse.seatbid.bid.wBidResponse.seatbid.bid.h. BidResponse do żądania zawierającego wiele rozmiarów reklam musi zawierać te pola, w przeciwnym razie zostanie wykluczone z aukcji.
  • Ogranicz rozmiar odpowiedzi do 8 K. Bardzo duże odpowiedzi mogą zwiększyć i powodują przekroczenie czasu oczekiwania.
  • Postępuj zgodnie z wytycznymi dotyczącymi stawek za zasoby reklamowe na iOS, które wymagają atrybucji SKAdNetwork.

Przykładowa odpowiedź na pytanie o stawkę

Poniższe przykłady przedstawiają czytelne dla człowieka próbki Protobuf i Żądania JSON.

OpenRTB Protobuf

OpenRTB w formacie JSON

Google

Ważne: komunikaty Protobuf przedstawione w próbkach są tu reprezentowane jako tekst zrozumiały dla człowieka. Nie jest to jednak wiadomości są wysyłane przewodowo. W przypadku korzystania z formatu Protobuf Google lub OpenRTB akceptowane są tylko serializowane 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 zostanie wyświetlona, gdy Twoja stawka wygra. Twoja stawka musi zawierać jeden z obsługiwanych formatów reklam (AMP, wideo, natywny). W tym podajemy kreację w polu html_snippet.

Możesz też określić kreację za pomocą 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

Podaj reklamę hostowaną na własnych serwerach, używając fragmentu kodu HTML w polu BidResponse.seatbid.bid.adm. Fragment jest zawarty w element iframe umieszczony na stronie, co powoduje pobranie reklamy, renderowane podczas wczytywania strony. Musisz utworzyć fragment kodu HTML, tak aby (baner lub reklama pełnoekranowa) renderuje się prawidłowo w elemencie iframe oraz rozmiar odpowiedni dla boksu reklamowego, dla którego licytujesz.

Dodatkowo rozmiar reklamy zadeklarowany w odpowiedzi na stawkę musi odpowiadać dokładnie 1 kombinacji rozmiarów w pytaniu o stawkę, gdy:

  • Reklama jest zwykłym banerem (nie wideo, natywnym ani pełnoekranowym).
  • Licytujący zadeklarował rozmiar w odpowiedzi na stawkę. Obecna deklaracja rozmiaru wymagane, jeśli w żądaniu występuje więcej niż jeden 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.

Możesz określić fragment kodu HTML za pomocą dowolnego prawidłowego kodu HTML, który renderuje się poprawnie, ale należy pamiętać o ograniczeniach crid w polu Sekcja Utwórz wiadomość na temat odpowiedzi na stawkę. Jednym z zastosować jest umieszczanie dodatkowych informacji w argumentach adresów URL pobieranych z Twoich serwerów w ramach renderowania reklamy. Dzięki temu możesz przekazać na własne serwery dowolne dane o wyświetleniu.

Większość zasad dotyczących fragmentów kodu HTML zwracanych w odpowiedziach na żądanie stawki jest takich samych jak w przypadku reklam innych firm. Zobacz Authorized Buyers Wytyczne programu, Wymagania dla firm zewnętrznych wyświetlanie reklam i Zadeklaruj, docelowych adresów URL w reklamach.

Określanie makr

Makra to sformatowany tekst umieszczony w niektórych polach odpowiedzi na stawkę, które zawierają Adresy URL, które są zastępowane odpowiednią wartością w czasie wyświetlania reklamy. Przykład: jeśli zwycięska stawka zawiera makro AUCTION_PRICE w kodzie HTML fragment kodu zostanie dodany do stawki, makro zostanie zastąpione wartość, którą możesz odszyfrować, by określić kwotę zapłaconą za wyświetlenie aukcji.

Makra możesz umieszczać w tych polach:

  • BidResponse.seatbid.bid.adm

    Makra są obsługiwane w przypadku formatów fragmentu kodu HTML, natywnego, adresu URL wideo i wideo VAST XML.

  • BidResponse.seatbid.bid.adm_native.eventtrackers.url

  • BidResponse.seatbid.bid.adm_native.imptrackers

  • BidResponse.seatbid.bid.ext.amp_ad_url

    Tylko WINNING_PRICE i Makra WINNING_PRICE_ESC są obsługiwane w przypadku kreacji AMP.

  • BidResponse.seatbid.bid.burl

  • BidResponse.seatbid.bid.ext.impression_tracking_url

    Użyj tej opcji zamiast BidResponse.seatbid.bid.burl, jeśli: wymagają więcej niż 1 adresu URL do rozliczeń.

Możesz np. umieścić makro w fragmentie kodu HTML, umieszczając w adresie URL używanym do pobierania kreacji makro ${MACRO}, gdzie MACRO to jedno z obsługiwanych makro opisanych w specyfikacji OpenRTB.

Makra Google RTB

Google obsługuje dodatkowe makropolecenia oprócz tych, które znajdują się w specyfikacji OpenRTB. Są one sformatowane inaczej i będą wyglądać jak %%MACRO%%, jeśli zostaną umieszczone w adresie URL. W tabeli poniżej opisano te makro:

Makro Opis
ADVERTISING_IDENTIFIER Umożliwia kupującym otrzymywanie identyfikatora IDFA w iOS lub identyfikatora wyświetlania reklam (AdID) w Androidzie podczas renderowania wyświetlenia. Przeczytaj sekcję Odszyfrowywanie identyfikatorów reklamodawcy. .
CACHEBUSTER Ciąg znaków reprezentujący losową, bezznakową liczbę całkowitą o czterech bajtach.
CLICK_URL_UNESC

Niezmodyfikowany adres URL kliknięcia reklamy. W fragmentach kodu bezpośrednio po makrze powinna znajdować się ujęta w znaki ucieczki wersja adresu URL kliknięcia firmy zewnętrznej.

Jeśli na przykład klikany URL firmy zewnętrznej to http://my.adserver.com/some/path/handleclick?click=clk, poniższego kodu można użyć z wersją z pojedynczą zmianą znaczenia klikalnego adresu URL firmy zewnętrznej po wywołaniu makra:

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

W momencie wyświetlania reklamy wartość ta jest rozszerzana do:

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

Adres URL najpierw rejestruje kliknięcie w Google, a potem przekierowuje do adresu URL kliknięcia należącego do firmy zewnętrznej.

CLICK_URL_ESC

Ucieczka adresu URL kliknięcia reklamy. Użyj tego zamiast CLICK_URL_UNESC, jeśli musisz najpierw przekazać wartość przez inny serwer, który zwróci przekierowanie.

We fragmencie HTML można na przykład wykorzystać ten kod:

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

W momencie wyświetlania reklamy wartość ta jest rozszerzana do:

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

Spowoduje to zarejestrowanie kliknięcia przez operatora my.adserver.com, który będzie odpowiadał za przekierowanie do adresu URL przekazanego w metodzie google_click_url. Zakładamy, że funkcja my.adserver.com dekoduje parametr google_click_url.

Możesz dołączyć adres URL z podwójną zmianą znaczenia po %%CLICK_URL_ESC%% Po odkodowaniu przez my.adserver.com pozostaje wersja adresu URL ze zmianą znaczenia dołączona do google_click_url. Gdy Pole google_click_url zostało pobrane, cofnie ono znaczenie jeszcze raz a następnie przekieruj.

CLICK_URL_ESC_ESC

Podwójnie ujęty w znaki cudzysłowe adres URL reklamy. Użyj tego zamiast CLICK_URL_UNESC, jeśli musisz najpierw przekazać wartość przez inny serwer, który zwróci przekierowanie.

W fragmentach kodu HTML można na przykład użyć tego kodu:

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

W momencie wyświetlania reklamy rozwijamy się do postaci:

<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 Rozwinięte do http:, jeśli żądanie stawki nie wymaga protokołu SSL, lub do https:, jeśli żądanie stawki wymaga protokołu SSL.
SITE Domena z ucieczkami znaków w adresie URL treści lub anonimowy identyfikator w przypadku anonimowego asortymentu.
SITE_URL Rola wycofana. Zastąpione makrem SITE, które działa identycznie.
TZ_OFFSET przesunięcie strefy czasowej.
VERIFICATION

różne wartości w przypadku produkcji i skanowania kreacji w systemie weryfikacji. Format to: %%?VERIFICATION:true-val:false-val%%, gdzie dowolne wartości oprócz makr można używać w elementach true-val i false-val, w tym puste ciągi. W przypadku Otwartego ustalania stawek zaleca korzystanie z tego makra; gdy już to zrobią, system DSP które nie wymagają wprowadzania zmian.

Jeśli na przykład kreacja ma zawierać %%?VERIFICATION:-1:5000%%, potem zamiana tekstu to 5000 przy wyświetlaniu i -1 w procesu weryfikacji. Pomoże to odróżnić dwa zestawy pingów.

WINNING_PRICE

Koszt zakodowanego wyświetlenia (czyli CPI, a nie CPM) w mikroach waluty konta. Na przykład wygrany CPM w wysokości 5 USD odpowiada CPM w wysokości 5 000 000 milionowych części jednostki lub CPI w wysokości 5 000 milionowych części jednostki. Zdekodowany wartość WINNING_PRICE w tym przypadku wyniesie 5000. Zwycięska cena jest podana w CPI.

Aby przeanalizować to makro, musisz wdrożyć aplikację, która odszyfrowuje potwierdzenia cen. Zapoznaj się z Odszyfrowywanie potwierdzeń cen .

WINNING_PRICE_ESC WINNING_PRICE ze zmianą znaczenia w adresie URL.

Google wymaga, aby w kreacji reklamy obsługiwanej przez firmę zewnętrzną używać makra CLICK_URL_UNESC lub CLICK_URL_ESC. Google używa makro CLICK_URL do śledzenia kliknięć.

Zmiana znaczenia adresu URL w makrach korzysta z tego schematu:

  • Znak odstępu jest zastępowany znakiem plusa (+).
  • Znaki alfanumeryczne (0–9, a–z, A–Z) oraz znaki z zestawu !()*,-./:_~ pozostają niezmienione.
  • Wszystkie inne znaki są zastępowane przez %XX, gdzie XX to szesnastkowa liczba reprezentująca znak.

Ograniczenia i wymagania dotyczące wydawców

Pytanie o stawkę zawiera informacje o rodzajach ograniczeń wymagania nakładane przez wydawców na kreacje biorące udział w aukcji.

  • BidRequest.bcat
    • Możesz porównać zablokowane kategorie określone w tym polu z kategoriami wykrytymi w przesłanych kreacjach za pomocą pola detectedCategories w interfejsie Real-time Bidding API.
  • BidRequest.imp.ext.allowed_vendor_type
  • BidRequest.imp.secure
    • W praktyce zawsze będzie to wartość true, ponieważ Google wymaga obsługi protokołu 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 reklamy zawierającej funkcję podlegającą ograniczeniom. W przypadku dozwolonych funkcji, takich jak typ dostawcy, zwracaj reklamę tylko wtedy, gdy typ dostawcy znajduje się na liście allowed_vendor_type w sekcji BidRequest. W stawce powinny być uwzględnione tylko formaty reklam określone w pytaniu o stawkę przez wypełnienie pól takich jak BidRequest.imp.banner. Zobacz komentarze do tych pól w buforze protokołu BidRequest .

Jeśli reklama zostanie zwrócona w tym kraju: BidResponse, musisz wykonać te czynności: dokładnie ustaw BidResponse.seatbid.bid.attr, BidResponse.seatbid.bid.cat oraz BidResponse.seatbid.bid.adomain lub BidResponse.seatbid.bid.adm_native.link.url pól w BidResponse Jeśli reklama ma wiele odpowiednich wartości w tych przypadkach musisz uwzględnić wszystkie wartości. Wyświetl komentarze do tych pól w języku: definicji bufora protokołu BidResponse, aby dowiedzieć się więcej. Odpowiedzi, które nie mają ustawionych pól, są odrzucane.

Open Measurement

Open Measurement pozwala wskazać zewnętrznych dostawców świadczących usługi usługi pomiaru i weryfikacji w przypadku reklam wyświetlanych w aplikacjach mobilnych w różnych środowiskach.

Obsługiwane formaty reklam to reklamy wideo, banery i reklamy pełnoekranowe. Więcej o użyciu Open Measurement w odpowiedzi na stawkę, która zawiera te zapoznaj się z informacjami o pakiecie SDK Open Measurement. artykule w Centrum pomocy.

Przykładowe odpowiedzi na stawkę

W następnych sekcjach znajdziesz przykładowe odpowiedzi na żądanie stawki w przypadku różnych typów reklam.

Baner aplikacji

OpenRTB Protobuf

OpenRTB w formacie JSON

Google

Reklama pełnoekranowa w aplikacji

Bufor protokołu OpenRTB

OpenRTB w formacie JSON

Google

Pełnoekranowa reklama wideo w aplikacji

OpenRTB Protobuf

Google

Reklama natywna w aplikacji

Bufor protokołu OpenRTB

OpenRTB w formacie JSON

Google

Film internetowy

Google

Baner internetowy na komórki dla licytujących w giełdzie

OpenRTB Protobuf