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

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

نمای کلی

شناسه‌های گزارش‌دهی، شناسه‌های مرتبط با یک تبلیغ هستند که برای استفاده در ایجاد پیشنهاد، امتیازدهی به پیشنهاد و گزارش‌دهی در دسترس هستند. شناسه‌های گزارش‌دهی توسط خریدار در پیکربندی گروه علاقه‌مند ارائه می‌شوند و تحت شرایط مختلفی که در این راهنما مورد بحث قرار گرفته‌اند، در 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-anonymity با مالک گروه ذینفع، URL اسکریپت پیشنهاد دهنده، URL رندر و اندازه تبلیغ بررسی می‌شود (اندازه تبلیغ حداقل تا سه‌ماهه اول سال 2025 از این بررسی مستثنی است). اگر k-anonymous نباشد، تابع reportResult() همچنان اجرا خواهد شد، اما مقدار شناسه گزارش‌دهی درون تابع در دسترس نخواهد بود.

گزارش خریدار

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

  • اگر هر دو buyerReportingId buyerAndSellerReportingId تعریف شده باشند، در این صورت متغیر 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-anonymity با مالک گروه ذینفع، 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-anonymity با مالک گروه ذینفع، 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-anonymity با مالک گروه ذینفع، 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;
}

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

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

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

شناسه‌های گزارش‌دهی قابل انتخاب به خریدار اجازه می‌دهند تا در طول تولید پیشنهاد، یک شناسه انتخاب کند و مرورگر مقدار انتخاب‌شده را در دسترس تابع 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 به همراه buyerAndSellerReportingId (در صورت وجود)، buyerReportingId (در صورت وجود)، مالک گروه ذینفع، URL اسکریپت پیشنهاد، URL رندر و اندازه تبلیغ (اندازه تبلیغ حداقل تا سه‌ماهه اول ۲۰۲۵ از این بررسی مستثنی است) به طور مشترک k-anonymous باشد.

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

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

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

  // ...
}

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

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

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

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

گزارش خریدار

اگر selectableBuyerAndSellerReportingIds در پیکربندی گروه علاقه‌مندی تعریف شده باشد، و selectedBuyerAndSellerReportingId از generateBid() برگردانده شده باشد، تمام شناسه‌های گزارش‌دهی که در پیکربندی گروه علاقه‌مندی تعریف شده‌اند، در دسترس قرار می‌گیرند. توجه داشته باشید که مشابه گزارش‌دهی فروشنده، اگر شناسه‌های گزارش‌دهی k-anonymous نباشند، نمی‌توانند در حراج برنده شوند و 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()		 اختیاری اختیاری ۱) selectedBuyerAnd
SellerReportingIds

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

۳) buyerReportingId (در صورت تعریف)		 ۱) selectedBuyerAnd
SellerReportingIds

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

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

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