Raporlama Kimlikleri

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

Genel Bakış

Raporlama kimlikleri, bir reklamla ilişkilendirilmiş ve teklif oluşturma, teklif puanlama ve raporlamada kullanılabilen 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()'te kullanılabilir hale gelir.

Raporlama kimlikleri, bir reklamın tanımlayıcısını bildirmenize ve anlaşmalar gibi kullanım alanlarını etkinleştirmenize olanak tanır.

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şlevleri içinde kullanılabilir. Seçilebilir raporlama kimlikleri, gerekirse seçilebilir olmayan raporlama kimlikleriyle birlikte 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ılabilmeleri için k-anonim olup olmadıkları açısından kontrol edilir.

Seçilemeyen raporlama kimlikleri

Seçilebilir raporlama kimliklerinin kullanılabilirliği

buyerReportingId ve buyerAndSellerReportingId, ilgi alanı grubu yapılandırmasında tanımlanan ve alıcı ile satıcı raporlama işlevlerinde kullanılabilen, 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, üst yazma davranışına bağlı olarak buyerReportingId veya buyerAndSellerReportingId alır ve satıcı raporlama işlevi buyerAndSellerReportingId alır. İlgi alanı grubu yapılandırmasında buyerReportingId veya buyerAndSellerReportingId tanımlanmamışsa reportWin() işlevi, kazanan teklifin ilgi alanı grubu adını (interestGroupName) alır.

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

İlgi gruplarındaki raporlama kimlikleri

Raporlama kimlikleri, bir ilgi alanı grubundaki her 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ı raporları

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ı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). K-anonim değilse reportResult() işlevi yine çalışır ancak raporlama kimliği değeri işlev içinde kullanılamaz.

Alıcı raporları

Açık artırmanın alıcı raporlama aşamasında reportWin() için bir raporlama kimliği kullanılabilir hale gelir. İlgi alanı grubunda birden fazla raporlama kimliği tanımlanmışsa buyerAndSellerReportingId'ün buyerReportingId'ün ü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ımlanmışsa 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ıma sunulan raporlama kimliği, ilgi alanı grubu sahibi, teklifli sistem komut dosyası URL'si, oluşturma URL'si ve reklam boyutu ile k-anonim olup olmadığı açısından kontrol edilir (reklam boyutu en az 2025'in 1. çeyreğine kadar bu kontrolden hariç tutulur). K-anonimlik kontrolünü geçemezse reportWin() yine de çalışır ancak raporlama kimliği değeri işlev içinde kullanılamaz.

Yalnızca buyerReportingId tanımlanır

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

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

Bu durumda 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 buyerAndSellerReportingId tanımlanmıştır

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

Bu durumda 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',
  }]
});

Bu durumda, üst yazma davranışı nedeniyle 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 veya buyerReportingId tanımlanmamış

İlgi grubu yapılandırmasında raporlama kimlikleri tanımlanmamışsa:

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

Ardından, name ilgi alanı grubu reportWin() içinde kullanılabilir:

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ği ile raporlama kimliklerinin kullanılabilirliği

Seçilebilir raporlama kimlikleri, alıcının teklif oluşturma sırasında bir kimlik seçmesine olanak tanır. Tarayıcı, seçilen değeri scoreAd() ve raporlama işlevleri için kullanılabilir hale getirir. Dize dizisi olan selectableBuyerAndSellerReportingIds değeri generateBid()'e sağlanır ve alıcı, selectedBuyerAndSellerReportingId olarak seçili bir kimliği 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 davranışları önceki bölümde açıklanan iş akışında belirtilenden farklı olur. Seçilemeyen raporlama kimliklerinin yalnızca raporlama işlevleri içinde kullanılabildiği ilk davranışın aksine, seçilebilir raporlama kimlikleri, seçilemeyen raporlama kimliklerinin generateBid() ve scoreAd() içinde de kullanılabilmesini sağlar.

Not: Seçilebilir raporlama kimlikleri, M130'ta kararlı sürümde kullanıma sunulacaktır. Seçilebilir raporlama kimlikleri kararlı sürüme ulaşmadan önce, Canary M130 sürümü komut satırından --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=ProtectedAudienceDealsSupport

işaretleriyle başlatılarak test edilebilir.

İlgi alanı 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

selectableBuyerAndSellerReportingIds, ilgi grubu yapılandırmasında tanımlandıysa tanımlanan diğer raporlama kimlikleriyle birlikte generateBid() içinde kullanılabilir hale gelir.

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

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

Alıcı, generateBid() içindeki selectableBuyerAndSellerReportingIds dizisinden bir kimliği seçebilir ve seçili kimliği selectedBuyerAndSellerReportingId olarak döndürebilir. Seçilen değer selectableBuyerAndSellerReportingIds dizisinde yoksa teklif reddedilir. İlgi alanı grubu yapılandırmasında selectableBuyerAndSellerReportingIds tanımlanmışsa ve alıcı generateBid()'den selectedBuyerAndSellerReportingId 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ı, k-anonimlik kontrollerini geçen reklamlar içeren teklifler oluşturmadığı için generateBid()'in yeniden çalıştırılması durumunda, k-anonimlik kontrolünü geçemeyen selectableBuyerAndSellerReportingIds yeniden çalıştırmadaki ilgi alanı grubunda yer almaz.

Satıcı reklamı puanlaması

Satıcı için, generateBid()'ten alıcı tarafından döndürülen selectedBuyerAndSellerReportingId, ilgi alanı grubu yapılandırmasında tanımlanmışsa buyerAndSellerReportingId ile birlikte scoreAd()'de kullanılabilir hale gelir.

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

  // ...
}

Satıcı raporları

Satıcı raporları için, generateBid()'ten alıcı tarafından döndürülen selectedBuyerAndSellerReportingId, ilgi alanı grubunda tanımlanmışsa buyerAndSellerReportingId ile birlikte reportResult()'de kullanılabilir hale gelir.

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

selectableBuyerAndSellerReportingIds ilgi alanı grubu yapılandırmasında tanımlandıysa ve selectedBuyerAndSellerReportingId, generateBid()'den 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 boyutuyla (reklam boyutu en az 2025'in 1. çeyreğine kadar bu kontrolden hariç tutulur) k-anonim olmadığı sürece açık artırmayı kazanamaz ve reportResult() bu teklif için yürütülmez. Bu nedenle, reportResult(), selectedBuyerAndSellerReportingId değeriyle çağrılırsa raporlama kimlikleri k-anonimlik kontrolünü geçmiş demektir ve tanımlanan tüm raporlama kimlikleri reportResult() içinde kullanılabilir.

Alıcı raporları

selectableBuyerAndSellerReportingIds, ilgi grubu yapılandırmasında tanımlandıysa ve selectedBuyerAndSellerReportingId, generateBid()'den döndürüldüyse ilgi grubu yapılandırmasında tanımlanan tüm raporlama kimlikleri kullanılabilir hale gelir. Satıcı raporlamasına benzer şekilde, raporlama kimlikleri k-anonim değilse açık artırmayı kazanamayacaklarını ve reportWin()'nin bu teklif için çalışmayacağını unutmayın.

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 verileri üzerine yazma kurallarını burada özetliyoruz. selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId ve ilgi alanı grubu adından hangisinin reportWin()'e iletileceği tarayıcı tarafından aşağıdaki mantıkla 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 alanı grubunda buyerAndSellerReportingId tanımlanmışsa yalnızca buyerAndSellerReportingId raporlanabilir.
• Aksi takdirde, ilgi alanı grubunda buyerReportingId tanımlanmışsa raporlama için yalnızca buyerReportingId kullanılabilir.
• Aksi takdirde, yalnızca name ilgi grubu raporlanabilir.

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

İlgi alanı grubu yapılandırmasında raporlama kimlikleri tanımlanmış mı?			Kullanılabilir raporlama kimlikleri
selectableBuyerAnd SellerReportingIds	buyerAndSeller ReportingId	buyerReportingId	reportWin()	reportResult()
Evet, generateBid() içinde seçili	İsteğe bağlı	İsteğe bağlı	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (tanımlanmışsa) 3) buyerReportingId (tanımlanmışsa)	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (tanımlanmışsa)
Hayır veya generateBid()'ta seçili değil	Evet	Yok sayıldı	buyerAndSeller ReportingId	buyerAndSeller ReportingId
Hayır veya generateBid()'ta seçili değil	Hayır	Evet	buyerReportingId	Yok
Hayır veya generateBid()'da seçili değil	Hayır	Hayır	interestGroupName	Yok

Etkileşim kurma ve geri bildirim paylaşma

• Raporlama kimlikleri hakkında daha fazla bilgi edinmek için Protected Audience açıklama makalesinin Raporlama Kimliği bölümüne bakın.
• GitHub: API deposunda soru sorun ve sorunlardaki tartışmaları takip edin.
• W3C: WICG toplantısında sektördeki kullanım alanlarını tartışın.
• Duyuru: Posta listesine katılın veya posta listesini görüntüleyin.
• Özel Korumalı Alan geliştirici desteği: Özel Korumalı Alan Geliştirici Desteği deposunda soru sorabilir ve tartışmalara katılabilirsiniz.
• Chromium: Chrome'da test edilebilecek uygulama hakkında soru sormak için Chromium hatası gönderin.