Alıcı olarak B&A ile entegrasyon

Teklifli Sistem ve Açık Artırma (B&A) Hizmetleri, Protected Audience (PA) açık artırmasını kolaylaştırmak için güvenilir yürütme ortamında (TEE) çalışan, reklam alıcıları ve satıcıları için bir hizmet grubudur. Bu Geliştirici Kılavuzu'nda, bir alıcının Chrome için bir B&A PA açık artırmasıyla nasıl entegrasyon yapabileceği açıklanmaktadır.

Genel Bakış

B&A Hizmetleri ile bir Protected Audience açık artırmasına katılmak için alıcı, açık artırma gecikmesini iyileştirmek üzere yükü optimize etmek amacıyla ilgi alanları grubunu (IG) günceller.

Alıcı tarafından aşağıdaki yük optimizasyonu görevleri gereklidir:

• joinAdInterestGroup() görev
  • Sunucu isteği işaretlerini ayarlama
  • Reklam oluşturma kimliklerini ayarlama
  • İlgi alanı grubu önceliklerini ayarlama
  • Güvenilir teklif sinyallerini ayarlama
• generateBid() görev
  • Tarayıcı sinyallerini okuma
  • Oluşturma URL'sini döndür
  • İade raporlama kimliği

B&A için ilgi grubu

Aşağıda, yük optimizasyonunun uygulandığı bir B&A PA açık artırması için örnek bir ilgi alanı grubu yapılandırması verilmiştir:

navigator.joinAdInterestGroup({
  name: 'example-ig',
  owner: 'https://dsp.example',

  // An ID is mapped to each render URL
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max,
      buyerReportingId: 'brid123', // Optional
      buyerAndSellerReportingId: 'bsrid123', // Optional
      selectableBuyerAndSellerReportingId: ['sbsrid123', 'sbsrid456'], // Optional
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adRenderId: 'abcdefgh'
    },
  ],

  // Flags are set to omit data in the B&A auction payload
  auctionServerRequestFlags: ['omit-ads', 'omit-user-bidding-signals'],

  // Data not included in the B&A auction payload can be fetched as trusted signals
  // The following is an example of how the keys could look, but the actual
  // implementation is up to the ad tech
  trustedBiddingSignalsKeys: [
    'exampleUserBiddingSignalsKey',
    'exampleAdRenderIdKey',
    'exampleAdMetadataKey',
    'exampleAdReportingIdKey',
  ],

  // Optionally, interest groups can be prioritized
  priority: 0.0,
});

B&A ile cihaz üzerinde ilgi alanı grubu yapılandırmaları arasındaki farklar şunlardır:

• auctionServerRequestFlags alanı, tarayıcıya B&A açık artırma yükündeki bazı verileri atlamasını söyleyen işaretlerin ayarlanmasına olanak tanır.
• userBiddingSignals değeri ilgi alanları grubunda tanımlanabilir ancak omit-user-bidding-signals işareti kullanılarak bu değerlerin atlanması önerilir. Atlanan sinyaller, K/V hizmeti kullanılarak sağlanabilir.
• adRenderId alanı, ilişkili renderURL ile birlikte ayarlanır ancak yalnızca adRenderId, B&A açık artırma yükünün bir parçası olur. Açık artırma sırasında daha sonra generateBid() öğesinden döndürülen oluşturma URL'si, IG'de tanımlanan oluşturma URL'siyle eşleşmelidir.
• Raporlama kimlikleri, B&A IG'de tanımlanır ancak B&A açık artırma yüküne dahil edilmez. Açık artırma sırasında daha sonra generateBid() tarafından döndürülen raporlama kimliği, IG'de tanımlanan oluşturma URL'siyle eşleşmelidir.
• ad.metadata ve raporlama kimlikleri, B&A açık artırma yüküne dahil edilmez. Bunun yerine, bu veriler Trusted Key/Value Service kullanımıyla kullanılabilir hale gelir.

Tarayıcı, teklif verme hizmetinin generateBid() işlevinden döndürülen oluşturma URL'sinin ve raporlama kimliklerinin, ilgi alanı grubunda tanımlanan değerlerle eşleştiğini kontrol ettiğinden, renderURL ve ads içindeki raporlama kimlikleri, açık artırma isteği yüküne dahil edilmese de ilgi alanı grubu yapılandırmasında tanımlanmaya devam eder.

joinAdInterestGroup() görev

joinAdInterestGroup() görüşmesi için aşağıdaki görevlerin yapılması gerekir.

Sunucu isteği işaretlerini ayarlama

joinAdInterestGroup() yapılandırmasının auctionServerRequestFlags alanı aşağıdaki işaretleri kabul eder:

Eksik veriler, trustedBiddingSignals'da ilgili bilgileri kullanılabilir hale getirerek işlenir. İşaretler ayrı ayrı kullanılabilir ve birlikte kullanılması gerekmez.

Örnek kullanım:

navigator.joinAdInterestGroup({
  auctionServerRequestFlags: ['omit-user-bidding-signals', 'omit-ads'],
});

Reklam oluşturma kimliklerini ayarlama

B&A açık artırma yükünün boyutunu küçültmek için ilgi alanları grubunun ads ve adComponents nesneleri atlanır. Bu nedenle, bu nesneler Teklif Verme Hizmeti'nde çalışan generateBid() işlevi içinde kullanılamaz.

Alıcı, eksik reklam bilgilerini işlemek için ilgi alanı grubu yapılandırmasındaki her reklamla ilişkilendirilmiş bir tanımlayıcı (adRenderId ve adComponentRenderId) tutar. Tanımlayıcı, 12 bayt veya daha kısa bir DOMString olmalıdır. Tanımlayıcı Base64 olarak kodlanmışsa uzunluğu 12 bayt veya daha az olmalıdır.

Reklam oluşturma kimlikleri içeren bir ilgi alanı grubu örneği:

navigator.joinAdInterestGroup({
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adComponentRenderId: 'abcdefgh'
    },
  ],
});

Reklamlarla ilişkili adRenderId, generateBid()'deki prevWins.browserSignals'de kullanılabilir.

renderURL istek yüküne dahil edilmese de generateBid() tarafından döndürülen oluşturma URL'si, ilgi alanı grubu yapılandırmasında tanımlanan oluşturma URL'siyle eşleşmelidir. Reklam teknolojisi sağlayıcılar, trustedBiddingSignals içinde reklam meta verilerini ve diğer bilgileri geri gönderebilir. Böylece, generateBid() yürütme sırasında teklif için reklam oluşturma URL'si ve reklam bileşeni oluşturma URL'si oluşturulabilir.

İlgi grubu önceliklerini ayarlama

Chrome, alıcıların ilgi gruplarına öncelik vermesine olanak tanır. Satıcı tarafından belirlenen alıcı başına yük boyutu sınırına ulaşılırsa satıcı için B&A açık artırma yükü oluşturulurken tek bir alıcı için daha düşük öncelikli ilgi alanları gruplarını bırakmak üzere ilgi alanı grubu öncelik değerleri kullanılır. Farklı alıcılar arasında ilgi alanları gruplarını seçmek için tarayıcı, serileştirilmiş yükün boyutuna göre karar verir. Varsayılan olarak her alıcıya eşit bir boyut verilir. Gerçek önceliklendirmenin, istek yükü oluşturulurken değil, B&A sunucularında gerçekleştiğini unutmayın.

Öncelik, alıcının öncelik vektörleri (priorityVector) ve satıcının öncelik sinyalleri (prioritySignals) kullanılarak açık artırma sırasında hesaplanır. Alıcı, satıcının öncelik sinyallerini geçersiz kılabilir.

Açık artırma sırasında tarayıcı, öncelik için priorityVector ve prioritySignals'deki eşleşen anahtarların seyrek iç çarpımını hesaplar. Aşağıdaki şemada, öncelik (4 * 2) + (3 * -1) ile hesaplanır ve 8 + -3'ye düşürülür. Bu nedenle, bu ilgi alanları grubunun açık artırma sırasındaki önceliği 5 olur.

Markalama ve alaka düzeyinde önceliklendirme için kullanılabilecek ek sinyaller de vardır:

Daha fazla bilgi edinmek için GitHub'daki açıklama sayfasını ziyaret edin.

Güvenilir teklif sinyallerini ayarlama

Bazı veriler B&A açık artırma yükünden çıkarılacağından, çıkarılan verileri generateBid() işlevine güvenilir teklif sinyalleri olarak sağlamak için anahtar/değer hizmetini kullanabilirsiniz.

Aşağıdaki atlanan veriler K/V Hizmeti tarafından sağlanabilir:

• userBiddingSignals Alıcı tarafından kullanılıyorsa
• metadata her reklamla ilişkilendirilir.
• adRenderId her reklamla ilişkilendirilir.
• Raporlama Kimliği

Bu durumda, güvenilir teklif sinyalleri anahtarlarına benzersiz bir tanımlayıcı ekleyip ilişkili verileri sunucunuza göndererek anahtar/değer hizmetine yüklenmesini sağlayabilirsiniz. Ancak, gerçek uygulama reklam teknolojisine bağlıdır ve API zorunlu değildir.

Aşağıdaki örnekte uygulanabilecek bir yaklaşım açıklanmaktadır:

const ad1RenderURL = 'https://dsp.example/ad-1.html';
const ad2RenderURL = 'https://dsp.example/ad-2.html';
const ad1RenderId = 'render-id-1';
const ad2RenderId = 'render-id-2';
const ad1ReportingId = 'reporting-id-1';
const ad2ReportingId = 'reporting-id-2';

// Generate a unique identifier
const id = crypto.randomUUID();

// Define the keys with the unique ID
const trustedSignalsKeyForIG = `interest-group-${id}`

// Set the keys in the interest group
navigator.joinAdInterestGroup({
  // …
  ads: [
    {
      renderURL: ad1RenderURL,
      adRenderId: ad1RenderId,
      buyerReportingId: ad1ReportingId
    },
    {
      renderURL: ad2RenderURL,
      adRenderId: ad2RenderId,
      buyerReportingId: ad2ReportingId
    },
  ],
  trustedBiddingSignalsKeys: [
    trustedSignalsKeyForIG
  ]
});

// Send the associated data to your server to be loaded into the Key/Value Service
fetch('https://dsp.example/kv/load', {
  method: 'POST',
  body: JSON.stringify({
    id,
    [trustedSignalsKeyForIG]: {
      userBiddingSignals: {
        favoriteColor: 'blue'
      },
      ads: [
        {
          renderURL: ad1RenderURL,
          adRenderId: ad1RenderId,
          buyerReportingId: ad1ReportingId,
          metadata: {
            color: 'red'
          }   
        },
        {
          renderURL: ad2RenderURL,
          adRenderId: ad2RenderId,
          buyerReportingId: ad2ReportingId,
          metadata: {
            color: 'blue'
          }   
        },
      ]
    }
  })
});

Örnekte, bir IG için benzersiz tanımlayıcı tanımlanır ve güvenilir sinyaller anahtarının bir parçası olur. IG'nin anahtarı ve ilişkili değerleri, Anahtar/Değer Hizmeti'ne yüklenmek üzere sunucunuza gönderilir. Açık artırmanın ilerleyen bir aşamasında tarayıcı, güvenilir sinyalleri getirir ve bunları alıcının generateBid() işlevinde kullanılabilir hale getirir.

Gerekirse K/V'den ilgi alanı grubu güncelleme sinyalini döndürün

Güvenilir sinyaller için updateIfOlderThanMs anahtarı, ilgi alanları grubunu normal günlük aralıktan daha önce güncellemek için kullanılır. İlgi alanı grubu, updateIfOlderThanMs anahtarı için döndürülen milisaniye değerini aşan bir süre boyunca katılmamış veya güncellenmemişse ilgi alanı grubu updateURL mekanizmasıyla güncellenir. Chrome'un ilgi alanı gruplarını 10 dakikada birden daha sık güncellemeyeceğini unutmayın.

Marka ve reklamveren açık artırması, tarayıcıda depolanan ilgi alanı grubunda tanımlanan reklamlardan biriyle eşleşmeyen bir kazanan reklam döndürürse tarayıcı açık artırmayı geçemez. updateIfOlderThanMs mekanizması, tarayıcının ve B&A açık artırmasının ilgi alanı grubundaki reklamlar konusunda anlaşmasını sağlamak için yararlı olabilir.

Daha fazla bilgi edinmek için açıklayıcı yazıyı inceleyin.

generateBid() görev

generateBid() görüşmesi için aşağıdaki görevlerin yapılması gerekir.

Tarayıcı sinyallerini okuma

B&A generateBid() çağrısına iletilen browserSignals nesnesi aşağıdaki gibi görünür:

{
  topWindowHostname: 'advertiser.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://ssp-top.example',
  joinCount: 5,
  bidCount: 24,
  recency: 1684134092,

  // prevWins is [timeInSeconds, adRenderId]
  prevWins: [
    [9342, 'render-id-1'],
    [1314521, 'render-id-2']
  ],

  // Compiled WebAssembly code
  wasmHelper: WebAssembly.Module

  // Data-Version value from K/V response, if available
  dataVersion: 1,
}

Aşağıdaki değiştirilmiş veya yeni özellikler browserSignals içinde kullanılabilir:

generateBid() konumundan oluşturma URL'si döndürme

ads nesnesi, B&A açık artırma yükünde atlandığından generateBid() tarafından döndürülen oluşturma URL'sinin yeniden oluşturulması gerekir. Oluşturma URL'sinin nasıl yeniden oluşturulacağı, uygulamanıza göre belirlenir ve döndürülen URL, ilgi alanları grubunda tanımlanan oluşturma URL'siyle eşleşmelidir.

Bu durumda, temel bir URL'yi koruyup şablonu interestGroup ve trustedBiddingSignals bilgilerini kullanarak doldurabilirsiniz.

Bu örnekte, renk ve ürüne göre 4 reklam tanımlıyoruz:

await navigator.joinAdInterestGroup({
  ads: [
    { renderURL: 'https://dsp.example/red-shirt-ad.html', adRenderId: 'arid1'},
    { renderURL: 'https://dsp.example/blue-shirt-ad.html', adRenderId: 'arid2'},
    { renderURL: 'https://dsp.example/red-pants-ad.html', adRenderId: 'arid3'},
    { renderURL: 'https://dsp.example/blue-pants-ad.html', adRenderId: 'arid4'},
  ],
  trustedBiddingSignalKeys: [
    'userBiddingSignals-someUniqueId',
    // ...and more
  ]
})

Ardından, kullanıcının en sevdiği rengi ve ürün bilgilerini, anahtar/değer hizmetine yüklenecek şekilde göndeririz:

fetch('https://dsp.example/kv/load', {
  body: JSON.stringify({
    'userBiddingSignals-someUniqueId': {
      favoriteColor: 'blue',
      favoriteProduct: 'shirt'
    }
  })
})

Daha sonra, açık artırma çalıştırıldığında güvenilir teklif sinyalleri generateBid() içinde kullanılabilir hale gelir ve bu bilgiler URL'yi yeniden oluşturmak için kullanılabilir:

function generateBid(..., trustedBiddingSignals, browserSignals) {
  const { userBiddingSignals } = trustedBiddingSignals
  const { favoriteColor, favoriteProduct } = userBiddingSignals

  return {
    bid: 1,
    render: `https://dsp.example/${favoriteColor}-${favoriteProduct}-ad.html`
  }
}

generateBid() konumundan raporlama kimliklerini döndürme

Raporlama kimlikleri B&A açık artırma yüküne dahil edilmediğinden kimlik, güvenilir teklif sinyalleri aracılığıyla generateBid() için kullanılabilir hale gelir. Hangi raporlama kimliğinin kullanılacağı belirlendikten sonra, seçilen raporlama kimliği generateBid() tarafından döndürülür. Döndürülen kimlikler, ilgi alanına göre gruplandırılmış kitlede tanımlanan kimliklerle eşleşmelidir.

Bu örnekte, 1. reklam seçilir ve ilişkili oluşturma kimliği generateBid() tarafından döndürülür:

generateBid(..., trustedBiddingSignals, …) {
  const { ad1ReportingId, ad2reportingId } = trustedBiddingSignals;
  // ...
  return {
    bid: 1,
    render: 'https://dsp.example/ad-1.html'
    buyerReportingId: ad1reportingId
  }
}

Döndürülen raporlama kimliği, reportWin() ile buyerReportingSignals arasında kullanılabilir:

reportWin(..., buyerReportingSignals) {
  const { buyerReportingId } = buyerReportingSignals;
}

buyerReportingId, generateBid() tarafından döndürülmezse interestGroupName değeri buyerReportingId yerine buyerReportingSignals içinde kullanılabilir.

Daha fazla bilgi edinmek için Raporlama kimliği kılavuzunu ziyaret edin.

Sonraki adımlar

Aşağıdaki kaynaklardan yararlanabilirsiniz

Daha fazla bilgi

• Chrome'daki B&A açık artırma yapılandırmaları hakkında daha fazla bilgi edinin.
• Uçtan uca yerel test codelab'ini uygulayarak B&A ile Protected Audience'ı deneyin.

Sorularınız mı var?

• Teklif verme ve açık artırma hizmetleriyle ilgili bir sorunuz varsa B&A Services deposunda bir sorun açın.