اصول API جمع آوری خصوصی

مفاهیم کلیدی Private Aggregation API

این سند برای چه کسی است؟

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

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

اصطلاحات کلیدی

قبل از خواندن این سند، آشنا شدن با اصطلاحات و مفاهیم کلیدی مفید خواهد بود. هر یک از این اصطلاحات در اینجا به طور کامل توضیح داده خواهد شد.

• یک کلید تجمع (همچنین به عنوان سطل شناخته می شود) مجموعه ای از پیش تعیین شده از نقاط داده است. به عنوان مثال، ممکن است بخواهید یک سطل از داده های مکان جمع آوری کنید که در آن مرورگر نام کشور را گزارش می کند. یک کلید تجمع ممکن است حاوی بیش از یک بعد باشد (به عنوان مثال، کشور و شناسه ویجت محتوای شما).
• یک مقدار تجمیع‌پذیر یک نقطه داده فردی است که در یک کلید تجمیع جمع‌آوری می‌شود. اگر می خواهید اندازه گیری کنید که چند کاربر از فرانسه محتوای شما را دیده اند، France یک بعد در کلید تجمع است و تعداد viewCount 1 مقدار قابل جمع آوری است.
• گزارش های جمع آوری شده در یک مرورگر تولید و رمزگذاری می شوند. برای Private Aggregation API، این شامل داده‌هایی درباره یک رویداد است.
• سرویس جمع‌آوری داده‌های گزارش‌های جمع‌آوری‌شده را برای ایجاد یک گزارش خلاصه پردازش می‌کند.
• گزارش خلاصه خروجی نهایی سرویس تجمیع است و حاوی داده‌های جمع‌آوری‌شده کاربر و داده‌های تبدیل دقیق است.
• Worklet بخشی از زیرساخت است که به شما امکان می دهد توابع خاص جاوا اسکریپت را اجرا کنید و اطلاعات را به درخواست کننده بازگردانید. در یک Worklet، می‌توانید جاوا اسکریپت را اجرا کنید، اما نمی‌توانید با صفحه بیرونی تعامل یا ارتباط برقرار کنید.

گردش کار جمع آوری خصوصی

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

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

اصطلاح کلیدی: محیط اجرای قابل اعتماد پیکربندی خاصی از سخت افزار و نرم افزار رایانه است که به طرف های خارجی اجازه می دهد تا نسخه های دقیق نرم افزار در حال اجرا بر روی رایانه را تأیید کنند. TEE ها به طرف های خارجی اجازه می دهند تا تأیید کنند که نرم افزار دقیقاً همان کاری را که سازنده نرم افزار ادعا می کند انجام می دهد - نه بیشتر یا کمتر.

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

کلید تجمع

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

برای مثال، ممکن است ویجتی داشته باشید که در چندین سایت تعبیه شده است و بخواهید کشور کاربرانی را که ویجت شما را دیده اند، تجزیه و تحلیل کنید. شما به دنبال پاسخ به سوالاتی مانند "چند نفر از کاربرانی که ویجت من را دیده اند از کشور X هستند؟" برای گزارش در مورد این سوال، می توانید یک کلید تجمیع تنظیم کنید که دو بعد را رمزگذاری می کند: شناسه ویجت و شناسه کشور.

کلید ارائه شده به Private Aggregation API یک BigInt است که از چند بعد تشکیل شده است. در این مثال، ابعاد شناسه ویجت و شناسه کشور است. بیایید بگوییم که شناسه ویجت می تواند تا 4 رقم مانند 1234 باشد و هر کشور به ترتیب حروف الفبا به یک عدد نگاشت می شود مانند افغانستان 1 ، فرانسه 61 و زیمبابوه 195 . بنابراین، کلید قابل جمع 7 رقم خواهد بود، که در آن 4 کاراکتر اول برای WidgetID و 3 کاراکتر آخر برای CountryID رزرو شده است.

فرض کنید کلید تعداد کاربرانی از فرانسه (شناسه کشور 061 ) را نشان می دهد که شناسه ویجت 3276 را دیده اند، کلید تجمع 3276061 است.

کلید تجمع
شناسه ویجت	شناسه کشور
3276	061

مثال: اگر یک بعد دارای فضای کلیدی برای چند رقم است، اما مقدار آن کمتر است، صفرهای ابتدایی را اضافه کنید. به عنوان مثال، اگر شناسه کشور اجازه 3 رقم را بدهد، شناسه کشور برای الجزایر 003 است.

کلید تجمیع را می توان با مکانیزم هش مانند SHA-256 نیز تولید کرد. برای مثال، رشته {"WidgetId":3276,"CountryID":67} می توان هش کرد و سپس به مقدار BigInt 42943797454801331377966796057547478208888578253058197330928948081739249096287n تبدیل کرد. 7n اگر مقدار هش بیش از 128 بیت باشد، می توانید آن را کوتاه کنید تا مطمئن شوید که از حداکثر مقدار مجاز سطل 2^128−1 تجاوز نمی کند.

در یک Worklet Shared Storage، می‌توانید به ماژول‌های crypto و TextEncoder دسترسی داشته باشید که می‌توانند به شما در ایجاد هش کمک کنند. برای کسب اطلاعات بیشتر در مورد ایجاد هش، SubtleCrypto.digest() در MDN بررسی کنید.

مثال زیر توضیح می دهد که چگونه می توانید یک کلید سطلی از یک مقدار هش شده تولید کنید:

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

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

ارزش تجمیع پذیر

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

اکنون، به مثال سوال مطرح شده قبلی برگردید: "چند نفر از کاربرانی که ویجت من را دیده اند اهل فرانسه هستند؟" پاسخ به این سوال چیزی شبیه به "تقریباً 4881 کاربر که شناسه ویجت 3276 من را دیده اند از فرانسه هستند." مقدار قابل جمع برای هر کاربر 1 است و "4881 کاربر" مقدار تجمیع شده ای است که مجموع همه مقادیر قابل جمع برای آن کلید تجمع است.

کلید تجمع		ارزش تجمیع پذیر
شناسه ویجت	شناسه کشور	تعداد مشاهده
3276	061	1

برای این مثال، برای هر کاربری که ویجت را می بیند، مقدار را 1 افزایش می دهیم. در عمل، مقدار تجمیع‌پذیر را می‌توان برای بهبود نسبت سیگنال به نویز مقیاس‌بندی کرد.

بودجه مشارکت

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

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

بودجه مشارکت با پارامتر L ₁ نشان داده می شود و به 2 ¹⁶ (65,536) در هر ده دقیقه در روز با بک استاپ 2 ²⁰ (1,048,576) تنظیم می شود. برای آشنایی بیشتر با این پارامترها به توضیح دهنده مراجعه کنید.

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

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

محدودیت مشارکت در هر گزارش

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

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

مشارکت با بالشتک

مشارکت ها با ویژگی padding بیشتر اصلاح می شوند. عمل پر کردن محموله اطلاعات مربوط به تعداد واقعی مشارکت‌های موجود در گزارش جمع‌آوری شده را محافظت می‌کند. بالشتک، بار محموله را با مشارکت های null (یعنی با مقدار 0) افزایش می دهد تا به طول ثابتی برسد.

گزارش های جمع آوری

هنگامی که کاربر API جمع‌آوری خصوصی را فراخوانی می‌کند، مرورگر گزارش‌های جمع‌آوری‌شده را تولید می‌کند تا در زمان بعدی توسط سرویس تجمع پردازش شود تا گزارش‌های خلاصه تولید شود. یک گزارش جمع‌آوری شده با قالب JSON است و حاوی فهرستی رمزگذاری‌شده از مشارکت‌ها است که هر کدام یک جفت {aggregation key, aggregatable value} هستند. گزارش های جمع آوری شده با تاخیر تصادفی تا یک ساعت ارسال می شود.

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

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

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

گزارش‌های جمع‌آوری‌شده را می‌توان از صفحه chrome://private-aggregation-internals بررسی کرد:

برای اهداف آزمایشی، می توان از دکمه "ارسال گزارش های انتخابی" برای ارسال گزارش بلافاصله به سرور استفاده کرد.

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

مرورگر گزارش‌های جمع‌آوری‌شده را با استفاده از مسیر شناخته شده فهرست‌شده به مبدأ Worklet ارسال می‌کند که حاوی تماس با Private Aggregation API است:

• برای ذخیره سازی مشترک: /.well-known/private-aggregation/report-shared-storage
• برای مخاطبان محافظت شده: /.well-known/private-aggregation/report-protected-audience

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

سپس سرور باید گزارش‌های دسته‌ای را انجام دهد و دسته را به سرویس تجمع ارسال کند. دسته‌هایی را براساس اطلاعات موجود در محموله رمزگذاری‌نشده گزارش جمع‌آوری‌شده، مانند قسمت shared_info ، ایجاد کنید. در حالت ایده آل، دسته ها باید شامل 100 یا بیشتر گزارش در هر دسته باشند.

ممکن است تصمیم بگیرید که به صورت روزانه یا هفتگی بچینگ کنید. این استراتژی انعطاف‌پذیر است و می‌توانید استراتژی دسته‌بندی خود را برای رویدادهای خاصی که انتظار حجم بیشتری را دارید تغییر دهید - به عنوان مثال، روزهایی از سال که انتظار می‌رود نمایش‌های بیشتری وجود داشته باشد. دسته ها باید شامل گزارش هایی از همان نسخه API، مبدأ گزارش و زمان گزارش برنامه باشند.

سرویس تجمع

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

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

گزارش های خلاصه

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

گزارش خلاصه شامل مجموعه ای از جفت های کلید-مقدار به سبک فرهنگ لغت JSON است. هر جفت شامل:

• bucket : کلید تجمیع به عنوان یک رشته اعداد باینری. اگر کلید تجمیع استفاده شده "123" باشد، سطل "1111011" است.
• value : مقدار خلاصه برای یک هدف اندازه‌گیری معین، که از تمام گزارش‌های قابل جمع‌آوری موجود با نویز اضافه شده خلاصه می‌شود.

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

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

سر و صدا و پوسته پوسته شدن

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

توزیع نویز بدون در نظر گرفتن مجموع تمام مقادیر قابل جمع یکسان است. بنابراین، هر چه مقادیر قابل جمع بالاتر باشد، احتمال تاثیر کمتری بر نویز وجود دارد.

به عنوان مثال، فرض کنید توزیع نویز دارای انحراف استاندارد 100 است و در مرکز صفر است. اگر مقدار گزارش جمع‌آوری‌شده جمع‌آوری‌شده (یا "مقدار قابل جمع‌آوری") تنها 200 باشد، انحراف استاندارد نویز 50٪ از مقدار جمع‌آوری‌شده خواهد بود. اما، اگر مقدار قابل جمع 20000 باشد، انحراف استاندارد نویز فقط 0.5٪ از مقدار کل خواهد بود. بنابراین، مقدار قابل جمع 20000 نسبت سیگنال به نویز بسیار بالاتری خواهد داشت.

بنابراین، ضرب مقدار قابل جمع شدن شما در یک ضریب مقیاس می تواند به کاهش نویز کمک کند. ضریب مقیاس‌بندی نشان می‌دهد که چقدر می‌خواهید یک مقدار جمع‌آوری شده را مقیاس کنید.

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

برای محاسبه ضریب مقیاس بندی مناسب، بودجه مشارکت را بر مجموع حداکثر مقادیر قابل جمع در همه کلیدها تقسیم کنید.

برای اطلاعات بیشتر به اسناد بودجه مشارکت مراجعه کنید.

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

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

• GitHub : توضیح دهنده را بخوانید، سوالاتی را مطرح کنید و در بحث شرکت کنید . * پشتیبانی برنامه‌نویس : سؤال بپرسید و به بحث‌های مربوط به مخزن پشتیبانی توسعه‌دهنده Privacy Sandbox بپیوندید. * برای اطلاع از آخرین اطلاعیه‌های مربوط به تجمیع خصوصی، به گروه API ذخیره‌سازی مشترک و گروه API مخاطبان محافظت شده بپیوندید.