شناسه های گزارش

با نحوه عملکرد شناسه‌های گزارش‌دهی در حراج مخاطب محافظت‌شده آشنا شوید

نمای کلی

شناسه‌های گزارش، شناسه‌های مرتبط با یک آگهی هستند که برای استفاده در ارائه پیشنهاد، امتیاز دادن به پیشنهاد و گزارش در دسترس هستند. شناسه‌های گزارش توسط خریدار در پیکربندی گروه علاقه‌مند ارائه می‌شوند و در generateBid() ، scoreAd() ، reportResult() و reportWin() تحت شرایط مختلفی که در این راهنما مورد بحث قرار گرفته‌اند، در دسترس قرار می‌گیرند.

شناسه‌های گزارش به شما امکان می‌دهند یک شناسه برای یک آگهی گزارش دهید، و همچنین موارد استفاده مانند معاملات را فعال کنید.

شناسه های گزارش برای عملکردهای خریدار و فروشنده مخاطب محافظت شده در دسترس قرار می گیرد
گزارش در دسترس بودن شناسه ها

سه شناسه گزارش از دو نوع وجود دارد:

  • شناسه های گزارش غیر قابل انتخاب
    • buyerReportingId (یک رشته)
    • buyerAndSellerReportingId (یک رشته)
  • شناسه های گزارش قابل انتخاب
    • selectableBuyerAndSellerReportingIds (آرایه ای از رشته ها)

شناسه‌های گزارش‌دهی بسته به اینکه از شناسه‌های گزارش قابل انتخاب استفاده می‌شوند، رفتار متفاوتی دارند. وقتی فقط از شناسه های گزارش غیر قابل انتخاب استفاده می شود، آن شناسه ها فقط در داخل توابع گزارش در دسترس می شوند. هنگامی که از شناسه های گزارش قابل انتخاب، همراه با شناسه های گزارش غیر قابل انتخاب در صورت نیاز استفاده می شود، تمام شناسه های تعریف شده در داخل generateBid() و scoreAd() نیز موجود می شوند.

شناسه های گزارش غیر قابل انتخاب

شناسه های گزارش برای عملکردهای خریدار و فروشنده مخاطب محافظت شده در دسترس قرار می گیرد
در دسترس بودن شناسه گزارش قابل انتخاب

buyerReportingId و buyerAndSellerReportingId شناسه های گزارش غیر قابل انتخاب هستند که در پیکربندی گروه علاقه تعریف شده اند و در عملکردهای گزارش خریدار و فروشنده در دسترس هستند. عملکردهای گزارش خریدار و فروشنده فقط برای آگهی برنده اجرا می شوند و توابع شناسه های گزارش تعریف شده برای آن آگهی برنده را دریافت خواهند کرد.

هنگامی که بدون شناسه های گزارش قابل انتخاب استفاده می شود، تابع گزارش خریدار بسته به رفتار رونویسی، buyerReportingId یا buyerAndSellerReportingId را دریافت می کند، و تابع گزارش فروشنده buyerAndSellerReportingId دریافت می کند. اگر نه buyerReportingId و نه buyerAndSellerReportingId در پیکربندی گروه علاقه تعریف نشده باشند، تابع reportWin() نام گروه علاقه ( interestGroupName ) پیشنهاد برنده را دریافت می کند.

شناسه‌های غیرقابل انتخاب در داخل generateBid() و scoreAd() در دسترس نیستند اگر همراه با شناسه‌های گزارش قابل انتخاب استفاده نشوند.

گزارش شناسه ها در گروه های ذینفع

شناسه های گزارش توسط خریدار برای هر آگهی در یک گروه علاقه تعریف می شود:

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

گزارش فروشنده

در مرحله گزارش فروشنده، مقدار buyerAndSellerReportingId برای reportResult() در دسترس قرار می گیرد:

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

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

قبل از اینکه شناسه در داخل reportResult() در دسترس قرار گیرد، از نظر k-ناشناس بودن با مالک گروه علاقه، URL اسکریپت پیشنهادی، URL رندر و اندازه تبلیغ بررسی می شود (اندازه آگهی حداقل تا سه ماهه اول 2025 از این بررسی مستثنی است). اگر k-anonymous نباشد، تابع reportResult() همچنان اجرا خواهد شد، اما مقدار شناسه گزارش در داخل تابع در دسترس نخواهد بود.

گزارش خریدار

در طول مرحله گزارش خریدار از حراج، یک شناسه گزارش برای reportWin() در دسترس قرار می گیرد. اگر بیش از یک شناسه گزارش در گروه ذینفع تعریف شده باشد، یک قانون رونویسی اعمال می‌شود که buyerAndSellerReportingId buyerReportingId بازنویسی می‌کند:

  • اگر buyerAndSellerReportingId و buyerReportingId هر دو تعریف شده باشند، buyerAndSellerReportingId buyerReportingId بازنویسی می کند و buyerAndSellerReportingId در داخل reportWin() موجود خواهد بود.
  • اگر فقط buyerReportingId تعریف شده باشد، buyerReportingId در دسترس خواهد بود.
  • اگر نه buyerAndSellerReportingId و نه buyerReportingId تعریف نشده باشند، interestGroupName در دسترس خواهد بود. 
function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

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

شناسه گزارشی که در داخل reportWin() موجود می‌شود، از نظر k-ناشناس بودن با مالک گروه علاقه‌مند، URL اسکریپت پیشنهادی، URL رندر و اندازه آگهی بررسی می‌شود (اندازه آگهی حداقل تا سه ماهه اول 2025 از این بررسی مستثنی است). اگر در بررسی k-anonymity ناموفق بود، reportWin() همچنان اجرا می‌شود، اما مقدار شناسه گزارش در داخل تابع موجود نخواهد بود.

فقط buyerReportingId تعریف شده است

اگر فقط buyerReportingId در پیکربندی گروه علاقه تعریف شده باشد:

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

سپس buyerReportingId در داخل reportWin() موجود است:

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

قبل از در دسترس قرار گرفتن برای reportWin() ، buyerReportingId از نظر k-ناشناس بودن با مالک گروه علاقه، URL اسکریپت پیشنهادی، URL رندر و اندازه تبلیغ بررسی می شود (اندازه آگهی حداقل تا سه ماهه اول 2025 از این بررسی مستثنی است).

فقط buyerAndSellerReportingId تعریف شده است

اگر فقط buyerAndSellerReportingId در پیکربندی گروه علاقه تعریف شده باشد:

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

سپس buyerAndSellerReportingId در داخل reportWin() موجود است:

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

قبل از در دسترس قرار گرفتن در reportWin() ، buyerAndSellerReportingId از نظر k-ناشناس بودن با مالک گروه علاقه مند، URL اسکریپت پیشنهادی، URL رندر و اندازه تبلیغ بررسی می شود (اندازه آگهی حداقل تا سه ماهه اول 2025 از این بررسی مستثنی است).

هر دو buyerAndSellerReportingId و buyerReportingId تعریف شده اند

اگر هر دو buyerAndSellerReportingId و buyerReportingId در پیکربندی گروه علاقه تعریف شده باشند:

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

سپس فقط buyerAndSellerReportingId در داخل reportWin() به دلیل رفتار رونویسی موجود است:

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

قبل از در دسترس قرار گرفتن در reportWin() ، buyerAndSellerReportingId از نظر k-ناشناس بودن با مالک گروه علاقه مند، URL اسکریپت پیشنهادی، URL رندر و اندازه تبلیغ بررسی می شود (اندازه آگهی حداقل تا سه ماهه اول 2025 از این بررسی مستثنی است).

نه buyerAndSellerReportingId و نه buyerReportingId تعریف نشده اند

اگر هیچ شناسه گزارشی در پیکربندی گروه علاقه تعریف نشده باشد: 

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

سپس name گروه ذینفع در داخل reportWin() موجود است: 

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

قبل از در دسترس قرار گرفتن برای reportWin() ، نام گروه علاقه ( interestGroupName ) از نظر k-ناشناس بودن با مالک گروه علاقه، URL اسکریپت پیشنهاد، URL رندر و اندازه تبلیغ بررسی می شود (اندازه آگهی حداقل تا سه ماهه اول 2025 از این بررسی مستثنی است. ).

شناسه های گزارش قابل انتخاب

شناسه های گزارش برای عملکردهای خریدار و فروشنده مخاطب محافظت شده در دسترس قرار می گیرد
در دسترس بودن شناسه گزارش با شناسه گزارش قابل انتخاب

شناسه‌های گزارش قابل انتخاب به خریدار اجازه می‌دهد تا در طول تولید پیشنهاد، یک شناسه را انتخاب کند و مرورگر مقدار انتخاب‌شده را در دسترس عملکردهای scoreAd() و گزارش قرار می‌دهد. مقدار selectableBuyerAndSellerReportingIds ، که آرایه‌ای از رشته‌ها است، برای generateBid() ارائه می‌شود، و خریدار می‌تواند یک شناسه انتخاب‌شده را به‌عنوان selectedBuyerAndSellerReportingId برگرداند.

توابع generateBid() و scoreAd() برای هر تبلیغ تعریف شده در پیکربندی گروه علاقه اجرا می شود و شناسه های گزارش برای هر تبلیغ را دریافت می کند. عملکردهای گزارش خریدار و فروشنده فقط برای آگهی برنده اجرا می شوند و توابع شناسه های گزارش تعریف شده برای آن آگهی برنده را دریافت خواهند کرد.

هنگامی که شناسه های گزارش غیر قابل انتخاب همراه با شناسه های گزارش قابل انتخاب استفاده می شوند، رفتار آنها نسبت به گردش کار توضیح داده شده در بخش قبل تغییر می کند. بر خلاف رفتار اولیه شناسه های گزارش غیر قابل انتخاب که فقط در داخل توابع گزارش در دسترس هستند، شناسه های گزارش قابل انتخاب، شناسه های گزارش غیر قابل انتخاب را قادر می سازند تا در داخل generateBid() و scoreAd() نیز در دسترس باشند.

گروه علاقه مندی

فیلد شناسه‌های گزارش قابل انتخاب - selectableBuyerAndSellerReportingIds - آرایه‌ای از رشته‌هایی است که توسط خریدار در گروه مورد علاقه برای یک آگهی تعریف شده است. شناسه های گزارش غیر قابل انتخاب نیز می توانند در کنار شناسه های گزارش قابل انتخاب تعریف شوند: 

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

تولید پیشنهاد خریدار

اگر selectableBuyerAndSellerReportingIds در پیکربندی گروه علاقه تعریف شده باشد، در داخل generateBid() به همراه سایر شناسه های گزارشی تعریف شده در دسترس می شود. 

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

خریدار می‌تواند یکی از شناسه‌ها را از آرایه selectableBuyerAndSellerReportingIds در generateBid() انتخاب کند و شناسه انتخابی را به عنوان selectedBuyerAndSellerReportingId برگرداند. اگر مقدار انتخاب شده در آرایه selectableBuyerAndSellerReportingIds نباشد، پیشنهاد رد می شود. اگر selectableBuyerAndSellerReportingIds در پیکربندی گروه علاقه تعریف شده باشد، و خریدار selectedBuyerAndSellerReportingId از generateBid() برنگرداند، شناسه های گزارش به رفتار توصیف شده برای شناسه های گزارش غیر قابل انتخاب برمی گردند.

پیشنهادی با مقدار برگشتی برای selectedbuyerAndSellerReportingId تنها در صورتی برنده حراج خواهد شد که ارزش selectedbuyerAndSellerReportingId به طور مشترک k-ناشناس همراه با buyerAndSellerReportingId (در صورت وجود)، buyerReportingId (در صورت وجود)، مالک گروه علاقه مند، URL اسکریپت پیشنهاد، URL رندر، اندازه آگهی (اندازه آگهی حداقل تا سه ماهه اول 2025 از این بررسی مستثنی است).

امتیاز آگهی فروشنده

برای فروشنده، selectedBuyerAndSellerReportingId BuyerAndSellerReportingId که توسط خریدار از generateBid() برگردانده شده بود، در scoreAd() همراه با buyerAndSellerReportingId در صورتی که در پیکربندی گروه علاقه تعریف شده باشد، در دسترس قرار می گیرد. 

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

  // ...
}

گزارش فروشنده

برای گزارش فروشنده، selectedBuyerAndSellerReportingId BuyerAndSellerReportingId که توسط خریدار از generateBid() برگردانده شده است، در reportResult() به همراه buyerAndSellerReportingId در دسترس می شود، اگر در گروه علاقه تعریف شده باشد. 

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

اگر selectableBuyerAndSellerReportingIds در پیکربندی گروه علاقه تعریف شده باشد، و selectedBuyerAndSellerReportingId از generateBid() برگردانده شده باشد، نمی تواند در حراج برنده شود مگر اینکه selectedBuyerAndSellerReportingId و buyerAndSellerReportingId (در صورت وجود) k-اسکریپت، مالک اسکریپت، نشانی اینترنتی علاقه مندرج مجدد باشند. و اندازه آگهی (اندازه آگهی حداقل تا سه ماهه اول 2025 از این بررسی مستثنی است) و reportResult() برای آن پیشنهاد اجرا نخواهد شد. بنابراین، اگر reportResult() با یک مقدار برای selectedBuyerAndSellerReportingId فراخوانی شود، به این معنی است که شناسه های گزارش از بررسی k-anonymity عبور کرده اند و همه شناسه های گزارش تعریف شده در داخل reportResult() موجود خواهند بود.

گزارش خریدار

اگر selectableBuyerAndSellerReportingIds در پیکربندی گروه علاقه تعریف شده بود، و selectedBuyerAndSellerReportingId از generateBid() برگردانده شد، آنگاه همه شناسه های گزارشی که در پیکربندی گروه علاقه تعریف شده بودند در دسترس خواهند بود. توجه داشته باشید که مشابه گزارش فروشنده، اگر شناسه‌های گزارش‌دهی k-ناشناس نباشند، نمی‌توانند در حراج برنده شوند و reportWin() برای آن پیشنهاد اجرا نمی‌شود. 

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

  // ...
}

بازنویسی قوانین

در اینجا قوانین رونویسی را برای شناسه‌های گزارش غیرقابل انتخاب و شناسه‌های گزارش قابل انتخاب خلاصه می‌کنیم. کدام یک از selectableBuyerAndSellerReportingIds ، buyerAndSellerReportingId ، buyerReportingId ، و نام گروه علاقه به reportWin() منتقل می شود توسط مرورگر با منطق زیر تعیین می شود:

  • اگر selectedBuyerAndSellerReportingId از یک پیشنهاد بازگردانده شود، selectedBuyerAndSellerReportingId ، buyerAndSellerReportingId (اگر در گروه علاقه تعریف شده باشد)، و buyerReportingId (اگر در گروه علاقه تعریف شده باشد) همگی برای گزارش در دسترس هستند.
  • در غیر این صورت، اگر buyerAndSellerReportingId در گروه علاقه تعریف شده باشد، فقط buyerAndSellerReportingId برای گزارش در دسترس است.
  • در غیر این صورت، اگر buyerReportingId در گروه علاقه تعریف شده باشد، فقط buyerReportingId برای گزارش در دسترس است.
  • در غیر این صورت، فقط name گروه ذینفع برای گزارش در دسترس است.

جدول زیر رفتار رونویسی را توضیح می دهد:

آیا شناسه های گزارش در پیکربندی گروه علاقه تعریف شده اند؟ شناسه های گزارش در دسترس است
selectableBuyerAnd
SellerReportingIds		 buyerAndSeller
ReportingId		 buyerReportingId reportWin() reportResult()
بله ، و انتخاب شده است
در generateBid()		 اختیاری اختیاری 1) selectableBuyerAnd
SellerReportingIds

2) buyerAndSeller
ReportingId (در صورت تعریف)

3) buyerReportingId (در صورت تعریف)		 1) selectableBuyerAnd
SellerReportingIds

2) buyerAndSeller
ReportingId (در صورت تعریف)

نه، یا انتخاب نشده است
در generateBid()		 بله نادیده گرفته شد buyerAndSeller
ReportingId		 buyerAndSeller
ReportingId
نه، یا انتخاب نشده است
در generateBid()		 خیر بله buyerReportingId هیچ کدام
نه، یا انتخاب نشده است
در generateBid()		 خیر خیر interestGroupName هیچ کدام

مشارکت کنید و بازخورد را به اشتراک بگذارید