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

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

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

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

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

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

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

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

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

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

Worklet ها برای ذخیره و استخراج داده ها با Shared Storage API استفاده می شوند.

• با استفاده از فناوری‌های تبلیغات جاوا اسکریپت می‌توان عملکردهای ذخیره‌سازی مشترک خاصی مانند تنظیم، الحاق و حذف مقادیر خارج از Worklet جاوا اسکریپت را انجام داد. با این حال، عملکردهایی مانند خواندن ذخیره‌سازی مشترک و انجام تجمیع خصوصی باید از طریق یک Worklet JavaScript تکمیل شوند. روش‌هایی را می‌توان در خارج از Worklet جاوا اسکریپت در Proposed API Surface - Outside the Worklet یافت.

  روش هایی که در Worklet در طول یک عملیات استفاده می شوند را می توان در Proposed API Surface - In the worklet یافت.

• استفاده از هدرهای پاسخ

  مشابه جاوا اسکریپت، تنها توابع خاصی مانند تنظیم، افزودن و حذف مقادیر در ذخیره‌سازی اشتراکی را می‌توان با استفاده از هدرهای پاسخ انجام داد. برای کار با ذخیره‌سازی مشترک در سرصفحه پاسخ، 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)
});

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

برای دسترسی به داده ها از فضای ذخیره سازی مشترک باید یک Worklet ایجاد کنید. برای انجام این کار، createWorklet() با URL worklet فراخوانی کنید. به‌طور پیش‌فرض، هنگام استفاده از فضای ذخیره‌سازی مشترک با createWorklet() ، مبدأ پارتیشن داده، مبدأ متن مرور فراخوانی خواهد بود، نه مبدا خود اسکریپت Worklet.

برای تغییر رفتار پیش‌فرض، هنگام فراخوانی createWorklet ویژگی dataOrigin را تنظیم کنید.

• dataOrigin: "context-origin" : (پیش‌فرض) داده‌ها در فضای ذخیره‌سازی مشترک مبدا متن مرور فراخوانی ذخیره می‌شوند.
• dataOrigin: "script-origin" : داده ها در حافظه مشترک مبدا اسکریپت worklet ذخیره می شوند. توجه داشته باشید که برای فعال کردن این حالت باید یک انتخاب انتخاب کنید.

sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

برای انتخاب، هنگام استفاده از "script-origin" ، نقطه پایانی اسکریپت باید با سرصفحه Shared-Storage-Cross-Origin-Worklet-Allowed پاسخ دهد. توجه داشته باشید که CORS باید برای درخواست های متقاطع فعال باشد.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

تنظیم «dataOrigin» در «createWorklet()» و ایجاد worklets متقاطع با «addModule()» در M130 در دسترس قرار گرفت.

استفاده از iframe متقاطع

یک iframe برای فراخوانی Worklet ذخیره سازی مشترک مورد نیاز است.

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

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.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,
      value
    });
  }
}
register('shared-storage-report', SharedStorageReportOperation);

با استفاده از درخواست متقاطع

ذخیره‌سازی مشترک و تجمیع خصوصی اجازه می‌دهد تا بدون نیاز به iframe با منبع متقاطع، Worklet‌های متقاطع ایجاد کنید.

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

async function crossOriginCall() {
  const privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.example/js/worklet.js',
    { dataOrigin: 'script-origin' }
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

نقطه پایانی جاوا اسکریپت متقاطع باید با هدرهای Shared-Storage-Cross-Origin-Worklet-Allowed پاسخ دهد و توجه داشته باشد که CORS برای درخواست فعال است.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

Worklet هایی که با استفاده از createWorklet() ایجاد می شوند دارای selectURL و run() خواهند بود. addModule() برای این در دسترس نیست.

توجه: addModule() می توان برای ایجاد Worklet های متقاطع استفاده کرد. با این حال، استفاده از createWorklet() ترجیح داده می شود زیرا اجازه ایجاد یک پارتیشن داده متقاطع را می دهد و برخلاف addModule() می تواند چندین Worklet ایجاد کند.

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}

مراحل بعدی

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

• مقدمه ای بر فضای ذخیره سازی مشترک (برنامه نویس کروم)
• موارد استفاده از فضای ذخیره‌سازی مشترک (برنامه‌نویس Chrome)
• مقدمه ای بر Private Aggregation (Developer Chrome)
• توضیح دهنده حافظه مشترک (GitHub)
• توضیح دهنده تجمع خصوصی (GitHub)
• نسخه نمایشی ذخیره سازی مشترک و جمع آوری خصوصی

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

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

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

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

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

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