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 yinelemesinde kullanılan reklam açık artırmasıyla ilgili teknik bir referans bulabilirsiniz.

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üğünü ayrıntılı olarak incelemek için Protected Audience API açıklayıcı belgesine 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ğin korunması için satıcı ve alıcılardan gelen tüm reklam açık artırması kodu, dış dünyayla iletişim kuramayan izole JavaScript işletim birimlerinde çalıştırılır.

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.

Açık artırma ne zaman yapılır?

Protected Audience API, tek başına veya programatik açık artırmalarla birlikte çalıştırılabilir. Çok satıcılı bir programatik açık artırmada:

1. Kullanıcı, programa katılan bir siteyi ziyaret eder.
2. Kullanılabilir bir reklam alanı için içeriğe dayalı reklam bulmak üzere başka bir satıcı tarafından programatik açık artırma 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ürütür?

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 eder.
• Arz tarafı platformu (STP): Yayıncıyla birlikte çalışır ve başka hizmetler sunar.
• Üçüncü taraf komut dosyası: Reklam açık artırmalarına katılımı sağlamak için bir yayıncı adına hareket eder.

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

• Yayıncı kurallarını zorunlu kılma: Hangi alıcıların ve hangi tekliflerin uygun olduğu.
• Açık artırma mantığını çalıştırma: Her teklif için bir uygunluk puanı hesaplamak üzere işletim birimlerinde çalıştırılan JavaScript.
• Açık artırma sonucunu bildirin.

Bu işlemler, satıcı navigator.runAdAuction() JavaScript işlevini çağırarak bir 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() işlevini çağırarak reklam açık artırması başlatmak için kullanıcının tarayıcısına 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>) ile sonuçlanan bir söz döndürür. Bu yalnızca oluşturma için sınırlı çerçeveye iletildiğinde tarayıcı tarafından kod çözülebilir: Yayıncı sayfası, kazanan reklamı inceleyemez.

decisionLogicUrl komut dosyası, her bir reklamı ilişkili teklifi ve meta verileriyle birlikte tek tek değerlendirir ve ardından her birine sayısal bir uygunluk puanı atar.

auctionConfig tesis

seller

Zorunlu

Örnek: 'https://ssp.example'

Rol: Satıcının bulunduğu ülke.

decisionLogicUrl

Zorunlu

Örnek: 'https://ssp.example/auction-decision-logic.js'

Rol: Açık artırma işleti 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', ...]

Rol: Açık artırmada teklif vermesi istenen tüm ilgi alanı grubu sahiplerinin kökenleri.

Notlar: Satıcı, tüm ilgi gruplarının teklif vermesine izin vermek için interestGroupBuyers: belirtebilir. Reklamlar daha sonra ilgi alanı grubu sahibinin dahil edilmesi dışında kalan ö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: {...}

Rol: Sayfa bağlamı, açık artırma türü vb. hakkında satıcı bilgileri.

sellerSignals

İsteğe bağlı

Örnek: {...}

Rol: Yayıncı ayarlarına, bağlamsal reklam isteğinde bulunmaya vb. dayalı bilgiler.

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: Her bir alıcı için sunucularından alınan, sayfayla ilgili bağlamsal sinyaller.

perBuyerTimeouts

İsteğe bağlı

Örnek: 50

Rol: Belirli bir alıcının generateBid() komut dosyalarının maksimum çalışma süresi (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, açık artırma yapılandırma nesnesinin bir özelliğidir ve runAdAuction()'ye iletilir. Bu URL, scoreAd() işlevi için bir komut dosyası içermelidir. Bu mantık, her reklamın ne kadar istenebilir olduğunu belirlemek 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 bilgiler de dahil olmak üzere 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ı, mevcut reklam alanı için en iyi bağlamsal reklamı bulur. scoreAd() mantığının bir parçası, bağlamsal kazananı geçemeyen tüm reklamları reddeder.

scoreAd()

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

Sık sorulan sorular

Açık artırma kazananı nasıl belirlenir ve kim seçer?

Satıcı, her reklamın istenirlik 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ışındaki kodlarla sınırlı iletişime sahip bir işlette yürütür. Reklamlara puan veren tarayıcının kendisi değildir. Puanlama mantığını yürütmek ve en yüksek puanlı teklifi seçmekten yalnızca tarayıcı sorumludur.

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.