این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

راه اندازی سریع ذخیره سازی مشترک و تجمیع خصوصی

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

مخاطبان هدف: فناوری های تبلیغاتی و ارائه دهندگان اندازه گیری.

نسخه ی نمایشی را امتحان کنید

نسخه ی نمایشی زنده را امتحان کنید. برای فعال کردن APIهای Privacy Sandbox مراحل دستورالعمل‌های نمایشی را دنبال کنید. باز کردن Chrome DevTools به شما کمک می کند تا نتایج موارد استفاده مختلف را تجسم کنید. موارد استفاده موجود در دمو:

تجمیع خصوصی
- اندازه گیری دسترسی منحصر به فرد
- اندازه گیری جمعیت شناسی
- اندازه گیری فرکانس K+
استفاده عمومی
- رویداد شناور بر روی قاب‌های حصاردار را اندازه‌گیری کنید
- ناوبری سطح بالا
- کنترل جایی که اشخاص ثالث می توانند بنویسند

نحوه مشاهده فضای ذخیره سازی مشترک

برای مشاهده آنچه در فضای ذخیره‌سازی مشترک ذخیره می‌شود، از Chrome DevTools استفاده کنید. داده های ذخیره شده را می توان در Application -> Shared Storage پیدا کرد.

داده‌های ذخیره‌شده در فضای ذخیره‌سازی مشترک را با استفاده از ابزارهای توسعه‌دهنده Chrome مشاهده کنید.

مشاهده گزارش‌های جمع‌آوری خصوصی

برای مشاهده گزارش های جمع آوری ارسال شده، به chrome://private-aggregation-internals بروید. هنگامی که حالت اشکال زدایی فعال است، یک گزارش بلافاصله (بدون تاخیر) به [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage همراه با گزارش تأخیر زمانی ارسال می شود. [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage .

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

مشاهده گزارش ها در chrome://private-aggregation-internals.

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

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

فضای ذخیره‌سازی مشترک محدود به مبدأ زمینه (تماس‌گیرنده sharedStorage ) است.

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

فراخوانی حافظه مشترک

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

با استفاده از فناوری‌های تبلیغات جاوا اسکریپت می‌توان عملکردهای ذخیره‌سازی مشترک خاصی مانند تنظیم، الحاق و حذف مقادیر خارج از Worklet جاوا اسکریپت را انجام داد. با این حال، عملکردهایی مانند خواندن ذخیره‌سازی مشترک و انجام تجمیع خصوصی باید از طریق یک Worklet JavaScript تکمیل شوند. روش‌هایی را می‌توان در خارج از Worklet جاوا اسکریپت در Proposed API Surface - Outside the Worklet یافت.
روش هایی که در Worklet در طول یک عملیات استفاده می شوند را می توان در Proposed API Surface - In the worklet یافت.
استفاده از هدرهای پاسخ
این ویژگی در M119 در دسترس قرار گرفت.
مشابه جاوا اسکریپت، تنها توابع خاصی مانند تنظیم، افزودن و حذف مقادیر در ذخیره‌سازی اشتراکی را می‌توان با استفاده از هدرهای پاسخ انجام داد. برای کار با ذخیره‌سازی مشترک در سرصفحه پاسخ، Shared-Storage-Writable: ?1 باید در هدر درخواست گنجانده شود.
برای شروع درخواست از مشتری، بسته به روش انتخابی خود، کد زیر را اجرا کنید:
- استفاده از fetch()
```
fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
```
- با استفاده از تگ iframe یا img
```
<iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
```
- استفاده از ویژگی IDL با تگ iframe یا img
```
let iframe = document.getElementById("my-iframe");
iframe.sharedStorageWritable = true;
iframe.src = "https://a.example/path/for/updates";
```

اطلاعات بیشتر را می‌توانید در ذخیره‌سازی مشترک: سرصفحه‌های پاسخ پیدا کنید.

نوشتن در فضای ذخیره‌سازی مشترک

برای نوشتن در فضای ذخیره‌سازی مشترک، با sharedStorage.set() از داخل یا خارج از Worklet جاوا اسکریپت تماس بگیرید. اگر از خارج از Worklet فراخوانی شود، داده ها در مبدأ زمینه مروری که تماس از آن برقرار شده است، نوشته می شود. اگر از داخل Worklet فراخوانی شود، داده ها در مبدأ زمینه مروری که worklet را بارگذاری کرده است، نوشته می شود. کلیدهای تنظیم شده دارای تاریخ انقضا 30 روز از آخرین به روز رسانی هستند.

فیلد ignoreIfPresent اختیاری است. اگر موجود باشد و روی true تنظیم شود، اگر کلید از قبل وجود داشته باشد، به روز نمی شود. انقضای کلید تا 30 روز از زمان فراخوانی set() تمدید می شود حتی اگر کلید به روز نشده باشد.

اگر در بارگذاری یک صفحه با کلید یکسان چندین بار به فضای ذخیره‌سازی مشترک دسترسی داشته باشید، مقدار کلید بازنویسی می‌شود. اگر کلید نیاز به حفظ مقدار قبلی دارد، ایده خوبی است که از sharedStorage.append() استفاده کنید.

با استفاده از جاوا اسکریپت

خارج از کارگاه:

window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true });
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false });
// Shared Storage: {'myKey': 'myValue2'}

به طور مشابه، در داخل کارگاه:

sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });

استفاده از هدرهای پاسخ
همچنین می‌توانید با استفاده از سرصفحه‌های پاسخ، در فضای ذخیره‌سازی مشترک بنویسید. برای انجام این کار، از Shared-Storage-Write در هدر پاسخ همراه با دستورات زیر استفاده کنید:
```
Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
```
```
Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
```
چندین مورد را می‌توان با کاما از هم جدا کرد و می‌توان set ، append ، delete و clear را ترکیب کرد.
```
Shared-Storage-Write : 
set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
```

اضافه کردن یک مقدار

با استفاده از روش append می توانید مقداری را به یک کلید موجود اضافه کنید. اگر کلید وجود نداشته باشد، فراخوانی append() کلید را ایجاد کرده و مقدار را تنظیم می کند. این را می توان با استفاده از جاوا اسکریپت یا هدرهای پاسخ انجام داد.

با استفاده از جاوا اسکریپت

برای به‌روزرسانی مقادیر کلیدهای موجود، از sharedStorage.append() از داخل یا خارج Worklet استفاده کنید.

window.sharedStorage.append('myKey', 'myValue1');
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.append('myKey', 'myValue2');
// Shared Storage: {'myKey': 'myValue1myValue2'}
window.sharedStorage.append('anotherKey', 'hello');
// Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}

برای ضمیمه کردن داخل کارنامه:

sharedStorage.append('myKey', 'myValue1');

استفاده از هدرهای پاسخ
مشابه تنظیم یک مقدار در ذخیره سازی مشترک، می توانید از Shared-Storage-Write در سربرگ پاسخ برای ارسال در جفت کلید-مقدار استفاده کنید.
```
Shared-Storage-Write : append;key="myKey";value="myValue2"
```

خواندن از فضای ذخیره‌سازی مشترک

می‌توانید از فضای ذخیره‌سازی مشترک فقط از داخل یک Worklet مطالعه کنید.

await sharedStorage.get('mykey');

مبدأ زمینه مروری که ماژول worklet از آن بارگیری شده است، تعیین می‌کند که ذخیره‌سازی مشترک چه کسی خوانده شود.

حذف از حافظه مشترک

می‌توانید با استفاده از جاوا اسکریپت از داخل یا خارج از Worklet یا با استفاده از هدرهای پاسخ با delete() حذف‌ها را از ذخیره‌سازی مشترک انجام دهید. برای حذف همه کلیدها به طور همزمان، از clear() از هر کدام استفاده کنید.

با استفاده از جاوا اسکریپت
برای حذف از فضای ذخیره‌سازی مشترک از خارج از Worklet:
```
window.sharedStorage.delete('myKey');
```
برای حذف از فضای ذخیره‌سازی مشترک از داخل Worklet:
```
sharedStorage.delete('myKey');
```
برای حذف همه کلیدها به یکباره از خارج از Worklet:
```
window.sharedStorage.clear();
```
برای حذف یکباره همه کلیدها از داخل Worklet:
```
sharedStorage.clear();
```
استفاده از هدرهای پاسخ
برای حذف مقادیر با استفاده از هدرهای پاسخ، می‌توانید از Shared-Storage-Write در سرصفحه پاسخ نیز استفاده کنید تا کلید حذف شود.
```
delete;key="myKey"
```
برای حذف همه کلیدها با استفاده از هدرهای پاسخ:
```
clear;
```

تغییر متن

داده‌های ذخیره‌سازی مشترک در مبدا (به عنوان مثال، https://example.adtech.com) زمینه مروری که تماس از آن آغاز شده است، نوشته می‌شود.

هنگامی که کد شخص ثالث را با استفاده از یک تگ <script> بارگیری می کنید، کد در زمینه مرور در embedder اجرا می شود. بنابراین، زمانی که کد شخص ثالث sharedStorage.set() را فراخوانی می‌کند، داده‌ها در ذخیره‌سازی اشتراکی embedder نوشته می‌شوند. هنگامی که کد شخص ثالث را در یک iframe بارگیری می کنید، کد یک زمینه مرور جدید دریافت می کند و منشاء آن مبدا iframe است. بنابراین، فراخوانی sharedStorage.set() که از iframe انجام می‌شود، داده‌ها را در ذخیره‌سازی مشترک مبدا iframe ذخیره می‌کند.

زمینه شخص اول

اگر یک صفحه شخص اول کد جاوا اسکریپت شخص ثالثی را جاسازی کرده باشد که sharedStorage.set() یا sharedStorage.delete() را فراخوانی می کند، جفت کلید-مقدار در زمینه شخص اول ذخیره می شود.

داده های ذخیره شده در یک صفحه شخص اول با جاوا اسکریپت شخص ثالث جاسازی شده است.

زمینه شخص ثالث

جفت کلید-مقدار را می توان با ایجاد یک iframe و فراخوانی set() یا delete() در کد جاوا اسکریپت از داخل iframe در فناوری تبلیغات یا زمینه شخص ثالث ذخیره کرد.

داده های ذخیره شده در زمینه فناوری تبلیغاتی یا شخص ثالث.

Private Aggregation API

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

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

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

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

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

اجرای فضای ذخیره سازی مشترک و تجمیع خصوصی

در iframe آگهی، ماژول worklet را با فراخوانی addModule() بارگیری کنید. برای اجرای روشی که در فایل worklet sharedStorageWorklet.js ثبت شده است، در همان ad iframe JavaScript، sharedStorage.run() را فراخوانی کنید.

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

در اسکریپت worklet، باید یک کلاس با یک متد async run ایجاد کنید. و این کلاس را برای اجرا در iframe آگهی register . داخل sharedStorageWorklet.js :

class SharedStorageReportOperation {
  async run(data) {
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

اشکال زدایی

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

privateAggregation.enableDebugMode();

برای مرتبط کردن گزارش‌ها با زمینه‌هایی که آنها را راه‌اندازی کرده‌اند، می‌توانید یک کلید اشکال‌زدایی عدد صحیح بدون علامت 64 بیتی تنظیم کنید که به فراخوانی جاوا اسکریپت ارسال می‌شود. debugKey یک BigInt است.

privateAggregation.enableDebugMode({debugKey: 1234});

اشکال زدایی حافظه مشترک

فضای ذخیره‌سازی مشترک یک پیام خطای عمومی را برمی‌گرداند:

Promise is rejected without and explicit error message

می‌توانید با قرار دادن تماس‌ها با بلوک‌های try-catch، فضای ذخیره‌سازی مشترک را رفع اشکال کنید.

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

اشکال زدایی تجمع خصوصی

گزارش ها به /.well-known/private-aggregation/report-shared-storage and /.well-known/private-aggregation/debug/report-shared-storage ارسال می شوند. گزارش‌های اشکال‌زدایی باری مشابه JSON زیر دریافت می‌کنند. این محموله فیلد api را به عنوان "store-store" تعریف می کند.

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

اشکال‌زدایی محموله متن شفاف

debug_cleartext_payload با Base64 CBOR -encoded است. می‌توانید سطل و مقدار را با استفاده از رمزگشا مشاهده کنید یا از کد جاوا اسکریپت موجود در رمزگشای ذخیره‌سازی مشترک استفاده کنید.

مراحل بعدی

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

هنگامی که با API ها آشنا شدید، می توانید شروع به جمع آوری گزارش ها کنید که به عنوان یک درخواست POST به نقاط انتهایی زیر به عنوان JSON در بدنه درخواست ارسال می شوند.

گزارش‌های اشکال‌زدایی - context-origin/.well-known/private-aggregation/debug/report-shared-storage
گزارش ها - context-origin/.well-known/private-aggregation/report-shared-storage

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

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

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