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

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

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

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

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

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

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

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

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

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

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

شما می توانید sharedStorage.batchUpdate() را از داخل یا خارج از یک Worklet جاوا اسکریپت فراخوانی کنید و یک آرایه مرتب از متدها را ارسال کنید که عملیات انتخابی را مشخص می کند. هر سازنده متد پارامترهای یکسانی را به عنوان روش فردی متناظر خود برای تنظیم، الحاق، حذف و پاک می‌پذیرد.

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

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

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

    • SharedStorageSetMethod() : یک جفت کلید-مقدار را در ذخیره سازی مشترک می نویسد.
    • SharedStorageAppendMethod() : یک مقدار را به یک کلید موجود در ذخیره سازی مشترک اضافه می کند.
    • SharedStorageDeleteMethod() : یک جفت کلید-مقدار را از ذخیره‌سازی مشترک حذف می‌کند.
    • SharedStorageClearMethod() : تمام کلیدهای موجود در ذخیره سازی مشترک را پاک می کند. 
    sharedStorage.batchUpdate([
new SharedStorageSetMethod('keyOne', 'valueOne'),
new SharedStorageAppendMethod('keyTwo', 'valueTwo'),
new SharedStorageDeleteMethod('keyThree'),
new SharedStorageClearMethod()
]);

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

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

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

می‌توانید از فضای ذخیره‌سازی مشترک فقط از داخل یک 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;

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

می‌توانید گروه‌های علاقه‌مند مخاطب محافظت‌شده را از یک Worklet فضای ذخیره‌سازی مشترک بخوانید. متد 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 پیش فرض و نحوه تغییر آن، بخش Executing Shared Storage and Private Aggregation را در Shared Storage API Walkthrough مرور کنید.

گزینه ها

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

با قفل

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

گزینه withLock را می توان با روش های اصلاح کننده ذخیره سازی مشترک زیر استفاده کرد:

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

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

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

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

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

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

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

در حالی که متد request() به گزینه‌های پیکربندی مختلف اجازه می‌دهد، قفل‌های به‌دست‌آمده در ذخیره‌سازی مشترک همیشه به تنظیمات پیش‌فرض زیر پایبند هستند:

  • 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');
اصلاح چند کلید مثال

این مثال از یک قفل استفاده می‌کند تا اطمینان حاصل کند که عملیات خواندن و حذف در 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);

تغییر متن

داده‌های ذخیره‌سازی مشترک در مبدا (به عنوان مثال، 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)
});

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

به‌طور پیش‌فرض، هنگام استفاده از فضای ذخیره‌سازی مشترک با 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" یا یک مبدا سفارشی، نقطه پایانی اسکریپت باید با سرصفحه Shared-Storage-Cross-Origin-Worklet-Allowed پاسخ دهد. برای درخواست های متقاطع، CORS نیز باید فعال باشد. 

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

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

استفاده از 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() برای این در دسترس نیست. 

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 فهرست می‌کند، با پردازش ذخیره‌سازی مشترک برای آن dataOrigin موافقت کند. فایل باید آرایه ای از اشیا با کلیدهای scriptOrigin و contextOrigin باشد. مقادیر این کلیدها می تواند یک رشته یا یک آرایه از رشته ها باشد.

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

  • زمینه تماس گیرنده
  • مبدا و URL اسکریپت Worklet
  • مبدا و مالک داده

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

زمینه تماس گیرنده URL اسکریپت Worklet مبدا داده ها صاحب داده فایل JSON با منبع معتبر مالک منبع داده
https://publisher.example https://publisher.example/script.js زمینه-منشا https://publisher.example JSON مورد نیاز نیست
https://publisher.example https://ad.example/script.js منشاء اسکریپت https://ad.example JSON مورد نیاز نیست
https://publisher.example https://cdn-ad.example/script.js https://ad.example https://ad.example 
[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "https://publisher.example"
}]
هر تماس گیرنده https://cdn-ad.example/script.js https://ad.example https://ad.example 
[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "*"
}]
https://publisher-a.example، یا https://publisher-b.example https://cdn-ad.example/script.js https://ad.example https://ad.example 
[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": [
      "https://publisher-a.example",
      "https://publisher-b.example"
  ]
}]
https://publisher.example https://cdn-a-ad.example/script.js، یا https://cdn-b-ad.example/script.js https://ad.example https://ad.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 میزبانی شود و همه پردازنده‌های مجاز داده‌های ذخیره‌سازی مشترک را برای مبدا 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های جمع‌آوری خصوصی را توضیح می‌دهند.

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

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

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

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

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

،

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

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

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

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

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

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

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

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

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

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

شما می توانید sharedStorage.batchUpdate() را از داخل یا خارج از یک Worklet جاوا اسکریپت فراخوانی کنید و یک آرایه مرتب از متدها را ارسال کنید که عملیات انتخابی را مشخص می کند. هر سازنده متد پارامترهای یکسانی را به عنوان روش فردی متناظر خود برای تنظیم، الحاق، حذف و پاک می‌پذیرد.

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

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

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

    • SharedStorageSetMethod() : یک جفت کلید-مقدار را در ذخیره سازی مشترک می نویسد.
    • SharedStorageAppendMethod() : یک مقدار را به یک کلید موجود در ذخیره سازی مشترک اضافه می کند.
    • SharedStorageDeleteMethod() : یک جفت کلید-مقدار را از ذخیره‌سازی مشترک حذف می‌کند.
    • SharedStorageClearMethod() : تمام کلیدهای موجود در ذخیره سازی مشترک را پاک می کند. 
    sharedStorage.batchUpdate([
new SharedStorageSetMethod('keyOne', 'valueOne'),
new SharedStorageAppendMethod('keyTwo', 'valueTwo'),
new SharedStorageDeleteMethod('keyThree'),
new SharedStorageClearMethod()
]);

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

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

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

می‌توانید از فضای ذخیره‌سازی مشترک فقط از داخل یک 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;

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

می‌توانید گروه‌های علاقه‌مند مخاطب محافظت‌شده را از یک Worklet فضای ذخیره‌سازی مشترک بخوانید. متد 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 پیش فرض و نحوه تغییر آن، بخش Executing Shared Storage and Private Aggregation را در Shared Storage API Walkthrough مرور کنید.

گزینه ها

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

با قفل

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

گزینه withLock را می توان با روش های اصلاح کننده ذخیره سازی مشترک زیر استفاده کرد:

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

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

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

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

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

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

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

در حالی که متد request() به گزینه‌های پیکربندی مختلف اجازه می‌دهد، قفل‌های به‌دست‌آمده در ذخیره‌سازی مشترک همیشه به تنظیمات پیش‌فرض زیر پایبند هستند:

  • 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');
اصلاح چند کلید مثال

این مثال از یک قفل استفاده می‌کند تا اطمینان حاصل کند که عملیات خواندن و حذف در 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);

تغییر متن

داده‌های ذخیره‌سازی مشترک در مبدا (به عنوان مثال، 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)
});

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

به‌طور پیش‌فرض، هنگام استفاده از فضای ذخیره‌سازی مشترک با 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" یا یک مبدا سفارشی، نقطه پایانی اسکریپت باید با سرصفحه Shared-Storage-Cross-Origin-Worklet-Allowed پاسخ دهد. برای درخواست های متقاطع، CORS نیز باید فعال باشد. 

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

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

استفاده از 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() برای این در دسترس نیست. 

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 فهرست می‌کند، با پردازش ذخیره‌سازی مشترک برای آن dataOrigin موافقت کند. فایل باید آرایه ای از اشیا با کلیدهای scriptOrigin و contextOrigin باشد. مقادیر این کلیدها می تواند یک رشته یا یک آرایه از رشته ها باشد.

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

  • زمینه تماس گیرنده
  • مبدا و URL اسکریپت Worklet
  • مبدا و مالک داده

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

زمینه تماس گیرنده URL اسکریپت کار مبدا داده ها صاحب داده پرونده JSON ORIGINS ORIGIN ORIGIN ORIGIN
https: //publisher.example https: //publisher.example/script.js مبداء https: //publisher.example Json نیازی به آن نیست
https: //publisher.example https: //ad.example/script.js با منزل https: //ad.example Json نیازی به آن نیست
https: //publisher.example https: //cdn-ad.example/script.js https: //ad.example https: //ad.example 
[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "https://publisher.example"
}]
هر تماس گیرنده https: //cdn-ad.example/script.js https: //ad.example https: //ad.example 
[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "*"
}]
https: //publisher-a.example ، یا https: //publisher-b.example https: //cdn-ad.example/script.js https: //ad.example https: //ad.example 
[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": [
      "https://publisher-a.example",
      "https://publisher-b.example"
  ]
}]
https: //publisher.example https: //cdn-a-ad.example/script.js ، یا https: //cdn-b-ad.example/script.js https: //ad.example https: //ad.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 میزبانی کرد و تمام پردازنده های مجاز ذخیره شده برای 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 های جمع آوری خصوصی را توضیح می دهد.

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

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

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

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

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

،

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

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

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

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

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

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

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

فناوری های تبلیغاتی می توانند با استفاده از javaScript یا عنوان های پاسخ ، به ذخیره سازی مشترک بنویسند. خواندن از ذخیره سازی مشترک فقط در یک محیط جاوا اسکریپت منزوی به نام کار انجام می شود.

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

    روش هایی که در طول یک کار در محل کار مورد استفاده قرار می گیرند می توانند در سطح API پیشنهادی - در کارگاه مشاهده شوند.

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

    مشابه JavaScript ، فقط توابع خاص مانند تنظیم ، ضمیمه و حذف مقادیر در ذخیره سازی مشترک می تواند با استفاده از هدرهای پاسخ انجام شود. برای کار با ذخیره سازی مشترک در یک هدر پاسخ ، 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() از داخل یا خارج از یک کار JavaScript تماس بگیرید. در صورت فراخوانی از خارج از محل کار ، داده ها به منشأ زمینه مرور که این تماس از آن ساخته شده است نوشته شده است. در صورت فراخوانی از داخل کار ، داده ها به منشأ زمینه مرور که بار کار را بارگیری می کند ، نوشته شده است. کلیدهایی که تنظیم شده اند از تاریخ آخرین به روزرسانی تاریخ انقضا 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() کلید را ایجاد می کند و مقدار را تعیین می کند. این می تواند با استفاده از هدرهای JavaScript یا پاسخ انجام شود.

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

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

    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"

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

شما می توانید با sharedStorage.batchUpdate() از داخل یا خارج از یک کار JavaScript تماس بگیرید و در یک آرایه سفارش داده شده از روش هایی که عملیات انتخابی را مشخص می کند عبور کنید. هر سازنده متد پارامترهای مشابهی را با روش فردی مربوطه برای تنظیم ، ضمیمه ، حذف و پاک بودن می پذیرد.

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

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

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

    • SharedStorageSetMethod() : یک جفت ارزش کلیدی را برای ذخیره سازی مشترک می نویسد.
    • SharedStorageAppendMethod() : یک مقدار را به یک کلید موجود در ذخیره سازی مشترک اضافه می کند.
    • SharedStorageDeleteMethod() : یک جفت ارزش کلیدی را از ذخیره مشترک حذف می کند.
    • SharedStorageClearMethod() : تمام کلیدهای موجود در ذخیره سازی مشترک را پاک می کند. 
    sharedStorage.batchUpdate([
new SharedStorageSetMethod('keyOne', 'valueOne'),
new SharedStorageAppendMethod('keyTwo', 'valueTwo'),
new SharedStorageDeleteMethod('keyThree'),
new SharedStorageClearMethod()
]);

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

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

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

شما می توانید از ذخیره مشترک فقط از داخل یک کار بخوانید. 

await sharedStorage.get('mykey');

منشأ زمینه مرور که ماژول کار از آن بارگیری شده است از مشخص می کند که ذخیره مشترک آنها خوانده می شود.

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

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

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

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

    window.sharedStorage.delete('myKey');

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

    sharedStorage.delete('myKey');

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

    window.sharedStorage.clear();

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

    sharedStorage.clear();

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

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

    delete;key="myKey"

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

    clear;

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

شما می توانید گروه های علاقه مند مخاطبان محافظت شده را از یک کار ذخیره سازی مشترک بخوانید. روش interestGroups() مجموعه ای از اشیاء StorageInterestroup ، از جمله ویژگی های Actioninterestgroup و GenerateBidestroup را برمی گرداند.

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

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);
}

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

گزینه ها

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

بستر

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

از گزینه withLock می توان با روشهای اصلاح کننده ذخیره سازی مشترک زیر استفاده کرد:

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

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

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

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

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

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

قفل های ذخیره سازی مشترک توسط منشأ داده تقسیم می شوند. قفل ها مستقل از هرگونه قفل به دست آمده با استفاده از روش Lockmanager Request () هستند ، صرف نظر از اینکه در یک window یا متن worker هستند. با این وجود ، آنها همان محدوده قفل های به دست آمده با استفاده از request() را در زمینه مشترک storageWorklet به اشتراک می گذارند.

در حالی که روش request() گزینه های مختلف پیکربندی را امکان پذیر می کند ، قفل های به دست آمده در ذخیره سازی مشترک همیشه به تنظیمات پیش فرض زیر پایبند هستند:

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

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

وضعیت دیگری که قفل ها در آن مفید هستند این است که اگر چندین کلید وجود داشته باشد که باید در یک کار با هم خوانده شوند و وضعیت آنها باید هماهنگ شود. در این حالت ، باید تماس های 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');
چندین کلید را تغییر دهید

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

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

// 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);

تغییر متن

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

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

زمینه شخص اول

اگر یک صفحه شخص ثالث کد جاوا اسکریپت شخص ثالث را که sharedStorage.set() تعبیه کرده است که sharedStorage.delete() .

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

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

جفت ارزش کلیدی را می توان با ایجاد یک IFRAME و CALL set() یا حذف () یا delete() در کد JavaScript از درون Iframe در زمینه AD Tech یا شخص ثالث ذخیره کرد.

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

API تجمع خصوصی

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

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

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

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

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

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

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

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

  • dataOrigin: "context-origin" : (پیش فرض) داده ها در ذخیره مشترک منشأ زمینه مرورگر دعوت شده ذخیره می شوند.
  • dataOrigin: "script-origin" : داده ها در ذخیره سازی مشترک منشأ اسکریپت کار ذخیره می شوند. برای فعال کردن این حالت ، گزینه انتخابی لازم است.
  • dataOrigin: "https://custom-data-origin.example" : داده ها در ذخیره مشترک منشأ داده های سفارشی ذخیره می شوند. برای فعال کردن این حالت و رضایت از مالک مبدا داده سفارشی ، به تفصیل در منشأ داده های سفارشی لازم است. 
sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

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

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

همچنین می توانید اسکریپت های متقاطع را با استفاده از یک IFRame شخص ثالث اجرا کنید ، در این صورت اقدامات ذخیره سازی مشترک در زمینه مرور شخص ثالث خواهد بود.

با استفاده از Iframe متقاطع

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

در IFRAME AD ، ماژول کار را با تماس با addModule() بارگذاری کنید. برای اجرای روشی که در پرونده Worklet.js sharedStorageWorklet.js ثبت شده است ، در همان تبلیغ 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' },
});

در اسکریپت کار ، شما باید یک کلاس با روش run Async ایجاد کنید و آن را register تا در IFRAME AD اجرا شود. Inside sharedStorageWorklet.js : 

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

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

ذخیره سازی مشترک و تجمیع خصوصی امکان ایجاد کارگاه های متقاطع را بدون نیاز به iframes متقاطع به صورت متقاطع امکان پذیر می کند.

صفحه شخص اول همچنین می تواند از یک فراخوان createWorklet() به نقطه پایانی JavaScript Cross-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();

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

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

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

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

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

هنگامی که dataOrigin به یک منشأ معتبر تنظیم شده است ، صاحب dataOrigin باید با میزبانی یک فایل JSON که در لیست منشأ اسکریپت کار در PATH /.well-known/shared-storage/trusted-origins قرار دارد ، با پردازش ذخیره سازی مشترک برای آن dataOrigin موافقت کند. پرونده باید مجموعه ای از اشیاء با Keys scriptOrigin و contextOrigin باشد. مقادیر این کلیدها می توانند یک رشته یا مجموعه ای از رشته ها باشند.

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

  • زمینه تماس گیرنده
  • منشأ اسکریپت کار و URL
  • منشأ داده و مالک

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

زمینه تماس گیرنده URL اسکریپت کار مبدا داده ها صاحب داده پرونده JSON ORIGINS ORIGIN ORIGIN ORIGIN
https: //publisher.example https: //publisher.example/script.js مبداء https: //publisher.example Json نیازی به آن نیست
https: //publisher.example https: //ad.example/script.js با منزل https: //ad.example Json نیازی به آن نیست
https: //publisher.example https: //cdn-ad.example/script.js https: //ad.example https: //ad.example 
[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "https://publisher.example"
}]
هر تماس گیرنده https: //cdn-ad.example/script.js https: //ad.example https: //ad.example 
[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "*"
}]
https: //publisher-a.example ، یا https: //publisher-b.example https: //cdn-ad.example/script.js https: //ad.example https: //ad.example 
[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": [
      "https://publisher-a.example",
      "https://publisher-b.example"
  ]
}]
https: //publisher.example https: //cdn-a-ad.example/script.js ، یا https: //cdn-b-ad.example/script.js https: //ad.example https: //ad.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 میزبانی کرد و تمام پردازنده های مجاز ذخیره شده برای 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 های جمع آوری خصوصی را توضیح می دهد.

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

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

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

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

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