Satıcı API kılavuzu ve Protected Audience API reklam açık artırmasıyla ilgili referanslar.
Bu makalede, reklam açık artırması için teknik referans verilmiştir. Bu teknik referans, deneme amaçlı Protected Audience API'nin geçerli yinelemesinde kullanılmıştır.
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 düzenlemesini ayrıntılı bir şekilde ele almak için Protected Audience API açıklayıcısını inceleyin.
Geliştirici değil misiniz? Protected Audience API'ye genel bakış başlıklı makaleyi inceleyin.
Protected Audience API reklam açık artırması nedir?
Protected Audience API reklam açık artırması, bir reklam seçmek üzere tarayıcının kullanıcının cihazında çalıştırdığı küçük JavaScript programlarından oluşan bir koleksiyondur. Gizliliği korumak için, satıcı ve alıcılara ait tüm reklam açık artırması kodları, dışarıyla iletişim kuramayan izole JavaScript işçilerinde çalıştırılır.
![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=5&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.
Açık artırma ne zaman yapılır?
Protected Audience API, tek başına veya programatik açık artırmalarla çalıştırılabilir. Çok satıcılı, programatik açık artırmada:
- Kullanıcı, katılımcı bir siteyi ziyaret eder.
- Başka bir satıcı, mevcut bir reklam alanı için içeriğe dayalı reklam bulmak amacıyla programatik açık artırma yapar.
- Protected Audience API açık artırması yapılır.
scoreAd()
Alıcının tekliflerini ilk açık artırmanın sonuçlarıyla karşılaştırır.
İçeriğe dayalı kazananı geçemeyen teklifler reddedilir.
Protected Audience API reklam açık artırmasını kim çalıştırır?
Reklam alanı satmak için açık artırma gerçekleştirebilecek birden fazla taraf vardır.
Örneğin:
- İçerik yayıncısı: Web sitesinde reklam içeriği barındırmak için kendisi adına hareket eder.
- Arz tarafı platformu (STP): Yayıncıyla çalışma ve diğer hizmetleri sağlama.
- Üçüncü taraf komut dosyası: Reklam açık artırmalarına katılım sağlamak amacıyla yayıncı adına hareket etme.
Protected Audience API ile satıcının üç işi vardır:
- Yayıncı kurallarını uygulama: hangi alıcılar ve hangi tekliflerin uygun olduğunu.
- Açık artırma mantığını çalıştırın: JavaScript, her teklif için bir istenenlik puanını hesaplamak üzere iş akışlarında çalışır.
- Açık artırma sonucunu bildirir.
Bu işler, navigator.runAdAuction()
JavaScript işlevini çağırarak bir reklam açık artırması başlattığında satıcı tarafından sağlanan kodla programlı bir şekilde gerçekleştirilir.
API işlevleri
runAdAuction()
Satıcı, navigator.runAdAuction()
numaralı telefonu arayarak reklam açık artırması başlatmak için kullanıcının tarayıcısına bir istek gönderir.
Örneğin:
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction()
, reklam açık artırması sonucunu temsil eden bir URN (urn:uuid:<something>
) değerine çözümlenen bir söz döndürür. Bu kod, yalnızca oluşturma için çitlenmiş bir çerçeveye iletildiğinde tarayıcı tarafından çözülebilir: Yayıncı sayfası kazanan reklamı inceleyemez.
decisionLogicUrl
komut dosyası, her bir reklamı, ilişkili teklifi ve meta verileriyle birlikte teker teker ele alır ve daha sonra sayısal bir istenenlik puanı atar.
auctionConfig
tesis
seller
- Zorunlu
- Örnek:
'https://ssp.example'
- Rol: Satıcının kaynağı.
decisionLogicUrl
- Gerekli
- Örnek:
'https://ssp.example/auction-decision-logic.js'
- Rol: Açık artırma iş akışı JavaScript'inin URL'si.
trustedScoringSignalsUrl
- İsteğe bağlı
- Örnek:
'https://ssp.example/scoring-signals'
- Rol: Satıcının güvenilir sunucusunun URL'si.
interestGroupBuyers
- Zorunlu
- Örnek:
['https://dsp.example', 'https://buyer2.example', ...]
- Rol: Açık artırmada teklif vermek isteyen tüm ilgi alanı grubu sahiplerinin kaynakları.
- Notlar: Satıcı, tüm ilgi alanı gruplarının teklif vermesine izin vermek için
interestGroupBuyers:
değerini belirtebilir. Ardından reklamlar, ilgi alanı grubu sahibinin dahil edilmesi dışındaki ölçütlere göre kabul edilir veya reddedilir. Örneğin satıcı, reklam öğelerinin politikalarına uyduğunu onaylamak için reklam öğelerini inceleyebilir. auctionSignals
- İsteğe bağlı
- Örnek:
{...}
- Rol: Sayfanın bağlamı, açık artırma türü vb.ile ilgili satıcı bilgileri
sellerSignals
- İsteğe bağlı
- Örnek:
{...}
- Rol: Yayıncı ayarlarına dayalı bilgiler, içeriğe dayalı reklam isteğinde bulunma vb.
sellerTimeout
- İsteğe bağlı
- Örnek:
100
- Rol: Satıcının
scoreAd()
komut dosyasının maksimum çalışma zamanı (ms). perBuyerSignals
- İsteğe bağlı
- Örnek:
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
- Rol: Her bir alıcı için, sunucudan alınan sayfayla ilgili içerik sinyalleri.
perBuyerTimeouts
- İsteğe bağlı
- Örnek:
50
- Rol: Belirli bir alıcının
generateBid()
komut dosyalarının maksimum çalışma zamanı (ms). componentAuctions
- İsteğe bağlı
- Örnek:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
- Rol: Bileşen açık artırmaları için ek yapılandırmalar.
decisionLogicUrl
decisionLogicUrl
, runAdAuction()
öğesine iletilen açık artırma yapılandırma nesnesinin bir özelliğidir. Bu URL, scoreAd()
işlevi için bir komut dosyası içermelidir. Bu mantık, istenip istenmediğini belirlemek amacıyla her reklam için bir kez çalıştırılır.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
browserSignals
browserSignals
, tarayıcı tarafından oluşturulan bir nesnedir. Buna, tarayıcının bildiği ve satıcının açık artırma komut dosyasının doğrulamak isteyebileceği bilgiler dahildir:
{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}
Açık artırma başlamadan önce satıcı, mevcut reklam alanı için içeriğe dayalı en iyi reklamı bulur. scoreAd()
mantığının bir parçası, içeriğe dayalı kazananı geçemeyen tüm reklamları reddeder.
scoreAd()
scoreAd()
şu bağımsız değişkenleri alır:
Argüman | Rol |
---|---|
adMetadata |
Alıcı tarafından sağlanan rastgele meta veriler. |
auctionConfig |
Açık artırma yapılandırma nesnesi navigator.runAdAuction() yöntemine iletildi. |
bid |
Sayısal bir teklif değeridir. |
trustedScoringSignals |
Açık artırma zamanında satıcının güvenilir sunucusundan alınan ve satıcının reklam hakkındaki görüşlerini temsil eden değerler. |
Sık sorulan sorular
Açık artırmanın kazananı nasıl belirlenir ve bunları kim seçiyor?
Satıcı, her bir reklamın istenenlik puanını belirlemek için puanlama mantığını sağlar ve tarayıcı en yüksek puanı kazanan reklam olarak seçer.
Satıcı, scoreAd()
işlevine mantık ekler ve tarayıcı, işlevi dışında kodla sınırlı iletişimi olan bir iş akışı içinde yürütür. Tarayıcının kendisi reklamları puanlamaz. Kayıt mantığını uygulamak ve en yüksek puana sahip teklifi seçmek tarayıcının sorumluluğundadır.
Tüm Protected Audience API referansları
API referans kılavuzları mevcuttur:
- Protected Audience API için geliştirici kılavuzu.
- Korunan Kitle ilgi alanı grupları ve teklif oluşturma ile ilgili reklam alıcı rehberi.
- Korunan Kitle reklam açık artırmaları ile ilgili reklam satıcısı kılavuzu.
- Açık artırma sonuçlarını raporlama kılavuzu
- Korunan Kitle için en iyi uygulamalar reklam açık artırması gecikmesi
- Korunan Kitle ile ilgili sorunları giderme
Protected Audience API açıklayıcısı da özellik desteği ve kısıtlamalar hakkında ayrıntılı bilgi sağlar.