Satıcı kılavuzu: reklam açık artırmaları çalıştırma

Protected Audience API reklam açık artırması için Satıcı API kılavuzu ve referanslar.

Bu makalede, deneysel Protected Audience API'nin mevcut iterasyonunda kullanılan reklam açık artırması için teknik bir referans bulabilirsiniz.

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ırma çalıştırması hakkında ayrıntılı bir tartışma için Protected Audience API açıklamalı kılavuzuna bakın.

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ı, tarayıcının reklam seçmek için 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ıdan ve alıcılardan gelen tüm reklam açık artırması kodu, dış dünyayla iletişim kuramayan izole JavaScript worklet'lerinde çalıştırılır.

Protected Audience API reklam açık artırmasının altı aşaması
Bu şemada, Protected Audience API reklam açık artırmasının her aşaması özetlenmiştir.
  1. Bir kullanıcı reklam gösteren bir siteyi ziyaret eder.
  2. Satıcının kodu navigator.runAdAuction()'ü yürütür. Bu, hangi reklam alanının satışta olduğunu ve kimlerin teklif verebileceğini belirtir. Satıcılar, her teklife puan veren bir komut dosyası (scoreAd()) da eklemelidir.
  3. Davet edilen alıcının kodu, teklif, alakalı bir reklam öğesi için URL ve diğer verileri oluşturmak üzere 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ı verileri sorgulayabilir.
  4. Satıcının kodu her teklife puan verir ve bir kazanan seçer. Bu mantık, teklif değerini ve teklifin arzu edilirliğini döndüren diğer verileri kullanır. Bağlama dayalı kazananı geçemeyen reklamlar reddedilir. Satıcı, gerçek zamanlı veriler için kendi anahtar/değer hizmetini kullanabilir.
  5. Kazanan reklam, çitli ç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.
  6. Açık artırma, satıcıya ve kazanan alıcılara bildirilir.

Açık artırma ne zaman gerçekleşir?

Protected Audience API tek başına veya programatik açık artırmalarla çalıştırılabilir. Birden çok satıcının yer aldığı programatik açık artırmada:

  1. Kullanıcı, katılımcı bir siteyi ziyaret eder.
  2. Programatik açık artırma, mevcut bir reklam alanı için içeriğe dayalı bir reklam bulmak üzere başka bir satıcı tarafından yürütülür.
  3. Protected Audience API açık artırması çalıştırılır.
  4. scoreAd(), alıcının tekliflerini ilk açık artırmanın sonuçlarıyla karşılaştırır.

Bağlamsal kazananı geçemeyen teklifler reddedilir.

Protected Audience API reklam açık artırmasını kim yönetir?

Reklam alanı satmak için açık artırma düzenleyebilecek birden fazla taraf vardır.

Örneğin:

  • İçerik yayıncısı: Web sitesinde reklam içeriği barındırmak için kendi adına hareket eden.
  • Arz tarafı platformu (STP): Yayıncıyla birlikte çalışır ve diğer hizmetleri sağlar.
  • Üçüncü taraf komut dosyası: Reklam açık artırmalarına katılımı sağlamak için yayıncı adına hareket eder.

Protected Audience API ile satıcının üç görevi vardır:

  • Yayıncı kurallarını uygulayın: Hangi alıcılar ve hangi teklifler uygundur?
  • Açık artırma mantığını çalıştırma: Her teklif için bir arzu edilirlik puanı hesaplamak üzere worklet'lerde çalıştırılan JavaScript.
  • Açık artırma sonucunu bildirin.

Bu işler, navigator.runAdAuction() JavaScript işlevini çağırarak reklam açık artırması başlattığında satıcı tarafından sağlanan kodda programatik olarak yapılır.

API işlevleri

runAdAuction()

Satıcı, navigator.runAdAuction() çağrısı yaparak kullanıcının tarayıcısından reklam açık artırması başlatmasını ister.

Ö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'ye (urn:uuid:<something>) çözüm bulan bir promise döndürür. Bu, yalnızca tarayıcı tarafından oluşturulmak üzere bir çitli çerçeveye aktarıldığında kodu çözülebilir: Yayıncı sayfası, kazanan reklamı denetleyebilir.

decisionLogicUrl komut dosyası, her bir reklamı ilişkili teklifi ve meta verileriyle birlikte tek tek inceler ve ardından reklama sayısal bir arzu puanı atar.

auctionConfig tesis

seller
Zorunlu
Örnek: 'https://ssp.example'
Rolü: Satıcının kaynağı.
decisionLogicUrl
Zorunlu
Örnek: 'https://ssp.example/auction-decision-logic.js'
Rolü: Açık artırma işleyici JavaScript'i için URL.
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', ...]
Roll: Açık artırmada teklif vermesi istenen tüm ilgi alanı grubu sahiplerinin kökenleri.
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ı, politikalarına uygunluğu onaylamak için reklam öğelerini inceleyebilir.
auctionSignals
İsteğe bağlı
Örnek: {...}
Roll: Sayfa bağlamı, açık artırma türü vb.hakkında satıcı bilgileri
sellerSignals
İsteğe bağlı
Örnek: {...}
Roll: Yayıncı ayarlarına dayalı bilgiler, bağlama dayalı reklam isteği gönderme vb.
sellerTimeout
İsteğe bağlı
Örnek: 100
Rolü: Satıcının scoreAd() komut dosyasının maksimum çalışma süresi (ms).
perBuyerSignals
İsteğe bağlı
Örnek: 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
Rolü: Belirli bir alıcıya ait sayfayla ilgili içerik sinyalleri (alıcı sunucusundan).
perBuyerTimeouts
İsteğe bağlı
Örnek: 50
Roll: Belirli bir alıcının generateBid() komut dosyalarının maksimum çalışma süresi (milisaniye).
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, açık artırma yapılandırma nesnesinin bir özelliğidir ve runAdAuction()'a iletilir. Bu URL, scoreAd() işlevi için bir komut dosyası içermelidir. Bu mantık, arzu edilirliğini belirlemek için her reklam için bir kez çalıştırılır.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

browserSignals, 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çeren, tarayıcı tarafından oluşturulan bir nesnedir:

{
  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ı, kullanılabilir reklam alanı için en iyi içeriğe dayalı reklamı bulur. scoreAd() mantığının bir kısmı, bağlamsal kazananı geçemeyen tüm reklamları reddeder.

scoreAd()

scoreAd() aşağıdaki bağımsız değişkenleri alır:

Bağımsız Değişken Rol
adMetadata Alıcı tarafından sağlanan keyfi meta veriler.
auctionConfig Açık artırma yapılandırması nesnesi navigator.runAdAuction()'e iletildi.
bid Sayısal bir teklif değeri.
trustedScoringSignals Açık artırma sırasında satıcının güvenilir sunucusundan alınan ve satıcının reklamla ilgili görüşünü temsil eden değerler.

Sık sorulan sorular

Açık artırmanın kazananı nasıl belirlenir ve kim tarafından seçilir?

Satıcı, her reklamın arzu edilirlik puanını belirlemek için puanlama mantığını sağlar ve tarayıcı, en yüksek puanı alan reklamı kazanan reklam olarak seçer.

Satıcı, scoreAd() işlevine mantık ekler ve tarayıcı, işlevi kendi dışındaki kodla sınırlı iletişime sahip bir iş parçasında yürütür. Tarayıcının kendisi reklamları puanlamaz. Puanlama mantığını yürütmekten ve en yüksek puana sahip teklifi seçmekten yalnızca tarayıcı sorumludur.

Tüm Protected Audience API referansları

API referans kılavuzları mevcuttur:

Protected Audience API açıklayıcısı da özellik desteği ve kısıtlamalar hakkında ayrıntılı bilgi sağlar.