نمای کلی API Aggregation خصوصی

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

برای ارائه ویژگی‌های حیاتی که وب به آن‌ها متکی است، API جمع‌آوری خصوصی برای جمع‌آوری و گزارش‌دهی داده‌های بین‌سایتی به شیوه‌ای حفظ حریم خصوصی ساخته شده است.

وضعیت پیاده سازی

پیشنهاد وضعیت
با تأیید گزارش برای فضای ذخیره‌سازی مشترک، از گزارش‌های نامعتبر Private Aggregation API جلوگیری کنید
توضیح دهنده		 در کروم موجود است
در دسترس بودن حالت اشکال زدایی تجمع خصوصی به واجد شرایط بودن 3PC بستگی دارد
مشکل GitHub		 در کروم M119 موجود است
کاهش تأخیر گزارش
توضیح دهنده		 در کروم M119 موجود است
پایان زمان مشارکت خصوصی تجمع برای فضای ذخیره‌سازی مشترک
توضیح دهنده		 موجود در M119
پشتیبانی از Private Aggregation API و Aggregation Service برای Google Cloud
توضیح دهنده		 موجود در کروم M121
بالشتک برای بارهای گزارش انباشته
توضیح دهنده		 در کروم M119 موجود است
حالت اشکال زدایی تجمع خصوصی برای گزارش auctionReportBuyers در دسترس است
توضیح دهنده		 در کروم M123 موجود است
پشتیبانی از فیلتر کردن شناسه
توضیح دهنده		 در کروم M128 موجود است
ادغام مشارکت سمت مشتری
توضیح دهنده		 در کروم M129 موجود است
محدودیت مشارکت در هر زمینه
توضیح دهنده		 در سه ماهه اول 2025 مورد انتظار است
بودجه های نام برده شده
توضیح دهنده		 در سه ماهه اول 2025 مورد انتظار است
گزارش خطای انبوه
توضیح دهنده		 مورد انتظار در سه ماهه اول 2025

Private Aggregation API چیست؟

Private Aggregation API به توسعه‌دهندگان اجازه می‌دهد تا گزارش‌های داده انبوه را با داده‌های API مخاطب محافظت‌شده و داده‌های بین‌سایتی از فضای ذخیره‌سازی مشترک تولید کنند.

تابع اصلی این API با نام contributeToHistogram() شناخته می شود. عملیات هیستوگرام به شما امکان می دهد داده ها را در بین کاربران در هر سطل (که در API به عنوان یک کلید تجمع شناخته می شود) که تعریف می کنید جمع آوری کنید. تماس هیستوگرام شما مقادیر را جمع می کند و یک نتیجه انبوه نویزدار را در قالب یک گزارش خلاصه برمی گرداند. به عنوان مثال، این گزارش ممکن است تعداد سایت‌هایی را که هر کاربر محتوای شما را در آن‌ها دیده است نشان دهد، یا با اشکالی در اسکریپت شخص ثالث شما مواجه شود. این عملیات در worklet یک API دیگر انجام می شود.

به عنوان مثال، اگر قبلاً داده‌های جمعیتی و جغرافیایی را در فضای ذخیره‌سازی مشترک ثبت کرده‌اید، می‌توانید از API جمع‌آوری خصوصی برای ایجاد یک هیستوگرام استفاده کنید که به شما می‌گوید تقریباً چند کاربر در شهر نیویورک محتوای شما را بین سایت دیده‌اند. برای جمع‌آوری این اندازه‌گیری، می‌توانید بعد جغرافیایی را در کلید تجمیع کدگذاری کنید و کاربران را در مقدار قابل جمع‌آوری شمارش کنید.

مفاهیم کلیدی

هنگامی که شما با یک کلید تجمیع و یک مقدار قابل تجمیع، Private Aggregation API را فراخوانی می کنید، مرورگر یک گزارش جمع آوری ایجاد می کند.

گزارش های جمع آوری شده برای جمع آوری و دسته بندی به سرور شما ارسال می شود. گزارش‌های دسته‌ای بعداً توسط سرویس جمع‌آوری پردازش می‌شوند و یک گزارش خلاصه ایجاد می‌شود.

برای کسب اطلاعات بیشتر در مورد مفاهیم کلیدی مرتبط با Private Aggregation API به سند اصول API Aggregation Private مراجعه کنید.

تفاوت با گزارش اسناد

Private Aggregation API شباهت های زیادی با Attribution Reporting API دارد. Attribution Reporting یک API مستقل است که برای اندازه‌گیری تبدیل‌ها طراحی شده است، در حالی که Private Aggregation برای اندازه‌گیری‌های بین سایتی در ارتباط با APIهایی مانند Protected Audience API و ذخیره‌سازی مشترک ساخته شده است. هر دو API گزارش‌های انباشته‌ای را تولید می‌کنند که توسط Back-end Service Aggregation برای تولید گزارش‌های خلاصه مصرف می‌شوند.

Attribution Reporting داده‌های مرتبط را از یک رویداد نمایش و یک رویداد تبدیل جمع‌آوری می‌کند که در زمان‌های مختلف اتفاق می‌افتد. Private Aggregation یک رویداد تک سایتی را اندازه گیری می کند.

این API را تست کنید

برای آزمایش API تجمیع خصوصی به صورت محلی، همه APIهای حریم خصوصی آگهی را در chrome://settings/adPrivacy فعال کنید.

درباره آزمایش در آزمایش بیشتر بخوانید و شرکت کنید .

از دمو استفاده کنید

نسخه ی نمایشی Private Aggregation API برای ذخیره سازی مشترک را می توان در goo.gle/shared-storage-demo مشاهده کرد و کد در GitHub در دسترس است. نسخه ی نمایشی عملیات سمت کلاینت را پیاده سازی می کند و یک گزارش جمع آوری ایجاد می کند که به سرور شما ارسال می شود.

نسخه نمایشی Private Aggregation API برای Protected Audience API در آینده منتشر خواهد شد.

موارد استفاده کنید

Private Aggregation یک API همه منظوره برای اندازه‌گیری بین سایتی است و برای استفاده در Worklet‌های API ذخیره‌سازی مشترک و مخاطبین محافظت‌شده در دسترس است. اولین قدم این است که تصمیم بگیرید به طور خاص چه اطلاعاتی را می خواهید جمع آوری کنید. این نقاط داده اساس کلیدهای تجمیع شما هستند.

با فضای ذخیره سازی مشترک

ذخیره‌سازی مشترک به شما امکان می‌دهد داده‌های بین سایتی را در یک محیط امن بخوانید و بنویسید تا از نشت جلوگیری کنید، و Private Aggregation API به شما امکان می‌دهد داده‌های بین سایتی ذخیره شده در ذخیره‌سازی مشترک را اندازه‌گیری کنید.

اندازه گیری دسترسی منحصر به فرد

ممکن است بخواهید اندازه گیری کنید که چند کاربر منحصر به فرد محتوای آنها را دیده اند. Private Aggregation API می تواند پاسخی مانند "تقریباً 317 کاربر منحصر به فرد Content ID 861 را دیده اند."

می‌توانید یک پرچم در فضای ذخیره‌سازی مشترک تنظیم کنید تا مشخص کند کاربر قبلاً محتوا را دیده است یا خیر. در اولین بازدید از جایی که پرچم وجود ندارد، یک تماس با Private Aggregation گرفته می شود و سپس پرچم تنظیم می شود. در بازدیدهای بعدی کاربر، از جمله بازدیدهای بین سایتی، می‌توانید فضای ذخیره‌سازی مشترک را بررسی کنید و در صورت تنظیم پرچم، از ارسال گزارش به Private Aggregation صرفنظر کنید. برای کسب اطلاعات بیشتر در مورد روش‌های اجرای این اندازه‌گیری‌ها، کاغذ سفید دسترسی ما را بررسی کنید.

اندازه گیری جمعیت شناسی

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

Private Aggregation می تواند پاسخی مانند "تقریباً 317 کاربر منحصر به فرد از سن 18 تا 45 سال و اهل آلمان" ارائه دهد. از فضای ذخیره‌سازی مشترک برای دسترسی به داده‌های جمعیتی از یک زمینه شخص ثالث استفاده کنید. در زمان بعدی، می‌توانید با رمزگذاری ابعاد گروه سنی و کشور در کلید تجمیع، گزارشی با تجمیع خصوصی ایجاد کنید.

اندازه گیری فرکانس K+

ممکن است بخواهید تعداد کاربرانی را که یک محتوا یا یک تبلیغ را حداقل K بار در یک مرورگر مشخص دیده‌اند، با مقدار K از پیش انتخاب شده اندازه‌گیری کنید.

Private Aggregation می تواند پاسخی مانند "تقریباً 89 کاربر حداقل 3 بار Content ID 581 را دیده اند" ارائه دهد. یک شمارنده را می توان در فضای ذخیره سازی مشترک از سایت های مختلف افزایش داد و در یک Worklet قابل خواندن است. وقتی تعداد به K رسید، می توان گزارشی از طریق Private Aggregation ارسال کرد.

انتساب چند لمسی

این راهنما قرار است در سایت توسعه دهنده منتشر شود تا کارشناسان تبلیغات بتوانند نحوه اجرای MTA را در فضای ذخیره‌سازی مشترک + جمع‌آوری خصوصی درک کنند.

با API مخاطب محافظت شده

Protected Audience API امکان هدف‌یابی مجدد و موارد استفاده سفارشی از مخاطب را فراهم می‌کند و Private Aggregation به شما امکان می‌دهد رویدادها را از مجموعه‌های کاری خریدار و فروشنده گزارش دهید. API را می توان برای کارهایی مانند اندازه گیری توزیع پیشنهادات مزایده استفاده کرد.

از یک Worklet Protected Audience API، می‌توانید داده‌های خود را مستقیماً با استفاده از contributeToHistogram() جمع‌آوری کنید و داده‌های خود را بر اساس یک راه‌انداز با استفاده از contributeToHistogramOnEvent() ، که یک برنامه افزودنی ویژه برای API مخاطب محافظت‌شده است، گزارش دهید.

توابع موجود

توابع زیر در شیء privateAggregation موجود در Workletهای API اشتراک‌گذاری شده و مخاطبین محافظت‌شده موجود است.

shareToHistogram()

می‌توانید privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }) را فراخوانی کنید، که در آن کلید تجمع bucket و مقدار قابل جمع‌آوری به عنوان value است. برای پارامتر bucket ، یک BigInt مورد نیاز است. برای پارامتر value ، یک عدد صحیح مورد نیاز است.

در اینجا مثالی از نحوه فراخوانی آن در فضای ذخیره‌سازی مشترک برای اندازه‌گیری دسترسی آورده شده است:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', { 
  data: { contentId: '1234' } 
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){ 
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling" 
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await sharedStorage.get(key) === 'true';

    // Do not send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId), 
      value: 1 * SCALE_FACTOR 
    });

    // Set the flag in Shared Storage
    await sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

هر زمان که محتوای iframe بین سایتی بارگیری شود، مثال کد بالا، Private Aggregation را فراخوانی می کند. کد iframe worklet را بارگیری می‌کند، و Worklet API جمع‌آوری خصوصی را با شناسه محتوا به یک کلید تجمع (سطل) فراخوانی می‌کند.

shareToHistogramOnEvent()

فقط در Worklet‌های Protected Audience API، ما مکانیزمی مبتنی بر محرک برای ارسال گزارش تنها در صورت وقوع رویداد خاصی ارائه می‌کنیم. این تابع همچنین اجازه می دهد تا سطل و مقدار به سیگنال هایی بستگی داشته باشد که هنوز در آن نقطه از حراج در دسترس نیستند.

متد privateAggregation.contributeToHistogramOnEvent(eventType, contribution) یک eventType می گیرد که رویداد آغازگر را مشخص می کند و contribution که باید هنگام راه اندازی رویداد ارسال شود. رویداد راه‌اندازی می‌تواند از خود حراج پس از پایان حراج، مانند یک رویداد برد یا باخت حراج باشد، یا می‌تواند از یک قاب محصور شده باشد که آگهی را ارائه کرده است. برای ارسال گزارش رویدادهای حراج، می‌توانید از دو کلمه کلیدی رزرو شده reserved.win ، reserved.loss و reserved.always استفاده کنید. برای ارسال گزارشی که توسط یک رویداد از یک قاب حصاردار ایجاد شده است، یک نوع رویداد سفارشی تعریف کنید. برای راه‌اندازی رویداد از یک قاب حصاردار، از روش fence.reportEvent() موجود در Fenced Frames Ads Reporting API استفاده کنید.

مثال زیر زمانی که رویداد برنده حراج راه اندازی می شود، یک گزارش نمایش ارسال می کند، و اگر رویداد click از قاب محصور شده ای که تبلیغ را ارائه می دهد، ایجاد شود، گزارش کلیک ارسال می کند. از این دو مقدار می توان برای محاسبه نرخ کلیک استفاده کرد.

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

برای کسب اطلاعات بیشتر به توضیح گزارش‌دهی تجمیع خصوصی گسترده مراجعه کنید.

enableDebugMode()

در حالی که کوکی‌های شخص ثالث هنوز در دسترس هستند، مکانیسم موقتی ارائه می‌کنیم که با فعال کردن حالت اشکال‌زدایی، اشکال‌زدایی و آزمایش آسان‌تر را ممکن می‌سازد. گزارش اشکال‌زدایی در مقایسه اندازه‌گیری‌های مبتنی بر کوکی‌ها با اندازه‌گیری‌های تجمیع خصوصی مفید است و همچنین به شما امکان می‌دهد تا به سرعت یکپارچه‌سازی API خود را تأیید کنید.

فراخوانی privateAggregation.enableDebugMode() در Worklet حالت اشکال‌زدایی را فعال می‌کند که باعث می‌شود گزارش‌های جمع‌آوری‌شده شامل محموله رمزگذاری نشده (متن شفاف) شود. سپس می‌توانید این محموله‌ها را با ابزار آزمایش محلی Aggregation Service پردازش کنید.

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

همچنین می‌توانید کلید اشکال‌زدایی را با فراخوانی privateAggregation.enableDebugMode({ <debugKey: debugKey> }) تنظیم کنید که در آن BigInt می‌تواند به عنوان کلید اشکال‌زدایی استفاده شود. کلید اشکال زدایی را می توان برای مرتبط کردن داده ها از اندازه گیری مبتنی بر کوکی و داده های اندازه گیری جمع آوری خصوصی استفاده کرد.

اینها را می توان تنها یک بار در هر زمینه فراخوانی کرد. هر تماس بعدی یک استثنا ایجاد می کند. 

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

تایید را گزارش کنید

برای فضای ذخیره‌سازی مشترک، می‌توانید با افزودن شناسه زمینه به تماس عملیات ذخیره‌سازی مشترک، تأیید کنید که گزارش‌های انبوهی که دریافت کرده‌اید قانونی هستند. شناسه به گزارش ارسال شده ضمیمه می‌شود و در فرصتی دیگر، می‌توانید از آن شناسه برای تأیید اینکه گزارش از عملیات ذخیره‌سازی مشترک شما ارسال شده است استفاده کنید.

برای کسب اطلاعات بیشتر، به توضیح تأیید گزارش مراجعه کنید.

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

Private Aggregation API تحت بحث فعال است و ممکن است در آینده تغییر کند. اگر این API را امتحان کردید و بازخورد دارید، مایلیم آن را بشنویم.