Bu sayfa, Cloud Translation API ile çevrilmiştir.

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 B&A PA açık artırmasıyla nasıl entegrasyon sağlayabileceği açıklanmaktadır.

Genel Bakış

Alıcı, B&A Hizmetleri ile Protected Audience açık artırmasına katılmak için ilgi alanı grubunu (IG) güncelleyerek yükü, açık artırma gecikmesini azaltacak şekilde optimize eder.

Alıcının aşağıdaki yükü optimize etme görevlerini yapması gerekir:

joinAdInterestGroup() görev
generateBid() görev

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,
});

Karşılaştırmalı test ve cihaz üzerinde ilgi alanı grubu yapılandırmaları arasındaki farklar şunlardır:

Alanlar	B&A IG	Cihaz üzerinde IG	B&A açık artırma yüküne dahildir
`auctionServerRequestFlags`	İkinci el	Kullanılmadı	Hayır
`userBiddingSignals`	Önerilmez	İkinci el	Hayır, `omit-user-bidding-signals` işareti ayarlandıysa
`ads` ve `adComponents` konumunda `adRenderId`	İkinci el	Kullanılmadı	`omit-ads` işareti ayarlanmışsa `ads` içindeki `adRenderId` yalnızca yükün `browserSignals.prevWins` bölümünde kullanılabilir. `adComponents` içinde tanımlanan `adRenderId` yüke dahil edilmemiştir. `omit-ads` işareti ayarlanmamışsa `browserSignals.prevWins`, `interestGroup.adRenderIds` ve `interestGroup.adComponentRenderIds`'te kullanılabilir.
`ads` ve `adComponents` konumunda `renderURL`	İkinci el	İkinci el	Hayır
`ads` ve `adComponents` konumunda `metadata`	Kullanılmadı	İkinci el	Hayır
`ads`'teki raporlama kimlikleri	İkinci el	İkinci el	Hayır

auctionServerRequestFlags alanı, tarayıcıya B&A açık artırma yükündeki bazı verileri atlamasını söyleyen işaretler ayarlamanıza olanak tanır.
userBiddingSignals değeri ilgi alanı grubunda tanımlanabilir ancak omit-user-bidding-signals işaretçisi kullanılarak 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ü haline gelir. Açık artırma sırasında daha sonra generateBid()'ten döndürülen oluşturma URL'si, IG'de tanımlanan oluşturma URL'siyle eşleşmelidir.
Raporlama kimlikleri B&A IG'sinde 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()'ten 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, Güvenilir Anahtar/Değer Hizmeti kullanımıyla kullanılabilir hale gelir.

Tarayıcının, Teklif Verme Hizmeti'nin generateBid() işlevinden döndürülen oluşturma URL'sinin ve raporlama kimliklerinin ilgi alanı grubunda tanımlanan değerlerle eşleşip eşleşmediğini kontrol etmesi nedeniyle, ads içindeki renderURL'lerin ve raporlama kimliklerinin açık artırma isteği yükü içerisine dahil edilmemesine rağmen ilgi alanı grubu yapılandırmasında hâlâ tanımlandığını unutmayın.

`joinAdInterestGroup()` görev

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

Sunucu istek işaretlerini ayarlama

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

İşaret Açıklama

omit-user-bidding-signals

omit-user-bidding-signals işareti, açık artırma yükündeki userBiddingSignals nesnesini atlar.

İşaretçi ayarlanmazsa ilgi alanı grubunda tanımlanan userBiddingSignals değeri, Teklif Verme Hizmeti'nin generateBid() içinde kullanılabilir hale gelir.

omit-ads

omit-ads işareti, tarayıcıya açık artırma yükündeki ads ve adComponents nesnelerini çıkarmasını söyler.

adRenderId, browserSignals'nin prevWins mülkünde kullanılabilir.

İşaretçi ayarlanmamışsa generateBid() işlevinin interestGroup bağımsız değişkenindeki adRenderIds ve adComponentRenderIds alanları, ilgili reklam oluşturma kimliklerini içerir.

Alıcıların omit-ads işaretini kullanmaları önemle tavsiye edilir. Gelecekte, daha fazla yük optimizasyonu için istemciden oluşturma kimlikleri ve reklam bileşeni oluşturma kimlikleri iletme desteği sonlandırılabilir.

Atlanan veriler, ilgili bilgilerin trustedBiddingSignals'te sağlanmasıyla ele alınır. İşaretler ayrı ayrı kullanılabilir ve birlikte kullanılmaları 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ü boyutunu azaltmak için ilgi alanı grubunun ads ve adComponents nesneleri atlanır ve bu nesneler de Teklif Verme Hizmeti'nde çalışan generateBid() işlevinde kullanılamaz.

Eksik reklam bilgilerini işlemek için alıcı, ilgi alanı grubu yapılandırmasında her reklamla ilişkili bir tanımlayıcı (adRenderId ve adComponentRenderId) tutar. Tanımlayıcı, 12 bayt veya daha kısa bir DOM dizesi olmalıdır. Tanımlayıcı Base64 olarak kodlanmışsa uzunluğu 12 bayt veya daha kısa olmalıdır.

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

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()'de prevWins.browserSignals'te kullanıma sunulur.

renderURL, istek yüküne dahil edilmese de generateBid() adresinden 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 teknolojileri, reklam meta verilerini ve diğer bilgileri trustedBiddingSignals içinde 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 alanı grubu önceliklerini ayarlama

Chrome, alıcıların ilgi alanı 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 ilgi alanı grubu öncelik değerleri, tek bir alıcı için daha düşük öncelikli ilgi alanı gruplarını çıkarmak üzere kullanılır. Tarayıcı, farklı alıcılar arasında ilgi alanı gruplarını seçerken serileştirilmiş yükün boyutuna göre karar verir. Varsayılan olarak her alıcıya eşit bir boyut verilir. Gerçek önceliğin, istek yükü oluşturulduğunda değil, B&A sunucularında yapıldığını unutmayın.

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

Özellik	Açıklama
Öncelik vektörü	Alıcı, K/V Hizmeti'ndeki `priorityVector` anahtarının değeri olarak vektörleri sağlar.
Öncelikli sinyaller	Satıcı, açık artırma yapılandırmasının `priority_signals` değerini ayarlayarak sinyalleri sağlar
Öncelikli sinyallerin geçersiz kılması	Alıcı, açık artırma yapılandırmasında `PerBuyerConfig` öğesinin `priority_signals_overrides` alanında geçersiz kılma bilgisini sağlar.

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'e düşürülür. Bu nedenle, açık artırma sırasında bu ilgi alanı grubunun önceliği 5 olur.

Öncelik vektörü ve öncelik sinyalleri nesnelerindeki her anahtar birbiriyle çarpılır, ardından önceliği hesaplamak için sonuçlar toplanır. — **Şekil 1**: Alıcının vektörleri ve satıcının sinyalleri kullanılarak öncelik hesaplaması

Karşılaştırmalı analizde öncelik belirlemek için kullanılabilecek ek sinyaller de vardır:

Sinyal	Açıklama
`deviceSignals.one`	Değer her zaman 1'dir ve nokta çarpımına sabit eklemek için kullanışlıdır.
`deviceSignals.ageInMinutes`	Değer,ilgi alanı grubunun yaşını (en son ilgi alanı grubuna katılma tarihinden itibaren geçen süre) 0 ile 43.200 arasında bir tam sayı olarak dakika cinsinden açıklar.
`deviceSignals.ageInMinutesMax60`	Değer, `ageInMinutes` sinyali ile aynı şeyi tanımlar ancak maksimum 60'tır. Grup 1 saatten eskiyse 60 döndürülür.
`deviceSignals.ageInHoursMax24`	Değer, ilgi grubunun yaşını saat cinsinden tanımlar ve en fazla 24 saat olabilir. Grup bir günden eskiyse 24 döndürülür.
`deviceSignals.ageInDaysMax30`	Bu değer, ilgi grubunun yaşını gün cinsinden tanımlar ve en fazla 30 gün olabilir. Grup 30 günden eskiyse 30 döndürülür.

Daha fazla bilgi için GitHub'daki açıklamayı inceleyin.

Güvenilir teklif sinyalleri oluşturma

Bazı veriler B&A açık artırma yükü kapsamından çıkarılacağından, çıkarılan verileri generateBid() işlevine güvenilir teklif sinyalleri olarak sağlamak için Anahtar/Değer Hizmeti'ni kullanabilirsiniz.

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

userBiddingSignals alıcı tarafından kullanılıyorsa
Her reklamla ilişkilendirilen metadata
Her reklamla ilişkilendirilen adRenderId
Raporlama Kimliği

İlgi alanı grubundan çıkarılan veriler, alıcının toplama sunucusuna gönderilebilir. Toplama sunucusu verileri anahtar/değer hizmetine gönderir ve daha sonra tarayıcı bu verileri anahtar/değer hizmetinden yükler. — **Şekil 2: Güvenilir sinyaller kurulum örneği**

Güvenilir teklif sinyalleri anahtarlarına benzersiz bir tanımlayıcı ekleyip ardından anahtar/değer hizmetine yüklenmesi için ilişkili verileri sunucunuza gönderebilirsiniz. Ancak gerçek uygulama reklam teknolojisine bağlıdır ve API talimat vermez.

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 bir 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 hizmetine yüklenmesi için sunucunuza gönderilir. Açık artırma sırasında daha sonra tarayıcı, güvenilir sinyalleri getirir ve alıcının generateBid() işlevinde kullanılabilir hale getirir.

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

Güvenilir sinyaller için updateIfOlderThanMs anahtarı, ilgi alanı grubunu normal günlük aralıktan daha erken 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 birleştirilmez veya güncellenmezse updateURL mekanizmasıyla güncellenir. Chrome'un ilgi alanı gruplarını 10 dakikadan daha sık güncellemediğini unutmayın.

B&A 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ı kaybeder. updateIfOlderThanMs mekanizması, tarayıcı ile B&A açık artırmasının ilgi alanı grubundaki reklam grubuyla ilgili olarak anlaşmasını sağlamada yararlı olabilir.

Daha fazla bilgi için açıklamayı inceleyin.

`generateBid()` görev

generateBid() çağrısı 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,
}

browserSignals'te aşağıdaki değiştirilmiş veya yeni özellikler kullanılabilir:

Özellik	Açıklama
`prevWins`	`prevWins`, zaman ve reklamdan oluşan bir tuple dizisidir. Zaman, ilişkili reklamın son 30 gün içindeki önceki kazanışından bu yana geçen saniyeleri gösterir. `ad` nesnesi yerine `adRenderId` nesnesi sağlayacak şekilde değiştirildi.
`wasmHelper`	`biddingWasmHelperURL` adresinden sağlanan kodun derlenmiş nesnesi.
`dataVersion`	Güvenilir bir sunucu, isteğe bağlı olarak `generateBid()` sürümünde kullanıma sunulan sayısal bir `Data-Version` yanıt üstbilgisi içerebilir. Daha fazla bilgi edinmek için GitHub'daki açıklamayı okuyun.

`generateBid()` adresinden oluşturma URL'sini döndürme

ads nesnesi B&A açık artırma yükü içinde atlandığından, generateBid()'ten döndürülen oluşturma URL'si yeniden oluşturulmalıdır. Oluşturma URL'sinin nasıl yeniden oluşturulacağı uygulamanıza bağlıdır ve döndürülen URL, ilgi alanı grubunda tanımlanan oluşturma URL'siyle eşleşmelidir.

Uygulayabileceğiniz bir yaklaşım, temel bir URL'yi korumak ve şablonu interestGroup ve trustedBiddingSignals'daki bilgilerle doldurmaktır.

Bu örnekte, renge ve ürüne göre 4 reklam tanımlarız:

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 favori rengini ve ürün bilgilerini Anahtar/Değer Hizmeti'ne yüklenmek üzere 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()'te 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()`'ten raporlama kimlikleri 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() tarafından kullanılabilir. Kullanılacak raporlama kimliği belirlendikten sonra, seçilen raporlama kimliği generateBid() üzerinden döndürülür. Döndürülen kimlikler, ilgi alanı grubunda tanımlanan kimliklerle eşleşmelidir.

Bu örnekte 1. reklam seçilir ve ilişkili oluşturma kimliği generateBid() kaynağı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;
}

generateBid()'dan buyerReportingId döndürülmezse buyerReportingId yerine buyerReportingSignals'da interestGroupName değeri kullanılabilir.

Daha fazla bilgi için Reporting ID 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 ve Açık Artırma Hizmetleri ile ilgili sorularınız varsa Teklif ve Açık Artırma Hizmetleri deposunda bir sorun açın.
Genel olarak Özel Korumalı Alan hakkında sorunuz varsa privacy-sandbox-dev-support deposunda bir sorun açın.