Protected Audience API açık artırmasını nasıl yapılandıracağınızı öğrenin.
Satıcılar tarafından cihaz üzerinde gerçekleştirilen açık artırmalar
Cihaz üzerinde Protected Audience açık artırması, reklam alanı satan bir sitede yapılır ve açık artırmayı yapan taraf satıcı olarak kastedilir. Birçok taraf satıcı olarak hareket edebilir: Bir site kendi reklam açık artırmasını gerçekleştirebilir, site için açık artırma yürütmek üzere üçüncü taraf bir komut dosyası içerebilir veya cihaz üzerinde açık artırma yürütmeyi diğer sunucu tarafı reklam açık artırma etkinlikleriyle birleştiren bir STP kullanabilir. Satıcıların cihaz üzerinde reklam açık artırmasında üç temel işi vardır:
- Satıcılar (a) hangi alıcıların katılabileceğine ve (b) bu alıcıların ilgi alanı gruplarındaki tekliflerden hangilerinin açık artırmaya girmeye uygun olduğuna karar verir. Bu şekilde satıcı, sayfada hangi reklamların gösterilmesine izin verileceğine dair site kurallarını uygulayabilir.
- Açık artırmanın iş mantığından satıcılar sorumludur: Her teklifin fiyatını ve meta verilerini dikkate alan ve "istenebilirlik" puanını hesaplayan JavaScript kodu. En yüksek istenen puana sahip teklif açık artırmayı kazanır.
- Satıcılar, açık artırma sonucuyla ilgili raporlar (ör. fiyatın takas edilmesi ve diğer ödemeler) ile ilgili raporlar yapar. Kazanan ve kaybeden alıcılar da kendi raporlarını yapar.
Bu dokümanda, cihaz üzerinde açık artırmanın nasıl yapılandırılacağı ve başlatılacağı açıklanmaktadır.
Protected Audience API reklam açık artırması yapılandırma
Protected Audience API reklam açık artırması yürütmek için ilk adım açık artırmayı yapılandırmaktır. Bu işlem, auctionConfig nesnesi oluşturarak yapılır.
Aşağıda, bu tür bir yapılandırmanın bir örneğini görebilirsiniz:
const auctionConfig = {
seller: 'https://seller.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://buyer-1.example': {...},
'https://buyer-2.example': {...},
...
},
perBuyerTimeouts: {
'https://buyer-1.example': 50,
'https://buyer-2.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://component-seller.example',
'decisionLogicUrl': ...,
...
},
...
],
resolveToConfig: [true|false],
};
AuctionConfig tesis
Zorunlu özellikler
auctionConfigs için yalnızca seller, decisionLogicUrl ve interestGroupBuyers özellikleri zorunludur.
| Özellik | Örnek | Rol |
|---|---|---|
| satıcı | https://seller.example | Satıcının kaynağı. |
| decisionLogicUrl | https://seller.example/decision-logic.js | Açık artırma JavaScript karar mantığı iş akışının URL'si. Bu alanın, satıcı alanıyla aynı kaynağa sahip olması gerekir. |
| interestGroupBuyers | [https://buyer-1.example, https://buyer-2.example, ...] |
Açık artırmada teklif vermek isteyen tüm ilgi alanı grubu sahiplerinin kaynakları |
İsteğe bağlı özellikler
auctionConfigs için kalan özellikler isteğe bağlıdır.
| Özellik | Örnek | Rol |
|---|---|---|
| trustedScoringSignalsUrl | https://seller.example/scoring-signals | Satıcının Anahtar/Değer sunucusunun URL'si. Bu değer, reklam puanlama sürecinde anahtar olarak reklam öğesinin oluşturma URL'si kullanılarak sorgulanır. Bu alanın, satıcı alanıyla aynı kaynağa sahip olması gerekir. |
| auctionSignals | {"category":"haber"} | Açık artırmaya katılan tüm alıcı ve satıcıların kullanabileceği sinyalleri temsil eden JSON seri hale getirilebilir nesne. |
| sellerSignals | {...} | Yalnızca satıcılar tarafından kullanılabilen sinyalleri temsil eden JSON seri hale getirilebilir nesne. |
| perBuyerSignals | {https://dsp.example: {...}, https://another-buyer.example: {...}, ... } |
Belirli bir alıcıya sunulan sinyaller. Sinyaller satıcılardan veya alıcılardan gelebilir. |
| perBuyerTimeouts | {https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...}, |
Belirli bir alıcının generateBid() komut dosyasının milisaniye cinsinden maksimum çalışma zamanı. Tanımlanmış belirli bir zaman aşımı olmayan her alıcıya joker karakter simgesi uygulanır. |
| sellerTimeout | 100 | Bir satıcının scoreAd() komut dosyasının milisaniye cinsinden maksimum çalışma zamanı. |
| componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | Bileşen açık artırmaları için ek yapılandırmalar. |
| resolveToConfig | doğru|yanlış | True ise FencedFrameConfig'e çözümlenmesi (<fencedframe> içinde kullanım için) veya false ise opak bir urn:uuid URL'sine (<iframe>'de kullanım için) (<iframe>'de kullanım için) için runAdAuction() işlevinden döndürülen sözü yönlendiren boole değeridir. |
Sinyalleri eşzamansız olarak sağlayın
Bazı sinyallerin değerleri (auctionSignals, sellerSignals, perBuyerSignals ve perBuyerTimeouts alanları tarafından yapılandırılanlar) isteğe bağlı olarak somut değerler olarak değil, Promise olarak sağlanabilir. Bu, açık artırmanın bazı bölümlerinin (komut dosyalarının ve güvenilir sinyallerin yüklenmesi ve izole iş akışı işlemlerinin başlatılması gibi) bu değerlerin hesaplamasını (veya ağ alımını) örtüşmesine izin verir. İş uygulaması komut dosyaları yalnızca çözümlenen değerleri görür. Bu tür bir Promise reddedilirse veya önceden başarısız olmadıkça veya başka yollarla iptal edilene kadar açık artırma iptal edilir.
Birden fazla satıcıyla açık artırma yapılandırma
Bazı durumlarda, birden fazla satıcı bir açık artırmaya katılmak isteyebilir. Bu açık artırmaların kazananları, başka bir satıcı tarafından yürütülen başka bir açık artırmaya geçirilir. Dışa aktarılan bu ayrı açık artırmalar, bileşen açık artırmaları olarak adlandırılır.
Bu bileşen açık artırmalarını kolaylaştırmak amacıyla componentAuctions nesnesi, her bir satıcının bileşen açık artırması için ek açık artırma yapılandırmaları içerebilir. Bu bileşen açık artırmalarının her birinin kazanan teklifi, açık artırmanın nihai kararını veren "üst düzey" açık artırmaya geçirilir. Bileşen açık artırmalarının auctionConfig değeri kendi componentAuctions değerine sahip olmayabilir. componentAuctions boş olmadığında interestGroupBuyers boş bırakılmalıdır. Yani, belirli bir Korunan Kitle açık artırması için tek bir satıcı ve bileşen açık artırması yoktur ya da tüm teklifler bileşen açık artırmalarından gelir ve üst düzey açık artırma yalnızca bileşen açık artırmalarının kazananları arasından seçim yapabilir.
Açık artırma
Satıcı, navigator.runAdAuction() çağrısı yaparak kullanıcının tarayıcısına bir reklam açık artırması başlatma isteğinde bulunur.
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction() çağrısı, reklama çözümlenen bir Promise döndürür. Yayıncı sayfasındaki hiçbir kodun kazanan reklamı incelemesi veya başka bir şekilde, runAdAuction() sonucundan içeriğin içeriği hakkında bilgi edinmesi mümkün değildir. resolveToConfig işareti AuctionConfig için doğru değerine ayarlanırsa yalnızca sınırlı bir çerçevede oluşturulabilecek bir FencedFrameConfig nesnesi döndürülür. İşaret false (yanlış) değerine ayarlanırsa iframe içinde oluşturulabilecek opak bir URN döndürülür. runAdAuction, hiçbir reklamın seçili olmadığını belirten boş bir değer döndürebilir. Bu durumda, satıcı içeriğe dayalı hedeflenmiş
bir reklam oluşturmayı seçebilir.