Yanıtı Oluşturun

Uygulamanız, Google'dan gelen teklif isteğini işledikten sonra bir yanıt oluşturmalı ve göndermelidir. Bu kılavuzda, yanıtı oluşturmak için uygulamanızı nasıl kodlayacağınız açıklanmaktadır.

Protobuf BidResponse mesajı oluşturma

Authorized Buyers, BidRequest öğesini bir HTTP POST mesajının gövdesi olarak gönderir. Teklif uç noktanız Protobuf biçimini kullanacak şekilde yapılandırılmışsa uygulamanız, Content-Type üst bilgisi application/octet-stream olarak ayarlanmış ve serileştirilmiş bir protokol arabelleğinden oluşan bir mesaj gövdesi içeren bir yanıt göndermelidir. Protokol arabelleği, openrtb.proto'te tanımlandığı şekilde bir BidResponse mesajıdır. Uygulamanız her BidRequest için ayrıştırılabilir bir BidResponse döndürmelidir. Zaman aşımları ve ayrıştırılamayan yanıtlar hata olarak kabul edilir ve Google, hata oranları yüksek olan teklif verenleri kısıtlar.

Bir gösterim için teklif vermek istemiyorsanız boş bir HTTP 204 yanıtı döndürmeniz gerekir. openrtb.proto değerini referans verileri sayfasından edinebilirsiniz.

Reklam Öğesi Kimliği

BidResponse, BidResponse.seatbid.bid.crid alanı aracılığıyla bir reklam öğesi belirtir (64 bayt sınırı). Benzer reklam öğeleri bile boyut, beyan edilen URL, reklam öğesi özellikleri ve tedarikçi firma türleri dahil ancak bunlarla sınırlı olmamak üzere herhangi bir belirgin özellikte farklılık gösteriyorsa bu alan için benzersiz değerlere sahip olmalıdır. Başka bir deyişle, aşağıdaki özelliklere sahip iki reklama farklı reklam öğesi kimlikleri vermeniz gerekir:

  • Farklı görünmek veya farklı davranmak
  • Farklı resimler oluşturabilirsiniz.
  • Farklı yöntemlerle oluşturulur (ör. bir reklam resimden, diğeri videodan oluşur).

Uygulamanızı tasarlarken, göndermeyi planladığınız reklam öğesi türleri için anlamlı olan, sistematik bir tanımlayıcılar oluşturma yöntemine karar vermelisiniz.

Reklam özellikleri

Google, reklamınızın özelliklerini ve hedeflemesini açıklamak için BidResponse.seatbid.bid.apis ile BidResponse.seatbid.bid.attr'nin bir kombinasyonunu veya BidResponse.seatbid.bid.ext.attribute uzantısını kullanarak reklam öğesi özelliklerini belirtmenizi önerir. Aşağıda, özellikleri nasıl tanımlayabileceğiniz açıklanmaktadır:

  • VPAID
    BidResponse.seatbid.bid.apis öğesini VPAID_1 veya VPAID_2 olarak ayarlayın. JSON biçimi için bu, sırasıyla 1 veya 2 olarak ayarlanabilir.
  • MRAID
    BidResponse.seatbid.bid.apis öğesini MRAID_1 veya JSON biçimi için 3 olarak ayarlayın.
  • SIZELESS
    BidResponse.seatbid.bid.attr öğesini RESPONSIVE veya JSON biçimi için 18 olarak ayarlayın.
  • PLAYABLE
    Bu, BidResponse.seatbid.bid.attr değerinin USER_INTERACTIVE olarak ayarlanmasıyla veya JSON biçimi için 13 olarak ayarlanmasıyla belirtilir.

Reklam öğelerinizin algılanan özellikleriyle ilgili geri bildirim alma hakkında açıklama için Reklam öğeleri kaynağına bakın.

Open Bidding alanları

Open Bidding'e katılan exchange ve ağ teklif verenleri tarafından gönderilen teklif yanıtları, standart gerçek zamanlı teklif vermeye katılan Authorized Buyers'ın yanıtlarına benzer. Open Bidding müşterileri az sayıda ek alan belirtebilir ve mevcut birkaç alanın alternatif kullanımları olabilir. Bu politikalar aşağıdakileri içerir:

OpenRTB Authorized Buyers Ayrıntılar
BidResponse.imp[].pmp.deals[].id BidResponse.ad[].adslot[].exchange_deal_id

Exchange'in ad alanından, bu teklifle ilişkilendirilen ve yayıncılara bildirilen anlaşma kimliği.

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

Yayıncılara bildirilen anlaşma türü. Anlaşmanın açık artırmada nasıl ele alınacağını etkiler.

BidResponse.seatbid[].bid[].ext.third_party_buyer_token BidResponse.ad[].adslot[].third_party_buyer_token Open Bidding kullanıcısı olarak exchange bir aracıysa nihai üçüncü taraf alıcı bilgilerini tanımlamak için kullanılan jeton. Bu değer, üçüncü taraf alıcıdan alınır ve teklif yanıtında Google'a değiştirilmeden aktarılmalıdır.

Öneriler

  • Sunucularınızda kalıcı HTTPS bağlantılarını ("keep-alive" veya "bağlantı yeniden kullanımı" olarak da bilinir) etkinleştirin. Zaman aşımını en az 10 saniyeye ayarlayın. Birçok durumda daha yüksek değerler faydalıdır. Authorized Buyers yüksek hızda istek gönderdiği ve her istek için ayrı bir TCP bağlantısı oluşturmanın gecikmesi yükünü önlemesi gerektiği için Google, uygulamanızın ilk gecikme testleri sırasında bunu doğrular.
  • Teklif verenin kazandığı zaman yerine gösterimin oluşturulduğu zamanı izlemek için isteğe bağlı gösterim izleme URL'sini ekleyin. Kazanma ve oluşturma işlemleri arasındaki düşüş nedeniyle bu yöntem, daha doğru izleme istatistikleri sağlar.

  • Teklif veren kodunuzu, tekliflerinizin hatalarla başarısız olmasına neden olabilecek desteği sonlandırılmış alanlara bağımlı olmaktan uzak tutun.
  • BidResponse dosyanıza BidResponse.seatbid.bid.w ve BidResponse.seatbid.bid.h ekleyin. Birden fazla reklam boyutu içeren bir istek için BidResponse bu alanları içermelidir. Aksi takdirde açık artırmadan çıkarılır.
  • Yanıtınızın boyutunu 8 KB'nın altında tutun. Çok büyük yanıtlar ağ gecikmesini artırabilir ve zaman aşımına neden olabilir.
  • iOS envanterinde SKAdNetwork ilişkilendirmesi gerektiren tekliflerle ilgili yönergeleri uygulayın.

Örnek teklif yanıtı

Aşağıdaki örnekler, Protobuf ve JSON isteklerinin insan tarafından okunabilen örneklerini temsil etmektedir.

OpenRTB Protobuf

OpenRTB JSON

Google

Önemli: Örneklerde gösterilen Protobuf mesajları burada kullanıcı tarafından okunabilir metin olarak temsil edilmiştir. Ancak mesajlar kablo üzerinden bu şekilde gönderilmez. Google veya OpenRTB Protobuf biçimi kullanıldığında yalnızca serileştirilmiş BidResponse mesajları kabul edilir.

Aşağıdaki C++ kodunu kullanarak bir BidResponse mesajı oluşturup seri hale getirebilirsiniz:

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
}

Reklam öğesini belirtme

Teklif yanıtınız, teklifiniz kazanırsa yayınlanacak reklam öğesini belirtir. Teklifiniz, desteklenen reklam biçimlerinden (AMP, video, yerel) birini içermelidir. Bu örnekte, html_snippet alanını kullanarak reklam öğesini belirtiyoruz.

Alternatif olarak, reklam biçimine bağlı olarak aşağıdaki alanlardan birini kullanarak reklam öğenizi belirtebilirsiniz:

  • SDK tarafından oluşturulan reklam
    • BidResponse.seatbid.bid.ext.sdk_rendered_ad
  • AMP
    • BidResponse.seatbid.bid.amp_ad_url
  • Video
    • BidResponse.seatbid.bid.adm
  • Yerel
    • BidResponse.seatbid.bid.adm_native

BidResponse.seatbid.bid.adm alanında bir HTML snippet'i kullanarak kendi sunucularınızda barındırılan bir reklam belirtin. Snippet, web sayfasına eklenen bir iFrame içine yerleştirilir. Bu sayede sayfa yüklendiğinde reklam alınır ve oluşturulur. HTML snippet'ini, reklamın (banner veya geçiş reklamı) bir iFrame içinde doğru şekilde ve teklif verdiğiniz reklam alanı için uygun boyutta oluşturulacak şekilde oluşturmanız gerekir.

Ayrıca, teklif yanıtında belirtilen reklam boyutu aşağıdaki durumlarda teklif isteklerindeki boyut kombinasyonlarından biriyle tam olarak eşleşmelidir:

  • Reklam, normal bir banner'dır (video, yerel veya geçiş reklamı değildir).
  • Teklif veren, boyutu teklif yanıtında belirtmiştir. İstekte birden fazla boyut varsa boyut beyanı gereklidir.
  • Geçiş reklamları için istisna uygulanır. Geçiş reklamlarının genişliği, ekran genişliğinin en az% 50'si, yüksekliği ise ekran yüksekliğinin en az% 40'ı kadar olmalıdır.

Düzgün şekilde oluşturulan herhangi bir geçerli HTML kodunu kullanarak bir HTML snippet'i reklam öğesi olarak belirtebilirsiniz. Ancak BidResponse mesajı oluştur bölümünde crid alanını belirtmeyle ilgili kısıtlamaları göz önünde bulundurun. Bunun bir kullanım alanı, reklamın oluşturulması kapsamında sunucularınızdan alınan URL'lerin bağımsız değişkenlerine ek bilgiler eklemektir. Bu sayede, gösterimle ilgili rastgele verileri kendi sunucularınıza iletebilirsiniz.

Teklif yanıtlarında döndürülen HTML snippet'leriyle ilgili politikaların çoğu, üçüncü taraf reklamlarla aynıdır. Daha fazla bilgi için Authorized Buyers Program Yönergeleri, Üçüncü taraf reklam yayınlama koşulları ve Reklamlarda tıklama URL'lerini beyan etme başlıklı makalelere bakın.

Makroları belirtme

Makrolar, reklam sunma zamanında ilgili bir değerle değiştirilen URL'ler içeren bazı teklif yanıtı alanlarına yerleştirilmiş biçimlendirilmiş metindir. Örneğin, kazanan teklifiniz teklifinizle birlikte eklenen HTML snippet'i reklam öğesinde AUCTION_PRICE makrosunu içeriyorsa makro, açık artırmadaki gösterim için ödediğiniz tutarı belirlemek üzere şifresini çözebileceğiniz bir değerle değiştirilir.

Aşağıdaki alanlara makro ekleyebilirsiniz:

  • BidResponse.seatbid.bid.adm

    HTML snippet'i, yerel, video URL'si ve video VAST XML biçimleri için makrolar desteklenir.

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

  • BidResponse.seatbid.bid.adm_native.imptrackers

  • BidResponse.seatbid.bid.ext.amp_ad_url

    AMP reklam öğeleri için yalnızca Google'a özgü WINNING_PRICE ve WINNING_PRICE_ESC makroları desteklenir.

  • BidResponse.seatbid.bid.burl

  • BidResponse.seatbid.bid.ext.impression_tracking_url

    Birden fazla faturalandırma URL'sine ihtiyacınız varsa BidResponse.seatbid.bid.burl yerine bunu kullanın.

Örneğin, reklam öğesini almak için kullanılan URL'ye ${MACRO} öğesini yerleştirerek bir HTML snippet'i kapsamında makro ekleyebilirsiniz. Burada MACRO, OpenRTB spesifikasyonunda açıklanan desteklenen makrolardan biridir.

Google RTB makroları

Google, OpenRTB spesifikasyonunda bulunanların dışında ek makroları destekler. Bunlar farklı şekilde biçimlendirilir ve bir URL'ye yerleştirilirse %%MACRO%% olarak görünür. Aşağıdaki tabloda bu makrolar açıklanmaktadır:

Makro Açıklama
ADVERTISING_IDENTIFIER Alıcıların gösterim oluşturma sırasında iOS IDFA'sını veya Android'in reklam kimliğini almasına olanak tanır. Ayrıntılar için Reklamveren Tanımlayıcılarının Şifresini Çözme başlıklı makaleye bakın.
CACHEBUSTER Rastgele, işaretsiz, dört baytlık bir tam sayının dize temsili.
CLICK_URL_UNESC

Reklamın çıkış karaktersiz tıklama URL'si. Kırpıntıda, üçüncü taraf tıklama URL'sinin koddan kaçan bir sürümü doğrudan makroyu izlemelidir.

Örneğin, üçüncü taraf tıklama URL'si http://my.adserver.com/some/path/handleclick?click=clk ise makro çağrıldıktan sonra üçüncü taraf tıklama URL'sinin tek çıkış karakterli sürümüyle aşağıdaki kod kullanılabilir:

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

Reklam sunma zamanında bu değer şu şekilde genişletilir:

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

URL, tıklamayı önce Google'a kaydeder, ardından üçüncü taraf tıklama URL'sine yönlendirir.

CLICK_URL_ESC

Reklamın kaçan tıklama URL'si. Değeri önce başka bir sunucuya iletmeniz ve bu sunucunun da yeniden yönlendirme döndürmesi gerekiyorsa CLICK_URL_UNESC yerine bunu kullanın.

Örneğin, bir HTML snippet'inde aşağıdaki kod kullanılabilir:

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

Reklam sunma zamanında bu değer şu şekilde genişletilir:

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

Bu işlem, tıklamayı my.adserver.com ile kaydeder. my.adserver.com, daha sonra google_click_url parametresinde iletilen URL'ye yönlendirmekten sorumlu olur. Bu durumda, my.adserver.com parametresinin google_click_url parametresinden kaçışı kaldırıldığı varsayılır.

%%CLICK_URL_ESC%% ifadesinden sonra çift kaçış karakteri içeren bir URL ekleyebilirsiniz. my.adserver.com tarafından çıkış karakteri kaldırıldıktan sonra, URL'nin tek çıkış karakterli bir sürümü google_click_url'a eklenir. google_click_url getirildiğinde, bir kez daha kaçış karakteri kaldırılır ve ardından yönlendirme yapılır.

CLICK_URL_ESC_ESC

Reklamın çift kaçış karakteri eklenmiş URL'si. Değeri önce başka bir sunucuya iletmeniz ve bu sunucunun da yeniden yönlendirme döndürmesi gerekiyorsa CLICK_URL_UNESC yerine bunu kullanın.

Örneğin, aşağıdaki kod bir HTML snippet'inde kullanılabilir:

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

Reklam sunma zamanında bu değer şu şekilde genişletilir:

<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 Teklif isteği SSL gerektirmiyorsa http:, teklif isteği SSL gerektiriyorsa https: olarak genişletilir.
SITE İçerik URL'sinin URL kaçış karakteri eklenmiş alan adı veya anonim envanter için anonim kimlik.
SITE_URL Kullanımdan kaldırıldı. Aynı işlevi sağlayan SITE makrosuyla değiştirildi.
TZ_OFFSET Saat dilimi farkı.
VERIFICATION

Üretim ve reklam öğesinin doğrulama ardışık düzeninde taranması için farklı değerler. Biçim şu şekildedir: %%?VERIFICATION:true-val:false-val%%; burada makrolar hariç tüm değerler true-val ve false-val için kullanılabilir (boş dize dahil). Açık Teklif için exchange'lerin bu makroyu kullanmasını öneririz. Bu işlem yapıldıktan sonra, talep tarafı platformların değişiklik yapması gerekmez.

Örneğin, bir reklam öğesi %%?VERIFICATION:-1:5000%% içeriyorsa metin değişimi, yayın sırasında 5000, doğrulama ardışık düzeninde ise -1 olur. Bu, bu iki ping grubunu birbirinden ayırt etmenize yardımcı olur.

WINNING_PRICE

Hesap para biriminin mikrolarında kodlanmış gösterim maliyeti (yani BGBM yerine YGBM). Örneğin, 5 ABD doları olan kazanan BGBM, 5.000.000 mikro BGBM'ye veya 5.000 mikro EBM'ye karşılık gelir. Bu durumda WINNING_PRICE değerinin kod çözme işlemi uygulanmış değeri 5.000 olur. Kazanan fiyat, YPP cinsinden belirtilir.

Bu makroyu ayrıştırmak için fiyat onaylarının şifresini çözen bir uygulama uygulamanız gerekir. Daha fazla bilgi için Fiyat Onaylarının Şifresini Çözme sayfasına bakın.

WINNING_PRICE_ESC URL'den kaçan WINNING_PRICE.

Google, üçüncü taraf tarafından yayınlanan reklamın reklam öğesinde CLICK_URL_UNESC veya CLICK_URL_ESC makrosunu kullanmanızı zorunlu kılar. Google, tıklama izleme için CLICK_URL makrolarını kullanır.

Makrolarda URL kaçış karakteri olarak aşağıdaki şema kullanılır:

  • Boşluk karakteri artı işaretiyle (+) değiştirilir.
  • Alfanümerik karakterler (0-9, a-z, A-Z) ve !()*,-./:_~ kümesinden karakterler değişmeden kalır.
  • Diğer tüm karakterler %XX ile değiştirilir. Burada XX, karakteri temsil eden onaltılık sayıdır.

Yayıncı kısıtlamaları ve şartları

Teklif isteği, yayıncıların açık artırmadaki reklam öğelerine uyguladığı kısıtlama ve şart türleri hakkında bilgi içerir.

  • BidRequest.bcat
    • Bu alan tarafından belirtilen engellenen kategorileri, Gerçek Zamanlı Teklif Verme API'sinin detectedCategories alanını kullanarak gönderilen reklam öğeleriniz için algılanan kategorilerle karşılaştırabilirsiniz.
  • BidRequest.imp.ext.allowed_vendor_type
  • BidRequest.imp.secure
    • Google tüm reklam öğeleri için SSL desteği gerektirdiğinden, pratikte bu değer her zaman true olarak ayarlanır.
  • 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

Hiçbir zaman kısıtlanmış özellik içeren bir reklamla teklif vermeyin. Tedarikçi firma türü gibi izin verilen özellikler için yalnızca tedarikçi firma türü BidRequest içindeki allowed_vendor_type listesinde yer alan reklamları döndürün. Teklifinize yalnızca BidRequest.imp.banner gibi alanlar doldurularak teklif isteğinde belirtilen reklam biçimleri dahil edilmelidir. Daha fazla bilgi için BidRequest protokol arabelleği tanımında bu alanlarla ilgili yorumlara bakın.

BidResponse içinde bir reklam döndürülürse BidResponse içinde BidResponse.seatbid.bid.attr, BidResponse.seatbid.bid.cat ve BidResponse.seatbid.bid.adomain veya BidResponse.seatbid.bid.adm_native.link.url alanlarını doğru şekilde ayarlamanız gerekir. Bir reklamın bu alanlar için birden fazla geçerli değeri varsa her değeri eklemeniz gerekir. Daha fazla bilgi için BidResponse protokol arabelleği tanımında bu alanlarla ilgili yorumları inceleyin. Bu alanların ayarlanmadığı yanıtlar yok sayılır.

Open Measurement

Open Measurement, mobil uygulama ortamlarına yayınlanan reklamlar için bağımsız ölçüm ve doğrulama hizmetleri sağlayan üçüncü taraf tedarikçi firmaları belirtmenize olanak tanır.

Desteklenen reklam biçimleri arasında video, banner ve geçiş reklamları yer alır. Bu biçimleri içeren bir teklif yanıtında Open Measurement'ın nasıl kullanılacağı hakkında daha fazla bilgi için Open Measurement SDK Yardım Merkezi makalesine bakın.

Örnek teklif yanıtları

Aşağıdaki bölümlerde, farklı reklam türleri için örnek teklif yanıtları gösterilmektedir.

Uygulama banner'ı

OpenRTB Protobuf

OpenRTB JSON

Google

Uygulama Geçiş Reklamı

OpenRTB Protobuf

OpenRTB JSON

Google

Uygulama geçiş reklamı videosu

OpenRTB Protobuf

OpenRTB JSON

Google

Uygulama yerel

OpenRTB Protobuf

OpenRTB JSON

Google

Web videosu

OpenRTB Protobuf

OpenRTB JSON

Google

Exchange teklif vereni için mobil web banner'ı

OpenRTB Protobuf

OpenRTB JSON