Bu belgede, Protected Audience API'nin mevcut yinelemesinde kullanılan şekilde tek bir satıcı için Protected Audience verileri içeren bir açık artırma yürütmeyle ilgili üst düzey bir genel bakış bulabilirsiniz. Tek bir satıcının bulunduğu açık artırmalar, birden çok satıcıyı kapsayan daha karmaşık bir açık artırmanın parçası olarak yapılabilir. Bu durumda, tek satıcılı açık artırma "bileşen açık artırması" olarak adlandırılır. Bu açık artırma, reklam adaylarını birden fazla satıcının katıldığı "üst düzey açık artırmaya" sunabilir.
Protected Audience API'nin tüm yaşam döngüsü için geliştirici kılavuzunu okuyun ve satıcıların cihaz üzerinde açık artırmaları nasıl düzenlediği hakkında ayrıntılı bilgi için Protected Audience API açıklayıcıyı inceleyin.
Protected Audience API reklam açık artırmasının altı aşaması
![Protected Audience API reklam açık artırmasında altı aşama](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/six-stages-a-protected-a-3e1dd6fdeddbe.png?authuser=7&hl=tr)
- Bir kullanıcı reklam gösteren bir siteyi ziyaret eder.
- Satıcının kodu
navigator.runAdAuction()
işlemini yürütür. Bu, hangi reklam alanının satılık olduğunu ve kimlerin teklif verebileceğini belirtir. Satıcılar, her bir teklifi puanlayan bir komut dosyası da (scoreAd()
) eklemelidir. - Davet edilen alıcının kodu; teklif, alakalı bir reklam öğesinin URL'si ve diğer verileri oluşturmak için yürütülür. Teklif komut dosyası, alıcının Anahtar/Değer hizmetinden kalan reklam kampanyası bütçesi gibi gerçek zamanlı verileri sorgulayabilir.
- Satıcının kodu her bir teklifi puanlar ve bir kazanan seçer. Bu mantık, teklif değerini kullanır ve diğer veriler bir teklifin ne kadar istekli olduğunu döndürür. İçeriğe dayalı kazananı geçemeyen reklamlar reddedilir. Satıcı, gerçek zamanlı veriler için kendi Anahtar/Değer hizmetini kullanabilir.
- Kazanan reklam, çitle çevrili çerçeve içinde gösterilen opak bir değer olarak döndürülür. Hem satıcı hem de yayıncı bu değeri görüntüleyemez.
- Açık artırma, satıcıya ve kazanan alıcılara bildirilir.
Kullanıcılar reklam gösteren bir sayfaya gittiğinde açık artırma gerçekleşebilir. Açık artırmalar, reklam alanı görüntülendiğinde reklam öğesinin hazır olması için önceden yapılabilir.
Satıcılar reklam açık artırmasını başlatır, scoreAd()
işlevi olarak sağlanan özel mantığı kullanarak aday reklamları puanlandırır ve açık artırmanın sonuçlarını hem kendilerine hem de kazanan alıcıya raporlamaktan sorumludur. Satıcılar ayrıca scoreAd()
işlevlerini kullanarak yayıncı kurallarını uygulayabilir ve reklam kalitesi için filtre uygulayabilir.
Satıcılar şu noktalara dikkat edebilir:
- Web sitelerinde reklam içeriği barındırmak için kendi başına hareket eden içerik yayıncıları
- Arz tarafı platformları (STP'ler), reklam yayıncısıyla çalışma ve diğer hizmetleri sağlama
- Yayıncıların reklam açık artırmalarına katılımlarını sağlamak amacıyla hareket eden üçüncü taraf komut dosyaları.
Açık artırma yürütmenin ön koşulları
Bir satıcının açık artırma yapmak için iki JavaScript işlevinin tanımlanmasını gerekir:
scoreAd()
(bir reklam adayını puanlandırır)- Açık artırma sonucunu satıcıya raporlamayı gerçekleştiren
reportResult()
Bu komut dosyalarının satıcının sahip olduğu tek bir uç noktadan yayınlanması gerekir.
scoreAd()
Bir satıcının, sahibi olduğu bir uç noktadan sunulan scoreAd()
işlevi tanımlaması gerekir. Uç nokta, açık artırma yapılandırmasında decisionLogicUrl
olarak belirtilir. scoreAd()
işlevi aşağıdaki imzaya sahiptir:
scoreAd(
adMetadata,
bid,
auctionConfig,
trustedScoringSignals,
browserSignals,
directFromSellerSignals)
scoreAd()
parametreleri şunlardır:
- Alıcı tarafından sağlanan reklam öğesiyle ilgili rastgele meta veriler olan
adMetaData
. Bu, satıcıların ve alıcıların yapıyı tanımlaması ve kabul etmesi gereken, seri hale getirilebilen bir JSON nesnesidir. bid
: Teklifi temsil eden sayısal bir değerdir.auctionConfig
, açık artırma işlemini yürütmek için kullanılan açık artırma yapılandırmasıdır.trustedScoringSignals
. Bunlar, açık artırma sırasında satıcının Anahtar/Değer sunucusundan okunan sinyallerdir. Platform, bu arama için anahtar olarak aday reklamınrenderUrl
değerini kullanır.browserSignals
. Bu nesne, tarayıcının bildiği ve satıcının açık artırma komut dosyasının doğrulamak isteyebileceği bilgiler de dahil olmak üzere tarayıcı tarafından oluşturulan bir nesnedir.directFromSellerSignals
, şu alanları içerebilecek bir nesnedir: **sellerSignals
:auctionConfig.sellerSignals
gibidir, ancakdirectFromSellerSignals
mekanizması kullanılarak geçirilmiştir. **auctionSignals
:auctionConfig.auctionSignals
ile benzer ancakdirectFromSellerSignals
mekanizması kullanılarak geçti.
Aşağıda browserSignals
örneği verilmiştir. Aday reklamın renderUrl
şu sinyaller aracılığıyla kullanılabildiğini unutmayın:
{ 'topWindowHostname': 'www.example-publisher.com',
'interestGroupOwner': 'https://www.example-buyer.com',
'renderURL': 'https://cdn.com/render_url_of_bid',
'renderSize': {width: 100, height: 200}, /* if specified in the bid */
'adComponents': ['https://cdn.com/ad_component_of_bid',
'https://cdn.com/next_ad_component_of_bid',
...],
'biddingDurationMsec': 12,
'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}
reportResult()
Bir satıcının, sahip olduğu bir uç noktadan sunulan bir reportResult()
işlevi tanımlaması gerekir. Uç nokta, açık artırma yapılandırmasında decisionLogicUrl
olarak belirtilir. reportResult()
işlevi aşağıdaki imzaya sahiptir:
reportResult(auctionConfig, browserSignals) {
...
return signalsForWinner;
}
reportResult()
parametreleri şunlardır:
auctionConfig
, açık artırma işlemini yürütmek için kullanılan açık artırma yapılandırmasıdır.browserSignals
. Bu nesne, tarayıcının bildiği ve satıcının açık artırma komut dosyasının doğrulamak isteyebileceği bilgiler de dahil olmak üzere tarayıcı tarafından oluşturulan bir nesnedir. Bu,scoreAds()
işlevine iletilen nesnedir.
reportResult()
, signalsForWinner
değerini döndürür. Bu, kazanan alıcının raporlama işlevine aktarılan rastgele bir JSON nesnesidir. Bu, satıcının açık artırmayla ilgili sağlayabileceği ve alıcının raporlaması için gerekli kıldığı tüm alakalı bilgileri içermelidir.
Protected Audience API açık artırması yürütme
Bir satıcının açık artırma yürütmek için atması gereken dört ana adım vardır. Bu adımlarda, satıcının bu kılavuzda daha önce bahsedilen gerekli JavaScript'i döndürecek bir uç nokta ayarlandığı varsayılır.
- Açık artırmayı yapılandırın. Bu adım bir
auctionConfig
nesnesi oluşturmayı içerir. Bu, satıcının açık artırmaya hangi alıcıların katılacağını belirtmesini ve teklif oluşturma veya reklam puanlaması sırasında alakalı olabilecek sinyalleri sağlamasına olanak tanır. navigator.runAdAuction()
yöntemini çağırarak açık artırmayı yürütün ve önceki adımda oluşturulan yapılandırmayı uygulayın. Bu işlem, teklifler oluşturup puanlamayı alan alıcı zincirini başlatır. Bu adımın nihai sonucu, reklam görüntülemek için oluşturulabilecek bir reklam adayıdır.- Kısıtlanmış bir çerçeve veya iframe içinde kazanan reklamı oluşturun.
- Açık artırmanın sonucunu raporlama. Raporlamayı başlatacak bir işlev (
navigator.sendReportTo()
) vardır. Satıcı her zaman açık artırma sonuçlarına ilişkin bir rapor alır. Yalnızca açık artırmayı kazanan alıcı bir rapor alır. Bu işlem, sunucusuna bildirmek için bu kılavuzda daha önce açıklananreportResult()
özelliğini kullanır.