Raporlama kimlikleri

Protected Audience açık artırmasında raporlama kimliklerinin işleyiş şekli

Genel Bakış

Raporlama kimlikleri, teklif oluşturma, teklif puanlama ve raporlama işlemlerinde kullanılabilen, bir reklamla ilişkili tanımlayıcılardır. Raporlama kimlikleri, alıcı tarafından ilgi alanı grubu yapılandırmasında sağlanır ve bu kılavuzda ele alınan çeşitli koşullar altında generateBid(), scoreAd(), reportResult() ve reportWin()'de kullanılabilir.

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

İ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şlevlerinde kullanılabilir. Seçilebilir raporlama kimlikleri kullanıldığında (gerekirse seçilemeyen raporlama kimlikleriyle birlikte) tanımlanan tüm kimlikler generateBid() ve scoreAd() içinde de kullanılabilir.

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 bu işlevler, 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 ve buyerAndSellerReportingId tanımlanmamışsa reportWin() işlevi, kazanan teklifin ilgi alanı grubu adını (interestGroupName) alır.

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

İlgi alanlarına göre gruplarda 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ı raporlaması

Satıcı raporlama aşamasında, buyerAndSellerReportingId değeri reportResult() için kullanılabilir hale gelir:

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 (reklam boyutu, en az 2025'in 1. çeyreğine kadar bu kontrolün dışında tutulur) k-anonimliği açısından kontrol edilir. K-anonim değilse reportResult() işlevi yine çalışır 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() için bir raporlama kimliği kullanılabilir. İlgi alanları grubunda birden fazla raporlama kimliği tanımlanmışsa buyerAndSellerReportingId, buyerReportingId değerinin üzerine yazıldığı bir geçersiz kılma kuralı uygulanır:

• Hem buyerAndSellerReportingId hem de buyerReportingId tanımlanırsa buyerAndSellerReportingId, buyerReportingId'nin ü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ılabilen raporlama kimliğinin k-anonimliği, 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) birlikte kontrol edilir. K-anonimlik kontrolünden geçemezse reportWin() yine çalışır ancak raporlama kimliği değeri işlevin içinde kullanılamaz.

Yalnızca buyerReportingId tanımlı

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

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

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

reportWin() tarafından kullanılabilir hale gelmeden önce buyerReportingId, 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 kontrolün dışında tutulur) k-anonimliği açısından kontrol edilir.

Yalnızca buyerAndSellerReportingId tanımlanmış

İ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ılabilir hale gelmeden önce buyerAndSellerReportingId, 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 kontrolün dışında tutulur) k-anonimliği açısından kontrol edilir.

Hem buyerAndSellerReportingId hem de buyerReportingId tanımlanmışsa

İlgi alanı grubu yapılandırmasında hem buyerAndSellerReportingId hem de buyerReportingId tanımlanırsa:

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

Ardından, üzerine yazma davranışı nedeniyle reportWin() içinde yalnızca buyerAndSellerReportingId kullanılabilir:

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

reportWin() tarafından kullanılabilir hale gelmeden önce buyerAndSellerReportingId, 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 kontrolün dışında tutulur) k-anonimliği açısından kontrol edilir.

Ne buyerAndSellerReportingId ne de buyerReportingId tanımlanmış

İlgi grubu yapılandırmasında raporlama kimliklerinden hiçbiri tanımlanmamışsa:

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

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

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

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

Seçilebilir raporlama kimlikleri

Seçilebilir raporlama kimlikleri, bir alıcının teklif oluşturma sırasında bir kimlik seçmesine olanak tanır ve tarayıcı, seçilen değeri scoreAd() ve raporlama işlevleri için kullanılabilir hale getirir. Dize dizisi olan selectableBuyerAndSellerReportingIds değeri, generateBid()'ye 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ışı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 bu işlevler, kazanan reklam için tanımlanan raporlama kimliklerini alır.

Seçilemeyen raporlama kimlikleri, seçilebilen raporlama kimlikleriyle birlikte kullanıldığında davranışları önceki bölümde açıklanan iş akışından farklı olur. Seçilemeyen raporlama kimliklerinin yalnızca raporlama işlevlerinde kullanılabilir olduğu ilk davranışın aksine, seçilebilir raporlama kimlikleri, seçilemeyen raporlama kimliklerinin generateBid() ve scoreAd() içinde de kullanılabilir olmasını sağlar.

İlgi alanı grubu

Seçilebilir raporlama kimlikleri alanı (selectableBuyerAndSellerReportingIds), bir reklam için alıcı tarafından ilgi alanları grubunda tanımlanan bir dizidir. Seçilemeyen raporlama kimlikleri, seçilebilen raporlama kimlikleriyle birlikte 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ımlanmışsa 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ı, selectableBuyerAndSellerReportingIds dizisindeki kimliklerden birini generateBid() içinde 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()'dan selectedBuyerAndSellerReportingId döndürmüyorsa 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, selectedbuyerAndSellerReportingId değeri buyerAndSellerReportingId (varsa), buyerReportingId (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 kontrolün dışında tutulur) birlikte k-anonim ise selectedbuyerAndSellerReportingId yalnızca açık artırmayı kazanabilir.

Satıcı reklamı puanı

Satıcı için, alıcı tarafından generateBid() konumundan iade edilen selectedBuyerAndSellerReportingId, ilgi alanı grubu yapılandırmasında tanımlanmışsa buyerAndSellerReportingId ile birlikte scoreAd() konumunda kullanılabilir hâle gelir.

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

  // ...
}

Satıcı raporlaması

Satıcı raporlaması için, alıcı tarafından generateBid() üzerinden döndürülen selectedBuyerAndSellerReportingId, ilgi alanları grubunda tanımlanmışsa buyerAndSellerReportingId ile birlikte reportResult() içinde kullanılabilir hâle gelir.

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

selectableBuyerAndSellerReportingIds ilgi alanı grubu yapılandırmasında tanımlanmışsa ve selectedBuyerAndSellerReportingId, generateBid()'dan döndürülmüşse 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 kontrolün dışında tutulur) k-anonim olmadığı sürece açık artırmayı kazanamaz ve bu teklif için reportResult() yürütülmez. Bu nedenle, reportResult() işlevi selectedBuyerAndSellerReportingId için bir değerle çağrılırsa raporlama kimliklerinin k-anonimlik kontrolünü geçtiği ve tanımlanan tüm raporlama kimliklerinin reportResult() içinde kullanılabileceği anlamına gelir.

Alıcı raporları

İlgi grubu yapılandırmasında selectableBuyerAndSellerReportingIds tanımlanmışsa ve generateBid()'den selectedBuyerAndSellerReportingId döndürülmüşse 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ı kazanamaz ve bu teklif için reportWin() çalıştırılmaz.

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

  // ...
}

Kuralların üzerine yazma

Burada hem seçilemeyen hem de seçilebilen raporlama kimlikleri için üzerine yazma kurallarını ö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 alanları grubunda tanımlanmışsa) ve buyerReportingId (ilgi alanları grubunda tanımlanmışsa) raporlama için kullanılabilir.
• Aksi takdirde, ilgi grubunda buyerAndSellerReportingId tanımlanmışsa raporlama için yalnızca buyerAndSellerReportingId kullanılabilir.
• Aksi takdirde, ilgi grubunda buyerReportingId tanımlanmışsa raporlama için yalnızca buyerReportingId kullanılabilir.
• Aksi takdirde, raporlama için yalnızca ilgi alanı grubu name kullanılabilir.

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çıklayıcısının raporlama kimliği bölümüne bakın.
• GitHub: API deposundaki sorunlarla ilgili sorular sorun ve tartışmaları takip edin.
• W3C: WICG görüşmesinde sektördeki kullanım alanlarını tartışın.
• Duyurular: Posta listesine katılın veya listeyi görüntüleyin.
• Özel Korumalı Alan geliştirici desteği: Özel Korumalı Alan geliştirici desteği deposunda soru sorun ve tartışmalara katılın.
• Chromium: Chrome'da test edilebilen uygulama hakkında soru sormak için Chromium hatası bildirin.