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 olanak tanır ve anlaşmalar gibi kullanım alanlarını da etkinleştirir.

İki tür 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.

Seçilemeyen raporlama kimlikleri

buyerReportingId ve buyerAndSellerReportingId, ilgi 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 değerini, satıcı raporlama işlevi ise buyerAndSellerReportingId değerini 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 boyutuyla 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 de çalışır ancak raporlama kimliği değeri işlevde 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'ü ü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-anonimliği 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() için kullanılabilir hale gelmeden önce buyerReportingId, ilgi alanı grubu sahibi, teklifli sistem 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, teklifli sistem 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, teklifli sistem 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 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, teklifli sistem 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 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.

İ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 alanı grubu yapılandırmasında tanımlandıysa tanımlanan diğer raporlama kimlikleriyle birlikte generateBid() içinde kullanılabilir.

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 kimlik 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).

Satıcı reklamı puanlaması

Satıcı için, generateBid()'ten alıcı tarafından iade edilen 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 yayınlanmayacağı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 üzerine yazma kurallarını burada özetliyoruz. selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId ve ilgi alanı grubu adından hangisinin reportWin()'a 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 grubunda buyerAndSellerReportingId tanımlanmışsa yalnızca buyerAndSellerReportingId raporlanabilir.
• Aksi takdirde, ilgi grubunda buyerReportingId tanımlanmışsa yalnızca buyerReportingId raporlanabilir.
• Aksi takdirde, yalnızca name ilgi grubu raporlanabilir.

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

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 göz atın.
• GitHub: API deposunda soru sorabilir ve sorunlarla ilgili tartışmaları takip edebilirsiniz.
• W3C: WICG görüşmesinde sektördeki kullanım alanlarını tartışın.
• Duyuru: 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 soru sorabilir ve tartışmalara katılabilirsiniz.
• Chromium: Chrome'da test edilebilecek uygulama hakkında soru sormak için Chromium hatası gönderin.