Gdy aplikacja przetworzy pytanie o stawkę od Google, musi utworzyć i wysłać odpowiedź. W tym przewodniku wyjaśniono, jak zakodować aplikację, aby wygenerować odpowiedź.
Utwórz wiadomość z odpowiedzią na stawkę
Authorized Buyers wysyła BidRequest
jako treść komunikatu HTTP POST
. Odpowiedź wysyłana przez aplikację musi mieć nagłówek Content-Type
ustawiony na application/octet-stream
, a treść wiadomości zawierająca bufor zserializowanego protokołu. Bufor protokołu to komunikat BidResponse
zgodny z definicją w realtime-bidding.proto
. W odpowiedzi na każdy typ BidRequest
aplikacja musi zwracać możliwy do przeanalizowania element BidResponse
. Czasy oczekiwania i odpowiedzi, których nie można przeanalizować, są uznawane za błędy. Google ogranicza licytujących z dużym odsetkiem błędów.
Jeśli nie chcesz ustalać stawki za wyświetlenie, możesz ustawić tylko pole processing_time_ms
, a wszystkie pozostałe pola pozostawić puste. Źródło danych realtime-bidding.proto
znajdziesz na stronie danych referencyjnych.
Identyfikator kreacji
BidResponse
określa kreację w polu buyer_creative_id
(maksymalnie 64 bajty). Nawet podobne kreacje muszą mieć unikalne wartości parametru buyer_creative_id
, jeśli różnią się
istotnymi cechami, takimi jak rozmiar, zadeklarowany adres URL, atrybuty kreacji i typy dostawców. Inaczej mówiąc, musisz przyznać różne
identyfikatory kreacji w przypadku 2 reklam, które:
- Wyglądać lub zachowywać się inaczej.
- Renderuj na różnych obrazach.
- Renderuj je na różne sposoby (np. jedna reklama składa się z obrazu, a druga zawiera Flasha).
Podczas projektowania aplikacji opracuj systematyczny sposób generowania identyfikatorów, który będzie odpowiedni dla typów przesyłanych kreacji.
Oznaczenie reklamy
Atrybuty kreacji, które w pełni opisują cechy reklamy i jej ustawienia kierowania, musisz zadeklarować w polu BidResponse.Ad.attribute
. Atrybuty, które trzeba zadeklarować (pełną listę obsługiwanych atrybutów znajdziesz na stronie buyer-declarable-creative-attributes.txt):
7 Tagging: IsTagged
Reklama zawiera w sobie piksel lub obraz jednopikselowy służący do tworzenia listy identyfikatorów plików cookie do późniejszego remarketingu.8 Remarketing: IsRemarketing
Reklama jest kierowana na użytkowników na podstawie identyfikatora pliku cookie lub identyfikatora urządzenia, gdzie lista identyfikatorów plików cookie lub identyfikatorów urządzeń to zbiór konsumentów, którzy wcześniej weszli w interakcję z witryną należącą do kupującego lub przez niego reprezentowaną.9 UserInterestTargeting: IsUserInterestTargeted
Reklama jest kierowana na użytkowników na podstawie ich identyfikatora pliku cookie lub identyfikatora urządzenia, gdzie lista identyfikatorów plików cookie lub identyfikator urządzenia to zbiór konsumentów zdefiniowanych jako grupa o wspólnych zainteresowaniach.30 InstreamVastVideoType: Vpaid
Reklama do renderowania wymaga obsługi VPAID.32 MraidType: MRAID
Reklama wymaga do renderowania interfejsu API MRAID.
Dodatkowo obsługiwane są te atrybuty, ale ich deklaracja nie jest wymagana, ponieważ Authorized Buyers automatycznie je wykrywa i blokuje (lub zezwala na) kreacje na podstawie wykrytych wartości, a nie Twojej deklaracji. Więcej informacji o sposobie uzyskiwania opinii o wykrytych właściwościach kreacji znajdziesz w artykule Interfejs Kreacje API.
34 RichMediaCapabilityType: RichMediaCapabilityFlash
Reklama wymaga obsługi Flasha.50 RichMediaCapabilityType: RichMediaCapabilityNonFlash
Reklama nie wymaga Flasha do renderowania.47 RichMediaCapabilityType: RichMediaCapabilitySSL
Reklama może się renderować na stronie SSL. Pamiętaj, że w Authorized Buyers kreacje z różnymi zadeklarowanymi wartościami tego atrybutu są traktowane jako osobne (będą sprawdzane oddzielnie i mają inny stan zatwierdzenia). Dlatego jeśli ustalasz stawki zarówno dla wersji SSL, jak i niez SSL, musisz odpowiednio zadeklarować ten atrybut, aby to rozróżnienie zostało odpowiednio odzwierciedlone w AdX.
Pola Otwartego ustalania stawek
Odpowiedzi na stawkę wysyłane przez licytujących z giełd i sieci uczestniczących w Otwartym ustalaniu stawek są podobne do odpowiedzi z programu Authorized Buyers, które uczestniczą 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 dotychczasowych pól może mieć alternatywne zastosowania. Mogą to być m.in.:
OpenRTB | Authorized Buyers; | Szczegóły |
---|---|---|
BidResponse.imp[].pmp.deals[].id |
BidResponse.ad[].adslot[].exchange_deal_id |
Identyfikator umowy z przestrzeni nazw giełdy, która jest powiązana z tą stawką i zgłoszona do wydawców. |
BidResponse.seatbid[].bid[].ext.exchange_deal_type |
BidResponse.ad[].adslot[].exchange_deal_type |
Typ umowy zgłoszony do wydawców, który wpływa na sposób jej obsługi podczas aukcji. |
BidResponse.seatbid[].bid[].ext.third_party_buyer_token |
BidResponse.ad[].adslot[].third_party_buyer_token |
Token używany do identyfikowania informacji o kupującym zewnętrznym, jeśli giełda jako dostawca Otwartego ustalania stawek jest pośrednikiem. Są one uzyskiwane od zewnętrznego kupującego i muszą być przekazywane do Google bez wprowadzania zmian w odpowiedzi na stawkę. |
Rekomendacje
- Włącz trwałe połączenia HTTPS na swoich serwerach (nazywane też „utrzymywaniem aktywności” lub „ponownym używaniem połączenia”). Ustaw limit czasu na co najmniej 10 sekund – wyższe wartości w wielu przypadkach są korzystne. Google weryfikuje to podczas wstępnych testów czasu oczekiwania Twojej aplikacji, ponieważ Authorized Buyers wysyła żądania bardzo często i musi uniknąć opóźnień, które wynikają z utworzenia osobnego połączenia TCP dla każdego żądania.
Dołącz opcjonalny link monitorujący wyświetlenia, by śledzić wyrenderowanie wyświetlenia, a nie moment, w którym licytujący wygrał. Ze względu na spadek liczby wygranych i wyrenderowań zapewnia to dokładniejsze statystyki śledzenia.
- Zadbaj o to, aby kod licytującego nie był zależny od wycofanych pól, bo może to powodować błędy przy ustalaniu stawek.
- Dodaj
BidResponse.Ad.width
iBidResponse.Ad.height
do:BidResponse
. ŻądanieBidResponse
w żądaniu, które zawiera wiele rozmiarów reklam, musi zawierać wartościwidth
iheight
. W przeciwnym razie zostanie ono usunięte z aukcji. - Ogranicz rozmiar odpowiedzi do mniej niż 8K. Bardzo duże odpowiedzi mogą zwiększyć opóźnienie sieci i spowodować przekroczenie czasu oczekiwania.
- Postępuj zgodnie ze wskazówkami dotyczącymi ustalania stawek za zasoby reklamowe na iOS, które wymagają atrybucji SKAdNetwork.
Przykładowa odpowiedź na stawkę
Poniższe przykłady przedstawiają zrozumiałe dla człowieka próbki żądań Protobuf i JSON.
Plik JSON OpenRTB
Protobuf OpenRTB
Ważne: wiadomości Protobuf przedstawione w przykładach są przedstawione tutaj jako tekst zrozumiały dla człowieka. Jednak nie w ten sposób wiadomości są przesyłane przewodowo. Jeśli używasz formatu Google lub OpenRTB Protobuf, akceptowane są tylko zserializowane wiadomości na żądanie odpowiedzi na stawkę.
Komunikat BidResponse
możesz utworzyć i zserializować 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 }
Wybierz kreację
Odpowiedź na stawkę określa kreację, która ma zostać wyświetlona, jeśli Twoja stawka wygrana. Stawka musi obejmować jeden z obsługiwanych formatów reklam (AMP, wideo, natywna). W tym przykładzie kreację określamy w polu html_snippet
.
W zależności od formatu reklamy możesz też określić kreację, używając jednego z tych pól:
- Reklama wyrenderowana przez pakiet SDK
BidResponse.Ad.sdk_rendered_ad
- AMP
BidResponse.Ad.amp_ad_url
- Film
BidResponse.Ad.video_url
lubBidResponse.Ad.video_vast_xml
- Reklama natywna
BidResponse.Ad.native_ad
Określ reklamę hostowaną na Twoich serwerach, korzystając z fragmentu kodu HTML w polu html_snippet
interfejsu BidResponse
. Fragment kodu jest umieszczany w elemencie iframe wstawionym na stronie internetowej, dzięki czemu reklama jest pobierana i renderowana po wczytaniu strony. Musisz przygotować fragment kodu HTML w taki sposób, aby reklama (baner lub reklama pełnoekranowa) renderowała się prawidłowo w elemencie iframe i miewała odpowiedni rozmiar pod kątem boksu reklamowego, za pomocą którego ustalasz stawkę.
Poza tym rozmiar reklamy zadeklarowany w odpowiedzi na stawkę musi odpowiadać dokładnie jednej z kombinacji rozmiarów w pytaniu o stawkę, jeśli:
- Reklama to zwykły baner (nie wideo, natywna ani pełnoekranowa).
- Licytujący zadeklarował rozmiar w odpowiedzi na stawkę. Deklaracja rozmiaru jest wymagana, gdy żądanie zawiera więcej niż 1 rozmiar.
- Wyjątkiem są reklamy pełnoekranowe. Reklamy pełnoekranowe muszą mieć co najmniej 50% szerokości i wysokości co najmniej 40% wysokości ekranu.
Pole html_snippet
obsługuje dowolny prawidłowy kod HTML, który renderuje się prawidłowo, ale pamiętaj o ograniczeniach związanych z określaniem pola buyer_creative_id
w sekcji Tworzenie wiadomości na stawkę na stawkę. Można to wykorzystać na przykład do umieszczenia dodatkowych informacji w argumentach adresów URL pobieranych z Twoich serwerów w ramach renderowania reklamy. Dzięki temu możesz przesyłać dowolne dane o wyświetleniach z powrotem do Twoich serwerów.
Większość zasad dotyczących fragmentów kodu HTML zwracanych w odpowiedziach na pytania o stawkę jest taka sama jak w przypadku reklam firm zewnętrznych. Więcej informacji znajdziesz w artykułach Wytyczne programu Authorized Buyers, Wymagania dotyczące wyświetlania reklam firm zewnętrznych i Deklarowanie docelowych adresów URL w reklamach.
Określanie makr
Fragment kodu HTML definiujący kreację może zawierać jedną lub więcej specjalnych konstrukcji nazywanych makrami. W momencie wyświetlania reklam wartości są zastępowane makrami. Na przykład aplikacja do określania stawek przez klienta może użyć makra WINNING_PRICE
do określenia, ile kosztowała reklama, jeśli wygra aukcję. Aby przeanalizować to makro, musisz wdrożyć aplikację, która odszyfrowuje potwierdzenia cen. Więcej informacji znajdziesz na stronie Odszyfrowywanie potwierdzenia ceny.
Określ makro jako część fragmentu kodu HTML w formacie %%MACRO%%
, gdzie MACRO
to jedno z obsługiwanych makr wymienionych w tabeli poniżej.
Google wymaga użycia w kreacji takiej reklamy makra CLICK_URL_UNESC
lub CLICK_URL_ESC
. Do śledzenia kliknięć Google używa makr CLICK_URL
.
Aby użyć makra, umieść je w reklamie, tak aby adres URL był pobierany, gdy ktoś go kliknie. Zwracana wartość pobierania to przekierowanie do innego adresu URL dołączonego do atrybutu CLICK_URL
.
Makro | Opis |
---|---|
ADVERTISING_IDENTIFIER |
Umożliwia kupującym otrzymywanie identyfikatora IDFA na iOS lub identyfikatora wyświetlania reklam na Androida podczas renderowania wyświetleń. Więcej informacji znajdziesz w artykule Odszyfrowywanie identyfikatorów reklamodawcy. |
CACHEBUSTER |
Ciąg znaków reprezentujący losową, nieoznaczoną, 4-bajtową liczbę całkowitą. |
CLICK_URL_UNESC |
Klikany adres URL reklamy bez zmiany znaczenia. We fragmencie kodu po makrze powinna znajdować się wersja docelowego adresu URL firmy zewnętrznej ze zmianą znaczenia. Jeśli na przykład klikany URL firmy zewnętrznej to <a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> W momencie wyświetlania reklam ta wartość jest rozwijana 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 następnie przekierowuje do klikanego adresu URL firmy zewnętrznej. |
CLICK_URL_ESC |
Klikany adres URL reklamy ze zmianą znaczenia. Użyj jej zamiast Na przykład we fragmencie kodu HTML można użyć tego kodu: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a> W momencie wyświetlania reklam ta wartość jest rozwijana 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 za pomocą metody Po |
CLICK_URL_ESC_ESC |
Adres URL reklamy z podwójną zmianą znaczenia. Użyj jej zamiast Na przykład we fragmencie kodu HTML można użyć tego kodu: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a> W momencie wyświetlania reklam ta wartość jest rozwijana do: <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ęto do wartości http: , jeśli pytanie o stawkę nie wymaga SSL, lub do https: , jeśli pytanie o stawkę wymaga SSL. |
SITE |
Domena adresu URL treści ze zmianą znaczenia lub identyfikator anonimowy w przypadku anonimowych zasobów reklamowych. |
SITE_URL |
Rola wycofana. Zastąpione przez makro SITE, które zapewnia identyczną funkcjonalność. |
TZ_OFFSET |
Przesunięcie strefy czasowej. |
VERIFICATION |
Różne wartości dla produkcji i czasu skanowania kreacji w procesie weryfikacji. Format: %%?VERIFICATION:true-val:false-val%% , gdzie przy true-val i false-val można używać dowolnych wartości oprócz makr, także pustych ciągów. W przypadku Otwartego ustalania stawek zalecamy korzystanie z tego makra przez giełdy. Gdy to zrobi, platformy DSP nie będą musiały wprowadzać zmian.Jeśli na przykład kreacja zawiera ciąg %%?VERIFICATION:-1:5000%% , tekst zastępczy będzie miał postać 5000 przy wyświetlaniu i -1 w procesie weryfikacji. Pomoże Ci to odróżnić te 2 zestawy pingów. |
WINNING_PRICE |
Zakodowany koszt wyświetlenia (czyli CPI, a nie CPM) w niewielkich częściach waluty konta. Na przykład zwycięski CPM w wysokości 5 USD odpowiada CPM 5 000 000 mikros, czyli 5000 mikro. Zdekodowana wartość WINNING_PRICE w tym przypadku wyniesie 5000.
Zwycięska cena jest określona w CPI.
|
WINNING_PRICE_ESC |
Ciąg znaków WINNING_PRICE ze zmianą znaczenia w adresie URL. |
Zmiana znaczenia adresu URL w makrach ma następujący schemat:
- Znak spacji jest zastępowany znakiem plusa (
+
). - Znaki alfanumeryczne (0–9, a–z, A–Z) i znaki z zestawu !()*,-./:_~ pozostają bez zmian.
- Pozostałe znaki są zastępowane wartością
%XX
, gdzieXX
to liczba szesnastkowa reprezentująca znak.
Ograniczenia wprowadzone przez wydawcę
Wydawcy korzystają z BidRequest
, aby ignorować ograniczenia dotyczące zezwalania na wyświetlanie reklam. Musisz egzekwować ograniczenia w tych polach:
allowed_vendor_type
excluded_attribute
excluded_sensitive_category
Jedno pole określa dozwolone cechy reklamy, a drugie niedozwolone. Nigdy nie zwracaj reklam z niedozwoloną funkcją. W przypadku dozwolonych funkcji, takich jak typ dostawcy, zwracaj reklamę tylko wtedy, gdy typ dostawcy jest na liście allowed_vendor_type
w elemencie BidRequest
. Więcej informacji znajdziesz w komentarzach do tych pól w definicji bufora protokołu BidRequest
.
Jeśli fragment kodu HTML jest zwrócony w metodzie BidResponse
, musisz prawidłowo skonfigurować pola attribute
, category
i click_through_url
w polu BidResponse
.
Jeśli reklama ma wiele 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, dla których te pola nie są ustawione, są odrzucane.
Możliwe wartości atrybutu BidRequest.excluded_attribute
to (patrz plik publisher-excludable-creative-attributes.txt):
7 Tagging: IsTagged
Reklamy są zabronione, jeśli zawierają piksel lub obraz jednopikselowy (beacon), którego celem jest generowanie listy identyfikatorów plików cookie przeznaczonych do remarketingu.8 CookieTargeting: IsCookieTargeted
Reklamy są niedozwolone, jeśli są kierowane na klientów na podstawie identyfikatora pliku cookie, gdzie lista identyfikatorów plików cookie reprezentuje zbiór konsumentów, którzy wcześniej weszli w interakcję z witryną należącą do kupującego lub przez niego reprezentowaną.9 UserInterestTargeting: IsUserInterestTargeted
Reklamy są niedozwolone, jeśli są kierowane na klientów na podstawie identyfikatora pliku cookie, gdzie lista identyfikatorów plików cookie reprezentuje zbiór konsumentów zdefiniowanych jako grupa o wspólnych zainteresowaniach.21 CreativeType: Html
Reklamy nie mogą używać polahtml_snippet
anisnippet_template
wBidResponse.Ad
.22 CreativeType: VastVideo
Reklamy nie mogą używać polavideo_url
wBidResponse.Ad
.30 InstreamVastVideoType: Vpaid
Reklamy nie mogą wymagać obsługi VPAID do renderowania.32 MraidType: MRAID
Reklamy nie mogą wymagać do renderowania interfejsu MRAID API.34 RichMediaCapabilityType: RichMediaCapabilityFlash
Reklamy nie mogą wymagać obsługi Flasha.39 RichMediaCapabilityType: RichMediaCapabilityHTML5
Reklamy nie mogą wymagać do renderowania funkcji HTML5.48 RichMediaCapabilityType: RichMediaCapabilityNonSSL
Reklamy nie mogą wysyłać żądań bez SSL.
Dlatego jeśli pole excluded_attribute
zawiera wartość 7, nie należy zwracać reklam, które do tworzenia list używają piksela lub obrazu typu web-beacon. Pamiętaj, że jeśli tak jest w przypadku reklamy, musi ona ustawić wartość 7 w polu atrybutu BidResponse
.
Podobnie, jeśli pole excluded_attribute
zawiera wartość 48, należy zwracać tylko te reklamy, które mogą być renderowane na stronie SSL (i odpowiednio zadeklaruj atrybut 47 RichMediaCapabilityType: RichMediaCapabilitySSL).
Również pole excluded_sensitive_category
w BidRequest
wykorzystuje kody z pliku ad-sensitive-categories.txt
dostępnego na stronie danych referencyjnych. Poniżej znajdziesz ich rozszerzone opisy:
3 Politics
Obejmuje politykę lub kontrowersyjne tematy społeczne, nie obejmuje reklam agencji informacyjnych, które nie prezentują stronniczych poglądów.4 Dating
Zakaz ten obejmuje usługi i serwisy randkowe.5 Religion
Obejmuje reklamy religijne propagujące określone poglądy religijne lub nawołujące przeciw nim; nie obejmuje astrologii i duchowości niewyznaniowej.7 Video Games (Casual & Online)
Obejmuje gry wideo, gry online i gry do pobrania; nie obejmuje konsol do gier wideo.8 Ringtones & Downloadables
dodatki na telefony komórkowe, w tym dzwonki i inne gadżety do pobrania, takie jak wygaszacze ekranu i tapety na komputery stacjonarne oraz układy profilu i grafiki do sieci społecznościowych;10 Get Rich Quick
Plany obiecujące szybkie zarobki.18 Weight Loss
Obejmuje odchudzanie, diety oraz związane z nimi produkty i programy; nie obejmuje zdrowego żywienia ani ogólnych reklam dotyczących kondycji fizycznej.19 Cosmetic Procedures & Body Modification
Obejmuje zabiegi liftingu, sukcji, laserowe, usuwanie i przywracanie włosów, tatuaże i modyfikacje ciała.23 Drugs & Supplements:
Obejmuje leki, witaminy, suplementy oraz sprzedawców oferujących te produkty; nie obejmuje źródeł informacji o lekach.24 Sexual & Reproductive Health
Obejmuje reklamy produktów i usług związanych z funkcjami seksualnymi i płodnością; nie obejmuje reklam produktów i usług związanych z ciążą.35 Social Casino Games
Obejmuje symulowane gry hazardowe (w tym pokera, automaty do gry, bingo, loterie, zakłady sportowe, obstawianie gonitw, a także inne gry karciane i kasyna), w których nie można wygrać niczego wartościowego (np. pieniędzy ani nagród).36 Significant Skin Exposure
Obrazy w reklamach pokazujące ciało ludzkie, które od wysokości mostka do połowy uda nie jest niczym okryte lub widać na nich bieliznę, kostium kąpielowy, bieliznę lub inne przezroczyste ubrania albo elementy niebędące ubraniem, takie jak ręcznik lub prześcieradło.37 Sensationalism
Reklamy, które zachęcają użytkowników do kliknięcia, odwołując się do ich ciekawości. Często wykorzystują prowokacyjny przekaz wyrażony w przesadnym języku lub z przesadną grafiką. Obejmuje reklamy skupiające się na sensacyjnej tematyce (takiej jak aresztowania, śmierć czy rozwody celebrytów) lub ich treści szokujące.
Open Measurement
Open Measurement pozwala określić dostawców zewnętrznych, którzy świadczą niezależne usługi pomiaru i weryfikacji w przypadku reklam wyświetlanych w środowiskach aplikacji mobilnych.Obsługiwane obecnie formaty reklam to m.in. reklamy wideo, banery i reklamy pełnoekranowe. Więcej informacji o używaniu Open Measurement w odpowiedzi na stawkę zawierającą te formaty znajdziesz w artykule w Centrum pomocy pakietu Open Measurement SDK.
Przykładowe odpowiedzi na stawkę
W sekcjach poniżej znajdziesz przykładowe odpowiedzi na stawki w przypadku różnych typów reklam.