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

این سند یک راهنمای سریع برای استفاده از Shared Storage و Private Aggregation است. شما به درک هر دو API نیاز خواهید داشت زیرا Shared Storage مقادیر را ذخیره می‌کند و Private Aggregation گزارش‌های قابل تجمیع را ایجاد می‌کند.

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

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

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

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

فضای ذخیره‌سازی مشترک (Shared Storage) برای هر مبدا محدودیت ظرفیت دارد و هر ورودی به حداکثر تعداد کاراکتر محدود می‌شود. در صورت رسیدن به این محدودیت، ورودی‌های بیشتری ذخیره نمی‌شوند. محدودیت‌های ذخیره‌سازی داده‌ها در توضیح فضای ذخیره‌سازی مشترک (Shared Storage) شرح داده شده است.

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

تکنسین‌های تبلیغات می‌توانند با استفاده از جاوا اسکریپت یا یک هدر پاسخ، در Shared Storage بنویسند. خواندن از Shared Storage فقط در یک محیط ایزوله جاوا اسکریپت به نام worklet انجام می‌شود.

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

  روش‌هایی که در این کتابچه در طول یک عملیات استفاده می‌شوند را می‌توانید در بخش «سطح API پیشنهادی» - در کتابچه - بیابید.

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

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

اطلاعات بیشتر را می‌توانید در بخش «ذخیره‌سازی مشترک: سرآیندهای پاسخ» بیابید.

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

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

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

اگر در یک صفحه چندین بار با کلید یکسان به Shared Storage دسترسی پیدا شود، مقدار کلید بازنویسی می‌شود. اگر کلید نیاز به حفظ مقدار قبلی دارد، استفاده از 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، می‌توانید از Shared-Storage-Write در هدر پاسخ برای ارسال جفت کلید-مقدار استفاده کنید.

  Shared-Storage-Write : append;key="myKey";value="myValue2"
  

به‌روزرسانی دسته‌ای مقادیر

شما می‌توانید sharedStorage.batchUpdate() از داخل یا خارج از یک worklet جاوااسکریپت فراخوانی کنید و یک آرایه مرتب از متدها را که عملیات انتخاب شده را مشخص می‌کنند، به آن ارسال کنید. هر سازنده متد، پارامترهای مشابهی را به عنوان متد مربوطه برای set، append، delete و clear می‌پذیرد.

می‌توانید batchUpdate() از جاوا اسکریپت فراخوانی کنید، یا از یک هدر پاسخ استفاده کنید:

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

  متدهای جاوا اسکریپت که می‌توانند با batchUpdate() استفاده شوند عبارتند از:

  • SharedStorageSetMethod() : یک جفت کلید-مقدار را در Shared Storage می‌نویسد.
  • SharedStorageAppendMethod() : مقداری را به یک کلید موجود در Shared Storage اضافه می‌کند، یا اگر کلید هنوز وجود ندارد، یک جفت کلید-مقدار می‌نویسد.
  • SharedStorageDeleteMethod() : یک جفت کلید-مقدار را از Shared Storage حذف می‌کند.
  • SharedStorageClearMethod() : تمام کلیدهای موجود در Shared Storage را پاک می‌کند.

  sharedStorage.batchUpdate([
  new SharedStorageSetMethod('keyOne', 'valueOne'),
  new SharedStorageAppendMethod('keyTwo', 'valueTwo'),
  new SharedStorageDeleteMethod('keyThree'),
  new SharedStorageClearMethod()
  ]);
  

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

  Shared-Storage-Write : set;key=keyOne;value=valueOne, append;key=keyTwo;value=valueTwo,delete;key=keyThree,clear
  

استفاده از هدرهای پاسخ، batchUpdate() را برای تمام متدهای موجود در هدر اجرا می‌کند.

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

شما فقط می‌توانید از داخل یک کتابچه، از Shared Storage بخوانید.

await sharedStorage.get('mykey');

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

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

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

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

  برای حذف از فضای ذخیره‌سازی مشترک از خارج از کتابچه:

  window.sharedStorage.delete('myKey');
  

  برای حذف از فضای ذخیره‌سازی مشترک از داخل کتابچه:

  sharedStorage.delete('myKey');
  

  برای حذف همزمان همه کلیدها از خارج از worklet:

  window.sharedStorage.clear();
  

  برای حذف همزمان همه کلیدها از داخل worklet:

  sharedStorage.clear();
  

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

  برای حذف مقادیر با استفاده از هدرهای پاسخ، می‌توانید Shared-Storage-Write در هدر پاسخ نیز برای ارسال کلید مورد نظر برای حذف استفاده کنید.

  delete;key="myKey"
  

  برای حذف همه کلیدها با استفاده از هدرهای پاسخ:

  clear;
  

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

شما می‌توانید گروه‌های مورد علاقه‌ی مخاطبان محافظت‌شده را از یک کتابچه‌ی Shared Storage بخوانید. متد interestGroups() آرایه‌ای از اشیاء StorageInterestGroup ، شامل ویژگی‌های AuctionInterestGroup و GenerateBidInterestGroup را برمی‌گرداند.

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

async function analyzeInterestGroups() {
  const interestGroups = await interestGroups();
  numIGs = interestGroups.length;
  maxBidCountIG = interestGroups.reduce((max, cur) => { return cur.bidCount > max.bidCount ? cur : max; }, interestGroups[0]);
  console.log("The IG that bid the most has name " + maxBidCountIG.name);
}

مبدأ زمینه مرور که ماژول worklet از آن بارگذاری شده است، مبدأ گروه‌های مورد علاقه‌ای را که به طور پیش‌فرض خوانده می‌شوند، تعیین می‌کند. برای کسب اطلاعات بیشتر در مورد مبدأ پیش‌فرض worklet و نحوه تغییر آن، بخش «اجرای ذخیره‌سازی مشترک و تجمیع خصوصی» را در راهنمای API ذخیره‌سازی مشترک مرور کنید.

گزینه‌ها

همه متدهای اصلاح‌کننده Shared Storage از یک شیء options اختیاری به عنوان آخرین آرگومان پشتیبانی می‌کنند.

با قفل

گزینه withLock اختیاری است. در صورت مشخص شدن، این گزینه به متد دستور می‌دهد که قبل از ادامه، با استفاده از Web Locks API، یک قفل برای منبع تعریف شده دریافت کند. هنگام درخواست قفل، نام قفل ارسال می‌شود. این نام نشان دهنده منبعی است که استفاده از آن در چندین تب، worker یا کد در داخل origin هماهنگ شده است.

گزینه withLock را می‌توان با متدهای اصلاح‌کننده Shared Storage زیر استفاده کرد:

• مجموعه
• ضمیمه کردن
• حذف
• واضح
• به‌روزرسانی دسته‌ای

می‌توانید قفل را با استفاده از جاوا اسکریپت یا یک هدر پاسخ تنظیم کنید:

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

  sharedStorage.set('myKey', 'myValue', { withLock: 'myResource' });
  

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

  Shared-Storage-Write : set;key="myKey";value="myValue",options;with_lock="myResource"
  

قفل‌های Shared Storage بر اساس مبدا داده‌ها پارتیشن‌بندی می‌شوند. این قفل‌ها مستقل از هر قفلی هستند که با استفاده از متد () LockManager request به دست می‌آیند، صرف نظر از اینکه در یک زمینه window یا worker باشند. با این وجود، آنها همان دامنه‌ای را دارند که قفل‌های به دست آمده با استفاده از request() در زمینه SharedStorageWorklet به اشتراک می‌گذارند.

اگرچه متد request() گزینه‌های پیکربندی مختلفی را امکان‌پذیر می‌کند، قفل‌های دریافت‌شده در Shared Storage همیشه از تنظیمات پیش‌فرض زیر پیروی می‌کنند:

• mode: "exclusive" : هیچ قفل دیگری با همین نام نمی‌تواند همزمان در اختیار داشته باشد.
• steal: false : قفل‌های موجود با نام مشابه برای تطبیق با درخواست‌های دیگر منتشر نمی‌شوند.
• ifAvailable: false : درخواست‌ها تا زمان در دسترس قرار گرفتن قفل، به طور نامحدود منتظر می‌مانند.

چه زمانی از withLock استفاده کنیم؟

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

یکی دیگر از موقعیت‌هایی که قفل‌ها مفید هستند، زمانی است که چندین کلید وجود دارند که باید در یک worklet با هم خوانده شوند و وضعیت آنها باید همگام‌سازی شود. در این حالت، باید فراخوانی‌های get را با یک قفل پوشش داد و هنگام نوشتن روی آن کلیدها، حتماً همان قفل را به دست آورد.

ترتیب قفل ها

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

برای مثال:

// This line might pause until the lock is available.
sharedStorage.set('keyOne', 'valueOne', { withLock: 'resource-lock' });

// This line will run right away, even if the first one is still waiting.
sharedStorage.set('keyOne', 'valueTwo');

مثال تغییر چندین کلید

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

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

مثال modify-multiple-keys.js زیر مقادیر جدیدی را برای keyOne و keyTwo با modify-lock تنظیم می‌کند، سپس عملیات modify-multiple-keys را از worklet اجرا می‌کند:

// modify-multiple-keys.js
sharedStorage.batchUpdate([
    new SharedStorageSetMethod('keyOne', calculateValueFor('keyOne')),
    new SharedStorageSetMethod('keyTwo', calculateValueFor('keyTwo'))
], { withLock: 'modify-lock' });

const modifyWorklet = await sharedStorage.createWorklet('modify-multiple-keys-worklet.js');
await modifyWorklet.run('modify-multiple-keys');

سپس، درون modify-multiple-keys-worklet.js می‌توانید با استفاده از navigator.locks.request() درخواست قفل دهید تا کلیدها را بخوانید و در صورت لزوم تغییر دهید.

// modify-multiple-keys-worklet.js
class ModifyMultipleKeysOperation {
  async run(data) {
    await navigator.locks.request('modify-lock', async (lock) => {
      const value1 = await sharedStorage.get('keyOne');
      const value2 = await sharedStorage.get('keyTwo');

      // Do something with `value1` and `value2` here.

      await sharedStorage.delete('keyOne');
      await sharedStorage.delete('keyTwo');
    });
  }
}
register('modify-multiple-keys', ModifyMultipleKeysOperation);

تغییر زمینه

داده‌های Shared Storage در مبدا (مثلاً https://example.adtech.com) از زمینه مرور که تماس از آن سرچشمه گرفته است، نوشته می‌شوند.

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

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

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

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

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

API تجمیع خصوصی

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

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

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

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

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

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

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

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

• dataOrigin: "context-origin" : (پیش‌فرض) داده‌ها در فضای ذخیره‌سازی مشترکِ مبداءِ زمینه‌ی مرورِ فراخوانی‌شده ذخیره می‌شوند.
• dataOrigin: "script-origin" : داده‌ها در حافظه مشترک مبدا اسکریپت worklet ذخیره می‌شوند. برای فعال کردن این حالت، عضویت لازم است.
• dataOrigin: "https://custom-data-origin.example" : داده‌ها در فضای ذخیره‌سازی مشترک یک منبع داده سفارشی ذخیره می‌شوند. برای فعال کردن این حالت، عضویت و رضایت مالک منبع داده سفارشی لازم است، همانطور که در منبع داده سفارشی توضیح داده شده است.

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

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

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1
Access-Control-Allow-Origin: *

همچنین می‌توانید اسکریپت‌های cross-origin را با استفاده از یک iframe شخص ثالث اجرا کنید، که در این صورت اقدامات Shared Storage در زمینه مرور شخص ثالث خواهد بود.

استفاده از iframe با مبدا متقابل

برای فراخوانی فایل worklet مربوط به فضای ذخیره‌سازی مشترک، به یک iframe نیاز است.

در iframe تبلیغ، ماژول worklet را با فراخوانی addModule() بارگذاری کنید. برای اجرای متدی که در فایل worklet sharedStorageWorklet.js ثبت شده است، در همان iframe تبلیغ، تابع جاوا اسکریپت 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);

استفاده از درخواست‌های بین‌منبعی

ذخیره‌سازی مشترک و تجمیع خصوصی امکان ایجاد workletهای بین‌منشأیی را بدون نیاز به iframeهای بین‌منشأیی فراهم می‌کند.

صفحه شخص اول همچنین می‌تواند یک فراخوانی createWorklet() را به نقطه پایانی جاوا اسکریپت cross-origin فراخوانی کند. هنگام ایجاد worklet، باید مبدا پارتیشن داده worklet را برابر با script-origin تنظیم کنید.

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

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

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

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

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

مبدا داده سفارشی

وقتی dataOrigin روی یک مبدأ معتبر تنظیم می‌شود، مالک dataOrigin باید با میزبانی یک فایل JSON که مبدأ اسکریپت worklet را در مسیر /.well-known/shared-storage/trusted-origins فهرست می‌کند، به پردازش Shared Storage برای آن dataOrigin رضایت دهد. این فایل باید آرایه‌ای از اشیاء با کلیدهای scriptOrigin و contextOrigin باشد. مقادیر این کلیدها می‌توانند یک رشته یا آرایه‌ای از رشته‌ها باشند.

فایل trusted-origins را با استفاده از اطلاعات زیر بسازید:

• زمینه تماس گیرنده
• مبدا و آدرس اسکریپت Worklet
• منشأ و مالک داده‌ها

جدول زیر نشان می‌دهد که چگونه می‌توانید فایل trusted-origins را بر اساس این اطلاعات بسازید:

[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "https://publisher.example"
}]
      

[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "*"
}]
      

[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": [
      "https://publisher-a.example",
      "https://publisher-b.example"
  ]
}]
      

[{
  "scriptOrigin": [
    "https://cdn-a-ad.example",
    "https://cdn-b-ad.example"
  ],
  "contextOrigin": "https://publisher.example"
}]
      

برای مثال، JSON زیر می‌تواند در https://custom-data-origin.example/.well-known/shared-storage/trusted-origins میزبانی شود و تمام پردازنده‌های مجاز داده‌های Shared Storage را برای مبدا https://custom-data-origin.example ترکیب کند.

[
  {
    "scriptOrigin": "https://script-origin.a.example",
    "contextOrigin": "https://context-origin.a.example"
  },
  {
    "scriptOrigin": "https://script-origin.b.example",
    "contextOrigin": [
      "https://context-origin.a.example",
      "https://context-origin.b.example"
    ]
}]

مراحل بعدی

صفحات بعدی جنبه‌های مهم APIهای Shared Storage و Private Aggregation را توضیح می‌دهند.

• مقدمه‌ای بر فضای ذخیره‌سازی مشترک (کروم توسعه‌دهندگان)
• موارد استفاده از فضای ذخیره‌سازی مشترک (کروم توسعه‌دهندگان)
• مقدمه‌ای بر تجمیع خصوصی (برای توسعه‌دهندگان کروم)
• توضیح‌دهنده‌ی فضای ذخیره‌سازی مشترک (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 به اشتراک بگذارید.

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