Tek satıcıyla tarayıcı tabanlı açık artırma yapma

Bu belgede, Protected Audience API'nin mevcut yinelemesinde kullanılan tek bir satıcı için Protected Audience verileriyle açık artırma çalıştırmaya yönelik üst düzey bir genel bakış bulacaksınız. Tek satıcılı bir açık artırma, birden fazla satıcının yer aldığı daha karmaşık bir açık artırmanın parçası olarak yürütülebilir. 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, birden fazla satıcının katıldığı "üst seviye açık artırmasına" reklam adayları sağlayabilir.

Protected Audience API'nin tam 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 yürüttüğü hakkında ayrıntılı bilgi edinmek için Protected Audience API açıklayıcı belgesine bakın.

Protected Audience API reklam açık artırmasının altı aşaması

1. Bir kullanıcı, reklam gösteren bir siteyi ziyaret eder.
2. Satıcının kodu navigator.runAdAuction() yürütülür. Bu, hangi reklam alanının satışa sunulduğunu ve kimlerin teklif verebileceğini belirtir. Satıcılar, her teklife puan veren bir komut dosyası da eklemelidir. scoreAd().
3. Teklif oluşturmak, alakalı bir reklam öğesi için URL ve diğer veriler oluşturmak üzere davet edilen alıcının kodu yürütülür. Teklif verme komut dosyası, alıcının anahtar/değer hizmetinden kalan reklam kampanyası bütçesi gibi gerçek zamanlı veriler için sorgu oluşturabilir.
4. Satıcının kodu her teklife puan verir ve kazananı seçer. Bu mantık, teklifin istenebilirliğini döndürmek için teklif değerini ve diğer verileri kullanır. Bağlamsal kazananı geçemeyen reklamlar reddedilir. Satıcı, gerçek zamanlı veriler için kendi anahtar/değer hizmetini kullanabilir.
5. Kazanan reklam, sınırlı çerçevede görüntülenen opak bir değer olarak döndürülür. Hem satıcı hem de yayıncı bu değeri görüntüleyemez.
6. Açık artırma, satıcıya ve kazanan alıcılara bildirilir.

Kullanıcı, reklam gösteren bir sayfaya gittiğinde açık artırma gerçekleşebilir. Reklam öğesi, reklam alanı görünür hale geldiğinde hazır olması için açık artırmalar ö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 bildirmekle sorumludur. Satıcılar, scoreAd() işlevini kullanarak yayıncı kurallarını uygulayabilir ve reklam kalitesine göre filtreleme de yapabilir.

Satıcı şu anlamlara gelebilir:

• Web sitesinde reklam içeriği barındırmak için kendi adına hareket eden içerik yayıncıları
• Reklam yayıncısıyla çalışan ve başka hizmetler sağlayan arz tarafı platformları (STP'ler)
• Reklam açık artırmalarına katılımı sağlamak için yayıncılar adına hareket eden üçüncü taraf komut dosyaları.

Açık artırma düzenlemenin ön koşulları

Bir satıcının açık artırma yayınlamak için iki JavaScript işlevi tanımlaması gerekir:

• scoreAd(), reklam adayına puan verir
• reportResult(), açık artırmanın sonucunu satıcıya bildirmekle ilgilenir.

Bu komut dosyalarının, satıcının sahip olduğu tek bir uç noktadan sunulması gerekir.

scoreAd()

Satıcının, kendisine ait bir uç noktadan sunulan bir scoreAd() işlevi tanımlaması gerekir. Uç nokta, açık artırma yapılandırmasında decisionLogicUrl olarak belirtilir. scoreAd() işlevinin imzası şöyledir:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

scoreAd() parametreleri şunlardır:

• adMetaData, reklam öğesiyle ilgili, alıcı tarafından sağlanan rastgele meta verilerdir. Bu, satıcıların ve alıcıların yapısını tanımlaması ve üzerinde anlaşması gereken, JSON'a dönüştürülebilir bir nesnedir.
• Teklifi temsil eden sayısal bir değer olan bid.
• auctionConfig, açık artırmayı yürütmek için kullanılan açık artırma yapılandırmasıdır.
• trustedScoringSignals, satıcının anahtar/değer sunucusundan açık artırma sırasında okunan sinyallerdir. Platform, bu arama için anahtar olarak aday reklamın renderUrl değerini kullanır.
• browserSignals, tarayıcının oluşturduğu bir nesnedir. Tarayıcının bildiği ve satıcının açık artırma komut dosyasının doğrulamak isteyebileceği bilgileri içerir.
• directFromSellerSignals, aşağıdaki alanları içerebilen bir nesnedir: ** sellerSignals: auctionConfig.sellerSignals gibi ancak directFromSellerSignals mekanizması kullanılarak iletilir. ** auctionSignals: auctionConfig.auctionSignals gibi, ancak directFromSellerSignals mekanizması kullanılarak aktarılır.

Aşağıda browserSignals örneği verilmiştir. Aday reklamın renderUrl özelliğinin aşağıdaki 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()

Satıcının, kendisine ait 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şlevinin imzası aşağıdaki gibidir:

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

reportResult() parametreleri şunlardır:

• auctionConfig, açık artırmayı yürütmek için kullanılan açık artırma yapılandırmasıdır.
• browserSignals, tarayıcının oluşturduğu bir nesnedir. Tarayıcının bildiği ve satıcının açık artırma komut dosyasının doğrulamak isteyebileceği bilgileri içerir. Bu, scoreAds() işlevine iletilen nesneyle aynıdır.

reportResult(), kazanan alıcının raporlama işlevine iletilen rastgele bir JSON nesnesi olan signalsForWinner değerini döndürür. Bu, satıcının alıcının raporlaması için açık artırma hakkında sağlayabileceği tüm ilgili bilgileri içermelidir.

Protected Audience API açık artırması çalıştırma

Bir satıcının açık artırma düzenlemek için atması gereken dört temel adım vardır. Bu adımlarda, satıcının bu kılavuzda daha önce bahsedilen gerekli JavaScript'i döndürmek için bir uç nokta ayarladığı varsayılır.

1. Açık artırmayı yapılandırın. Bu adımda bir auctionConfig nesnesi oluşturulur. Bu, satıcının açık artırmaya hangi alıcıların katılacağını belirtmesine ve teklif oluşturma veya reklam puanlama sırasında alakalı olabilecek sinyalleri sağlamasına olanak tanır.
2. Önceki adımda oluşturulan yapılandırmayı ileterek navigator.runAdAuction() işlevini çağırarak açık artırmayı yürütün. Bu işlem, teklif oluşturup puan veren alıcılar zincirini başlatır. Bu adımın sonucunda, reklam göstermek için oluşturulabilecek bir reklam adayı elde edilir.
3. Kazanan reklamı, sınırlı çerçeve veya iFrame'de oluşturun.
4. Açık artırmanın sonucunu bildirin. Raporlamayı başlatacak bir işlev ( navigator.sendReportTo()) vardır. Satıcı her zaman açık artırma sonuçlarının raporunu alır. Yalnızca açık artırmayı kazanan alıcı rapor alır. Bu işlemde, satıcının sunucusuna rapor göndermek için bu kılavuzun önceki bölümlerinde açıklanan reportResult() kullanılır.