Raporlama Kimlikleri

Raporlama kimliklerinin Protected Audience açık artırmasında nasıl çalıştığını öğrenin

Genel Bakış

Raporlama kimlikleri; teklif oluşturma, teklif puanlama ve raporlamada kullanılabilen, reklamla ilişkili tanımlayıcılardır. Raporlama kimlikleri, ilgi alanı grubu yapılandırmasında alıcı tarafından sağlanır ve bu kılavuzda açıklanan çeşitli koşullar altında generateBid(), scoreAd(), reportResult() ve reportWin() için kullanılabilir hale gelir.

Raporlama kimlikleri, bir reklama ilişkin tanımlayıcıyı raporlamanıza olanak tanır ve ayrıca anlaşmalar gibi kullanım alanlarını etkinleştirmenizi sağlar.

Raporlama kimliklerinin kullanılabilirliği

İki türde üç raporlama kimliği vardır:

• Seçilemeyen raporlama kimlikleri
  • buyerReportingId (dize)
  • buyerAndSellerReportingId (dize)
• Seçilebilir raporlama kimlikleri
  • selectableBuyerAndSellerReportingIds (dize dizisi)

Raporlama kimlikleri, seçilebilir raporlama kimliklerinin kullanılıp kullanılmadığına bağlı olarak farklı şekilde davranır. Yalnızca seçilemeyen raporlama kimlikleri kullanıldığında, bu kimlikler yalnızca raporlama işlevlerinin içinde kullanılabilir hale gelir. Seçilebilir raporlama kimlikleri ve gerekirse seçilemeyen raporlama kimlikleri kullanıldığında, tanımlanan tüm kimlikler generateBid() ve scoreAd() içinde de kullanılabilir hale gelir.

Önemli: Raporlama kimlikleri, raporlama işlevlerinde (reportResult() ve reportWin()) kullanıma sunulmadan önce k-anonimlik açısından kontrol edilir.

Seçilemeyen raporlama kimlikleri

Seçilebilir raporlama kimliklerinin kullanılabilirliği

buyerReportingId ve buyerAndSellerReportingId, alıcı ve satıcı raporlama işlevlerinde kullanılabilen, ilgi alanı grubu yapılandırmasında tanımlanan seçilemeyen raporlama kimlikleridir. Alıcı ve satıcı raporlama işlevleri yalnızca kazanan reklam için çalışır ve işlevler, bu kazanan reklam için tanımlanan raporlama kimliklerini alır.

Seçilebilir raporlama kimlikleri olmadan kullanıldığında, alıcı raporlama işlevi üzerine yazma davranışına bağlı olarak buyerReportingId veya buyerAndSellerReportingId, satıcı raporlama işlevi ise buyerAndSellerReportingId alır. İlgi alanı grubu yapılandırmasında buyerReportingId veya buyerAndSellerReportingId tanımlı değilse reportWin() işlevi, kazanan teklifin ilgi grubu adını (interestGroupName) alır.

Seçilemeyen kimlikler, seçilebilir raporlama kimlikleriyle birlikte kullanılmadıkları takdirde generateBid() ve scoreAd() içinde kullanılamaz.

İlgi alanı gruplarındaki raporlama kimlikleri

Raporlama kimlikleri, bir ilgi alanı grubundaki her bir reklam için alıcı tarafından tanımlanır:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    // buyerAndSellerReportingId goes to the buyer and seller reporting functions
    buyerAndSellerReportingId: 'bsrid123',
    // buyerReportingId is defined here as an example, but
    // is not used due to the overwrite rules described later
    buyerReportingId: 'brid123',
  }]
});

Satıcı raporlama

Satıcı raporlama aşamasında buyerAndSellerReportingId değeri reportResult() tarafından kullanılabilir:

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

Kimlik reportResult() içinde kullanıma sunulmadan önce ilgi alanı grubu sahibi, teklif verme komut dosyası URL'si, oluşturma URL'si ve reklam boyutu ile k-anonim olup olmadığı kontrol edilir (reklam boyutu en az 2025'in 1. çeyreğine kadar bu kontrole dahil edilmez). K-anonim değilse reportResult() işlevi çalışmaya devam eder ancak raporlama kimliği değeri işlevin içinde kullanılamaz.

Alıcı raporları

Açık artırmanın alıcı raporlama aşamasında reportWin() tarafından bir raporlama kimliği kullanılabilir hale gelir. İlgi alanı grubunda birden fazla raporlama kimliği tanımlanırsa buyerAndSellerReportingId ürününün, buyerReportingId değerinin üzerine yazdığı bir üzerine yazma kuralı uygulanır:

• Hem buyerAndSellerReportingId hem de buyerReportingId tanımlanmışsa buyerAndSellerReportingId, buyerReportingId'un üzerine yazar ve buyerAndSellerReportingId, reportWin() içinde kullanılabilir.
• Yalnızca buyerReportingId tanımlanırsa buyerReportingId kullanılabilir.
• buyerAndSellerReportingId veya buyerReportingId tanımlanmamışsa interestGroupName kullanılabilir.

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

reportWin() içinde kullanılabilen raporlama kimliğinin; ilgi alanı grubu sahibi, teklif komut dosyası URL'si, oluşturma URL'si ve reklam boyutu ile k-anonim olup olmadığı kontrol edilir (reklam boyutu en az 2025'in 1. çeyreğine kadar bu kontrole dahil edilmez). K-anonimlik kontrolü başarısız olursa reportWin() çalışmaya devam eder ancak raporlama kimliği değeri işlevin içinde kullanılamaz.

Yalnızca buyerReportingId tanımlandı

İlgi alanı grubu yapılandırmasında yalnızca buyerReportingId tanımlıysa:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
  }]
});

Ardından buyerReportingId, reportWin() içinde kullanılabilir:

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
  } = browserSignals;
}

reportWin() tarafından kullanılabilmesi için buyerReportingId, ilgi alanı grubu sahibi, teklif verme komut dosyası URL'si, oluşturma URL'si ve reklam boyutu ile k-anonimliği açısından kontrol edilir (reklam boyutu en az 2025'in 1. çeyreğine kadar bu kontrolden hariç tutulur).

Yalnızca BuyersAndSellerReportingId tanımlandı

İlgi alanı grubu yapılandırmasında yalnızca buyerAndSellerReportingId tanımlanmışsa:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

Ardından buyerAndSellerReportingId, reportWin() içinde kullanılabilir:

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

reportWin() tarafından kullanılabilmesi için buyerAndSellerReportingId, ilgi alanı grubu sahibi, teklif verme komut dosyası URL'si, oluşturma URL'si ve reklam boyutu ile k-anonimliği açısından kontrol edilir (reklam boyutu en az 2025'in 1. çeyreğine kadar bu kontrolden hariç tutulur).

Hem buyerAndSellerReportingId hem de buyerReportingId tanımlanmışsa

İlgi alanı grubu yapılandırmasında hem buyerAndSellerReportingId hem de buyerReportingId tanımlanmışsa:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

Üzerine yazma davranışı nedeniyle bu durumda reportWin() içinde yalnızca buyerAndSellerReportingId kullanılabilir:

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

reportWin() tarafından kullanılabilmesi için buyerAndSellerReportingId, ilgi alanı grubu sahibi, teklif verme komut dosyası URL'si, oluşturma URL'si ve reklam boyutu ile k-anonimliği açısından kontrol edilir (reklam boyutu en az 2025'in 1. çeyreğine kadar bu kontrolden hariç tutulur).

buyerAndSellerReportingId ve buyerReportingId tanımlı değil

İlgi alanı grubu yapılandırmasında iki raporlama kimliği de tanımlanmamışsa:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
  }]
});

Ardından name ilgi grubu, reportWin() içinde mevcut:

function reportWin(..., browserSignals, ...) {
  const {
    interestGroupName, // 'example-interest-group'
  } = browserSignals;
}

İlgi alanı grubu adı (interestGroupName), reportWin() tarafından kullanılabilir hale gelmeden önce ilgi alanı grubu sahibi, teklif verme komut dosyası URL'si, oluşturma URL'si ve reklam boyutu ile k-anonimliği açısından kontrol edilir (reklam boyutu en az 2025'in 1. çeyreğine kadar bu kontrolden hariç tutulur).

Seçilebilir raporlama kimlikleri

Seçilebilir raporlama kimliğiyle raporlama kimliklerinin kullanılabilirliği

Seçilebilir raporlama kimlikleri, alıcının teklif oluşturma sırasında kimlik seçmesine olanak tanır. Tarayıcı da seçilen değeri scoreAd() ve raporlama işlevleri için kullanılabilir hale getirir. Bir dize dizisi olan selectableBuyerAndSellerReportingIds değeri generateBid() öğesine sağlanır ve alıcı, seçilen bir kimliği selectedBuyerAndSellerReportingId olarak döndürebilir.

generateBid() ve scoreAd() işlevleri, ilgi alanı grubu yapılandırmasında tanımlanan her reklam için çalıştırılır ve her reklamın raporlama kimliklerini alır. Alıcı ve satıcı raporlama işlevleri yalnızca kazanan reklam için çalışır ve işlevler, bu kazanan reklam için tanımlanan raporlama kimliklerini alır.

Seçilemeyen raporlama kimlikleri, seçilebilir raporlama kimlikleriyle birlikte kullanıldığında, bunların davranışı bir önceki bölümde açıklanan iş akışına göre değişir. Seçilemeyen raporlama kimliklerinin yalnızca raporlama işlevlerinde bulunan ilk davranışından farklı olarak, seçilebilir raporlama kimlikleri, seçilemeyen raporlama kimliklerinin generateBid() ve scoreAd() içinde de kullanılabilir olmasını sağlar.

Not: Seçilebilir raporlama kimlikleri, M130 sürümündeki Kararlı sürümünde kullanılabilecek. Seçilebilir raporlama kimlikleri Kararlı'ya ulaşmadan önce, komut satırından --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=ProtectedAudienceDealsSupport işaretleriyle Canary M130 başlatılarak test edilebilir.

İlgi grubu

Seçilebilir raporlama kimlikleri alanı (selectableBuyerAndSellerReportingIds), bir reklamın ilgi alanı grubunda alıcı tarafından tanımlanan bir dize dizisidir. Seçilebilir raporlama kimliklerinin yanı sıra seçilemeyen raporlama kimlikleri de tanımlanabilir:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
    selectableBuyerAndSellerReportingIds: ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }]
});

Alıcı teklifi oluşturma

İlgi alanı grubu yapılandırmasında selectableBuyerAndSellerReportingIds tanımlanmışsa tanımlanan diğer raporlama kimlikleriyle birlikte generateBid() içinde kullanılabilir hale gelir.

function generateBid(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
  } = browserSignals;

  return {
    bid: 1,
    render: 'https://buyer.example/ad.html',
    selectedBuyerAndSellerReportingId: 'sbsrid2' // Buyer returns the selected ID
  };
}

Alıcı, generateBid() içindeki selectableBuyerAndSellerReportingIds dizisindeki kimliklerden birini seçebilir ve seçilen kimliği selectedBuyerAndSellerReportingId olarak döndürebilir. Seçilen değer selectableBuyerAndSellerReportingIds dizisinde değilse teklif reddedilir. İlgi alanı grubu yapılandırmasında selectableBuyerAndSellerReportingIds tanımlanmışsa ve alıcı generateBid() üzerinden selectedBuyerAndSellerReportingId değerini döndürmezse raporlama kimlikleri, seçilemeyen raporlama kimlikleri için açıklanan davranışa geri döner.

selectedbuyerAndSellerReportingId için döndürülen bir değere sahip teklif yalnızca açık artırmayı kazanabilir. Bunun için selectedbuyerAndSellerReportingId değeri, buyerAndSellerReportingId (varsa), buyerReportingId (varsa), ilgi alanı grubu sahibi, teklif verme komut dosyası URL'si, oluşturma URL'si ve reklam boyutuyla birlikte ortak k-anonim olmalıdır (reklam boyutu en az 2025'in 1. çeyreğine kadar bu kontrolden hariç tutulur).

Not: İlk çağrının k-anonimlik kontrollerini geçen reklamlarla ilgili herhangi bir teklif vermemesi nedeniyle generateBid() yeniden çalıştırıldığı durumlarda, k-anonimlik kontrolünü geçemeyen seçili AlıcıAndSellerReportingId öğeleri, yeniden çalıştırılan ilgi alanı grubunda yer almaz.

Satıcı reklam puanı

Satıcı için generateBid() tarihinden itibaren alıcı tarafından iade edilen selectedBuyerAndSellerReportingId, scoreAd() içinde ve ilgi alanı grubu yapılandırmasında tanımlanmışsa buyerAndSellerReportingId ile birlikte kullanılabilir.

function scoreAd(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId, // 'sbsrid2'
  } = browserSignals;

  // ...
}

Satıcı raporlama

Satıcı raporları için generateBid() tarihinden itibaren alıcı tarafından iade edilen selectedBuyerAndSellerReportingId, ilgi alanı grubunda tanımlanmışsa buyerAndSellerReportingId ile birlikte reportResult() içinde kullanılabilir hale gelir.

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;
  
  // ...
}

selectableBuyerAndSellerReportingIds, ilgi alanı grubu yapılandırmasında tanımlanmışsa ve selectedBuyerAndSellerReportingId generateBid() üzerinden döndürüldüyse selectedBuyerAndSellerReportingId ve buyerAndSellerReportingId (varsa) ilgi alanı grubu sahibi, teklif verme komut dosyası URL'si, oluşturma URL'si ve reklam boyutu (reklam boyutu en azından 2025'in 1. çeyreğine kadar bu kontrolden hariç tutulur) ile k-anonim olmadığı sürece açık artırmayı kazanamaz. reportResult() bu teklif için yürütülmez. Bu nedenle, reportResult(), selectedBuyerAndSellerReportingId için bir değerle çağrılırsa k-anonimlik kontrolünden geçmiş raporlama kimlikleri ve tanımlanan tüm raporlama kimlikleri reportResult() içinde kullanılabilir olur.

Alıcı raporları

İlgi alanı grubu yapılandırmasında selectableBuyerAndSellerReportingIds tanımlanmışsa ve generateBid() öğesinden selectedBuyerAndSellerReportingId döndürüldüyse ilgi alanı grubu yapılandırmasında tanımlanan tüm raporlama kimlikleri kullanılabilir hale gelir. Satıcı raporlarına benzer şekilde k-anonim olmayan raporlama kimlikleri, açık artırmayı kazanamaz ve reportWin() bu teklif için çalışmaz.

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;

  // ...
}

Kurallar üzerinde değişiklik yapma

Hem seçilemeyen hem de seçilebilir raporlama kimlikleri için üzerine yazma kurallarını burada özetliyoruz. Hangi selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId ve ilgi alanı grubu adının reportWin() öğesine iletileceği tarayıcı tarafından aşağıdaki mantığa göre belirlenir:

• Bir tekliften selectedBuyerAndSellerReportingId döndürülürse selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (ilgi alanı grubunda tanımlanmışsa) ve buyerReportingId (ilgi alanı grubunda tanımlanmışsa) raporlama için kullanılabilir.
• Aksi takdirde, ilgi grubunda buyerAndSellerReportingId tanımlanmışsa yalnızca buyerAndSellerReportingId raporlanabilir.
• Aksi takdirde, ilgi grubunda buyerReportingId tanımlanmışsa yalnızca buyerReportingId raporlanabilir.
• Aksi takdirde, raporlama için yalnızca name ilgi alanı grubu kullanılabilir.

Aşağıdaki tabloda, üzerine yazma davranışı açıklanmaktadır:

Raporlama kimlikleri, ilgi grubu yapılandırmasında tanımlanmış mı?			Kullanılabilir raporlama kimlikleri
selectableBuyerAnd SellerReportingIds	buyerAndSeller ReportingId	buyerReportingId	reportWin()	reportResult()
Evet ve generateBid() grubunda seçildi	İsteğe bağlı	İsteğe bağlı	1) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (tanımlanmışsa) 3) buyerReportingId (tanımlanmışsa)	1) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (tanımlanmışsa)
Hayır veya generateBid()'ta seçilmedi	Evet	Yok sayıldı	buyerAndSeller ReportingId	buyerAndSeller ReportingId
Hayır veya generateBid() grubunda seçilmedi	Hayır	Evet	buyerReportingId	Yok
Hayır veya generateBid() grubunda seçilmedi	Hayır	Hayır	interestGroupName	Yok

Etkileşimde bulunun ve geri bildirim paylaşın

• Raporlama kimlikleri hakkında daha fazla bilgi edinmek için Protected Audience açıklama makalesinin Raporlama Kimliği bölümüne göz atın.
• GitHub: API deposundaki sorular sorun ve sorunlarla ilgili tartışmaları takip edin.
• W3C: WICG görüşmesinde sektördeki kullanım alanlarını tartışın.
• Duyurular: Posta listesine katılın veya bu listeyi görüntüleyin.
• Özel Korumalı Alan geliştirici desteği: Özel Korumalı Alan Geliştirici Desteği deposunda sorular sorun ve tartışmalara katılın.
• Chromium: Chrome'da test edilebilecek uygulama hakkında sorular sormak için bir Chromium hatası bildirin.