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

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

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

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

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

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 گزارش‌های انبوهی را تولید می‌کنند که توسط Backend 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 رسید، می توان گزارشی را با استفاده از تجمیع خصوصی ارسال کرد.

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

این راهنما قرار است در سایت توسعه دهنده منتشر شود تا کارشناسان تبلیغات بتوانند نحوه اجرای 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';

    // Don't 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()

در حالی که کوکی‌های شخص ثالث هنوز در دسترس هستند، مکانیسم موقتی ارائه می‌کنیم که با فعال کردن حالت اشکال‌زدایی، اشکال‌زدایی و آزمایش آسان‌تر را ممکن می‌سازد. گزارش اشکال‌زدایی در مقایسه اندازه‌گیری‌های مبتنی بر کوکی با اندازه‌گیری‌های Private Aggregation مفید است و همچنین به شما امکان می‌دهد به سرعت یکپارچه‌سازی 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 معتبر و معتبر تولید می‌شوند، که ساخت گزارش را برای بازیگران بد مشکل می‌کند.
  • جلوگیری از پخش مجدد گزارش: هر گونه تلاش برای استفاده مجدد از گزارش های قدیمی را شناسایی و رد کنید، و اطمینان حاصل کنید که هر گزارش فقط یک بار به نتایج کلی کمک می کند.

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

هنگام استفاده از ذخیره‌سازی مشترک برای اجرای عملیاتی که می‌تواند یک گزارش جمع‌آوری ارسال کند، می‌توانید یک شناسه غیرقابل پیش‌بینی در خارج از Worklet تنظیم کنید.

این شناسه در گزارش ایجاد شده از Worklet تعبیه شده است. می‌توانید آن را هنگام فراخوانی روش‌های ذخیره‌سازی مشترک run() یا selectURL() در شی گزینه‌های زیر کلید privateAggregationConfig مشخص کنید.

به عنوان مثال:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

پس از تنظیم این شناسه، می توانید از آن برای تأیید اینکه گزارش از عملیات ذخیره سازی مشترک شما ارسال شده است استفاده کنید. برای جلوگیری از نشت اطلاعات، بدون در نظر گرفتن تعداد فراخوانی های contributeToHistogram() ، دقیقاً یک گزارش برای هر عملیات ذخیره سازی مشترک ارسال می شود (حتی اگر هیچ مشارکتی انجام نشود).

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

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

یک نمونه گردش کار (همانطور که در نمودار بالا نشان داده شده است):

  1. عملیات ذخیره‌سازی مشترک با پیکربندی Private Aggregation اجرا می‌شود که شناسه زمینه را مشخص می‌کند و یک گزارش جمع‌آوری ایجاد می‌شود.
  2. شناسه زمینه در گزارش انبوه ایجاد شده ارسال شده به سرور شما تعبیه شده است.
  3. سرور شما گزارش های جمع آوری شده تولید شده را جمع آوری می کند.
  4. فرآیندهای روی سرور شما، شناسه زمینه در هر گزارش جمع‌آوری‌شده را در برابر شناسه‌های زمینه ذخیره‌شده‌تان بررسی می‌کنند تا از اعتبار آن قبل از دسته‌بندی گزارش‌ها و ارسال آن‌ها به سرویس تجمع شما اطمینان حاصل کنند.

تأیید هویت زمینه

گزارش‌های دریافتی به سرور جمع‌آوری کننده شما را می‌توان به چند روش مختلف قبل از ارسال به سرویس تجمع تأیید کرد. وقتی شناسه زمینه:

  • ناشناخته: اگر گزارشی با شناسه زمینه ای که سیستم شما ایجاد نکرده است به دست می آید، می توانید آن را رد کنید. این کار مانع از تزریق اطلاعات توسط بازیگران ناشناس یا مخرب به خط لوله جمع آوری شما می شود.
  • یک تکراری: اگر دو (یا بیشتر) گزارش با شناسه زمینه یکسان دریافت می‌کنید، به این معنی است که باید انتخاب کنید کدام یک از گزارش‌ها را رد کنید.
  • پرچم گذاری شده در تشخیص هرزنامه:
    • اگر هنگام پردازش گزارش کاربر، فعالیت مشکوکی را از سوی کاربر شناسایی کردید، به عنوان مثال تغییر ناگهانی در فعالیت کاربر، می توانید آن را رد کنید.
    • می‌توانید گزارش‌ها را در کنار شناسه‌های زمینه و هر سیگنال مرتبط (به عنوان مثال، عامل کاربر، منبع ارجاع و غیره) ذخیره کنید. بعداً، همانطور که رفتار کاربر را تجزیه و تحلیل می‌کنید و شاخص‌های هرزنامه جدید را شناسایی می‌کنید، می‌توانید گزارش‌های ذخیره‌شده را بر اساس شناسه‌ها و سیگنال‌های زمینه مرتبط آن‌ها دوباره ارزیابی کنید. این به شما امکان می‌دهد گزارش‌های کاربرانی که فعالیت‌های مشکوک را نشان می‌دهند صرف‌نظر کنید، حتی اگر در ابتدا پرچم‌گذاری نشده باشند.

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

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