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

Storage Access API

مسدود کردن کوکی‌های شخص ثالث توسط مرورگرها، تنظیمات کاربر و پارتیشن‌بندی فضای ذخیره‌سازی ، برای سایت‌ها و سرویس‌هایی که به کوکی‌ها و سایر فضای ذخیره‌سازی در زمینه‌های تعبیه‌شده متکی هستند، برای سفرهای کاربر مانند احراز هویت، چالشی ایجاد می‌کند. Storage Access API (SAA) به این موارد استفاده اجازه می دهد تا به کار خود ادامه دهند، در حالی که ردیابی بین سایتی را تا حد امکان محدود می کند.

وضعیت پیاده سازی

Browser Support

Source

Storage Access API در همه مرورگرهای اصلی موجود است، اما تفاوت‌های پیاده‌سازی جزئی بین مرورگرها وجود دارد. این تفاوت ها در بخش های مربوطه در این پست برجسته شده است.

کار برای حل و فصل همه مشکلات باقیمانده مسدود کردن قبل از استانداردسازی API ادامه دارد.

Storage Access API چیست؟

Storage Access API یک API جاوا اسکریپت است که به iframes اجازه می‌دهد تا مجوز دسترسی به فضای ذخیره‌سازی را درخواست کند، در صورتی که تنظیمات مرورگر دسترسی به آن را رد کند. جاسازی‌هایی با موارد استفاده که به بارگیری منابع بین سایتی بستگی دارند، می‌توانند از API برای درخواست مجوز دسترسی از کاربر، بر اساس نیاز، استفاده کنند.

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

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

موارد استفاده کنید

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

موارد استفاده عبارتند از:

ویجت‌های کامنت‌گذاری تعبیه‌شده که به جزئیات جلسه ورود نیاز دارند.
دکمه های "پسندیدن" رسانه های اجتماعی که به جزئیات جلسه ورود نیاز دارند.
اسناد جاسازی شده که به جزئیات جلسه ورود نیاز دارند.
تجربه ممتازی که برای جاسازی ویدیو ارائه می‌شود (مثلاً برای نمایش ندادن تبلیغات برای کاربرانی که وارد سیستم شده‌اند، یا برای دانستن ترجیحات کاربر برای زیرنویس‌ها یا محدود کردن انواع خاصی از ویدیو).
سیستم های پرداخت تعبیه شده

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

زمان استفاده از Storage Access API بر روی سایر APIها

Storage Access API یکی از جایگزین‌های استفاده از کوکی‌ها و فضای ذخیره‌سازی پارتیشن نشده است، بنابراین درک زمان استفاده از این API در مقایسه با سایرین مهم است. این برای موارد استفاده است که هر دو مورد زیر درست است:

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

APIهای جایگزین برای موارد مختلف استفاده وجود دارد:

کوکی‌هایی که دارای وضعیت پارتیشن بندی شده مستقل هستند (CHIPS) به توسعه‌دهندگان اجازه می‌دهد تا یک کوکی را در فضای ذخیره‌سازی «پارتیشن‌بندی‌شده» با یک شیشه کوکی جداگانه برای هر سایت سطح بالا انتخاب کنند. برای مثال، ویجت چت وب شخص ثالث ممکن است به تنظیم یک کوکی برای ذخیره اطلاعات جلسه متکی باشد. اطلاعات جلسه در هر سایت ذخیره می شود، بنابراین کوکی تنظیم شده توسط ویجت نیازی به دسترسی به وب سایت های دیگر که در آن جاسازی شده نیز نیست. Storage Access API زمانی مفید است که یک ویجت شخص ثالث تعبیه شده وابسته به اشتراک گذاری اطلاعات یکسان در منابع مختلف باشد (مثلاً برای جزئیات جلسه وارد شده یا تنظیمات برگزیده).
پارتیشن بندی فضای ذخیره سازی راهی برای iframe های متقابل سایتی است تا از مکانیسم های ذخیره سازی جاوا اسکریپت موجود در حین تقسیم فضای ذخیره سازی در هر سایت استفاده کنند. این مانع از دسترسی به فضای ذخیره سازی جاسازی شده در یک وب سایت توسط همان جاسازی در وب سایت های دیگر می شود.
مجموعه‌های وب‌سایت‌های مرتبط (RWS) راهی است برای سازمان برای اعلام روابط بین سایت‌ها، به طوری که مرورگرها اجازه دسترسی محدود به کوکی‌ها و فضای ذخیره‌سازی را برای اهداف خاص می‌دهند. سایت‌ها همچنان نیاز به درخواست دسترسی با Storage Access API دارند، اما برای سایت‌های موجود در مجموعه، دسترسی می‌تواند بدون درخواست کاربر اعطا شود.
مدیریت اعتبار فدرال (FedCM) یک رویکرد حفظ حریم خصوصی برای خدمات هویتی فدرال است. Storage Access API با دسترسی به کوکی های پارتیشن نشده و ذخیره سازی پس از ورود به سیستم سروکار دارد. برای برخی موارد استفاده، FedCM یک راه حل جایگزین برای Storage Access API ارائه می دهد، و ممکن است ترجیح داده شود زیرا دارای یک درخواست مرورگر با ورود به سیستم است. با این حال، پذیرش FedCM معمولاً به تغییرات اضافی در کد شما نیاز دارد، به عنوان مثال برای پشتیبانی از نقاط پایانی HTTP.
APIهای ضد کلاهبرداری ، مرتبط با تبلیغات و اندازه‌گیری نیز وجود دارند، و API دسترسی به فضای ذخیره‌سازی برای رفع این نگرانی‌ها در نظر گرفته نشده است.

از Storage Access API استفاده کنید

Storage Access API دو روش مبتنی بر وعده دارد:

Document.hasStorageAccess() (همچنین با نام جدید Document.hasUnpartitionedCookieAccess() از Chrome 125 موجود است)
Document.requestStorageAccess()

همچنین با Permissions API ادغام می شود. این به شما امکان می‌دهد وضعیت مجوز دسترسی به ذخیره‌سازی را در زمینه شخص ثالث بررسی کنید، که نشان می‌دهد آیا فراخوانی به document.requestStorageAccess() به طور خودکار اعطا می‌شود یا خیر:

navigator.permissions.query({name: "storage-access"});

از متد `hasStorageAccess()` استفاده کنید

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

// Set a hasAccess boolean variable which defaults to false.
let hasAccess = false;

async function handleCookieAccessInit() {
  if (!document.hasStorageAccess) {
    // Storage Access API is not supported so best we can do is
    // hope it's an older browser that doesn't block 3P cookies.
    hasAccess = true;
  } else {
    // Check whether access has been granted using the Storage Access API.
    // Note on page load this will always be false initially so we could be
    // skipped in this example, but including for completeness for when this
    // is not so obvious.
    hasAccess = await document.hasStorageAccess();
    if (!hasAccess) {
      // Handle the lack of access (covered later)
    }
  }
  if (hasAccess) {
    // Use the cookies.
  }
}
handleCookieAccessInit();

دسترسی به فضای ذخیره سازی تنها پس از فراخوانی requestStorageAccess(), بنابراین hasStorageAccess() همیشه در ابتدا false را برمی گرداند - به جز زمانی که به سندی با منبع مشابه در همان iframe قبلاً دسترسی داده شده باشد. این کمک هزینه در مسیرهای با مبدأ یکسان در داخل iframe حفظ می‌شود تا پس از اعطای دسترسی به صفحاتی که نیاز به وجود کوکی‌ها در درخواست اولیه سند HTML دارند، امکان بارگیری مجدد فراهم شود.

استفاده از `requestStorageAccess()`

اگر iframe دسترسی نداشته باشد، ممکن است نیاز به درخواست دسترسی با استفاده از متد requestStorageAccess() داشته باشد:

if (!hasAccess) {
  try {
    await document.requestStorageAccess();
  } catch (err) {
    // Access was not granted and it may be gated behind an interaction
    return;
  }
}

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

برای جلوگیری از سوء استفاده، این درخواست مرورگر فقط پس از تعامل کاربر نشان داده می شود. به همین دلیل است که requestStorageAccess() در ابتدا باید از یک کنترل کننده رویداد فعال شده توسط کاربر فراخوانی شود، نه بلافاصله با بارگیری iframe:

async function doClick() {

  // Only do this extra check if access hasn't already been given
  // based on the hasAccess variable.
  if (!hasAccess) {
    try {
      await document.requestStorageAccess();
      hasAccess = true; // Can assume this was true if requestStorageAccess() did not reject.
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  if (hasAccess) {
    // Use the cookies
  }
}

document.querySelector('#my-button').addEventListener('click', doClick);

اگر به جای کوکی ها نیاز به استفاده از حافظه محلی دارید، می توانید کارهای زیر را انجام دهید:

let handle = null;

async function doClick() {
  if (!handle) {
    try {
      handle = await document.requestStorageAccess({localStorage: true});
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  // Use handle to access unpartitioned local storage.
  handle.localStorage.setItem('foo', 'bar');
}

document.querySelector('#my-button').addEventListener('click', doClick);

مجوز درخواست می کند

هنگامی که کاربر برای اولین بار روی دکمه کلیک می کند، اعلان مرورگر به طور خودکار در اکثر موارد، معمولاً در نوار آدرس ظاهر می شود. تصویر زیر نمونه ای از درخواست کروم را نشان می دهد، اما سایر مرورگرها رابط کاربری مشابهی دارند:

درخواست مجوز دسترسی API به فضای ذخیره‌سازی Chrome — درخواست مجوز API دسترسی به فضای ذخیره‌سازی Chrome

این درخواست ممکن است توسط مرورگر نادیده گرفته شود و در شرایط خاصی مجوز به طور خودکار ارائه شود:

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

از طرف دیگر، ممکن است این روش به طور خودکار بدون نشان دادن درخواست در شرایط خاص رد شود:

اگر کاربر قبلاً از سایتی که iframe را در اختیار دارد به عنوان یک سند سطح بالا بازدید نکرده باشد و با آن تعامل نداشته باشد، نه در iframe. این بدان معناست که Storage Access API فقط برای سایت‌های تعبیه‌شده که کاربران قبلاً در زمینه شخص اول بازدید کرده‌اند مفید است.
اگر متد requestStorageAccess() خارج از یک رویداد تعامل کاربر بدون تأیید قبلی درخواست پس از یک تعامل فراخوانی شود.

در حالی که در استفاده اولیه از کاربر درخواست می‌شود، بازدیدهای بعدی می‌توانند بدون درخواست و بدون نیاز به تعامل کاربر در کروم و فایرفاکس requestStorageAccess() حل کنند. توجه داشته باشید که سافاری همیشه به تعامل کاربر نیاز دارد.

نکته کلیدی: حتی پس از granted مجوز، به طور خودکار به همه فریم‌ها اجازه دسترسی به کوکی‌ها یا فضای ذخیره‌سازی نشده نمی‌دهد. روش requestStorageAccess() همچنان باید در هر صفحه بارگیری شده توسط هر فریمی که به کوکی‌های پارتیشن نشده یا دسترسی به ذخیره‌سازی نیاز دارد فراخوانی شود. این تضمین می‌کند که قاب فقط زمانی که به کوکی‌ها و فضای ذخیره‌سازی نیاز داشته باشد، دسترسی پیدا می‌کند، نه اینکه اجازه دسترسی به همه فریم‌ها را بدهد.

از آنجایی که ممکن است دسترسی به کوکی و فضای ذخیره‌سازی بدون درخواست یا تعامل کاربر اعطا شود، اغلب ممکن است قبل از تعامل کاربر در مرورگرهایی که از این مورد پشتیبانی می‌کنند (Chrome و Firefox) با فراخوانی requestStorageAccess() در بارگذاری صفحه، دسترسی به کوکی یا فضای ذخیره‌سازی بدون پارتیشن دریافت کنید. این ممکن است به شما امکان دهد فوراً به کوکی‌ها و فضای ذخیره‌سازی پارتیشن نشده دسترسی داشته باشید و تجربه کامل‌تری را حتی قبل از تعامل کاربر با iframe ارائه دهید. این می تواند تجربه کاربری بهتری برای برخی موقعیت ها نسبت به انتظار برای تعامل کاربر باشد.

FedCM به عنوان یک سیگنال اعتماد برای SAA

FedCM (مدیریت اعتبار فدرال) یک رویکرد حفظ حریم خصوصی برای سرویس‌های هویت فدرال (مانند "ورود به سیستم با...") است که به کوکی‌های شخص ثالث یا تغییر مسیرهای ناوبری متکی نیست.

هنگامی که کاربر به یک حزب متکی (RP) وارد می‌شود که دارای محتوای جاسازی‌شده از یک ارائه‌دهنده هویت شخص ثالث (IdP) با FedCM است، محتوای IdP تعبیه‌شده می‌تواند به‌طور خودکار به کوکی‌های پارتیشن نشده سطح بالای خود دسترسی به فضای ذخیره‌سازی داشته باشد. برای فعال کردن دسترسی خودکار به ذخیره سازی با FedCM، این شرایط باید رعایت شود:

احراز هویت FedCM (وضعیت ورود کاربر) باید فعال باشد.
RP با تنظیم مجوز identity-credentials-get مجوز انتخاب کرده است، به عنوان مثال:

<iframe src="https://idp.example" allow="identity-credentials-get"></iframe>

برای مثال، یک iframe idp.example در rp.example تعبیه شده است. وقتی کاربر با FedCM وارد می‌شود، iframe idp.example می‌تواند برای کوکی‌های سطح بالای خود درخواست دسترسی به فضای ذخیره‌سازی کند.

rp.example یک تماس FedCM برای ورود کاربر با ارائه دهنده هویت idp.example برقرار می کند:

// The user will be asked to grant FedCM permission.
const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/fedcm.json',
      clientId: '123',
    }],
  },
});

پس از اینکه کاربر وارد سیستم شد، IdP می تواند requestStorageAccess() از داخل iframe idp.example فراخوانی کند، تا زمانی که RP به صراحت این را با Permissions Policy اجازه داده باشد. جاسازی به طور خودکار به کوکی سطح بالای خود، بدون فعال سازی کاربر یا نیاز به درخواست مجوز دیگر، به فضای ذخیره سازی دسترسی پیدا می کند:

// Make this call within the embedded IdP iframe:

// No user gesture is needed, and the storage access will be auto-granted.
await document.requestStorageAccess();

// This returns `true`.
const hasAccess = await document.hasStorageAccess();

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

بارگیری بعدی با سرصفحه های دسترسی به فضای ذخیره سازی

سرصفحه‌های دسترسی به فضای ذخیره‌سازی یک روش توصیه‌شده و کارآمدتر برای فعال کردن بارگیری محتوای تعبیه‌شده، از جمله منابع غیرiframe است. این ویژگی از Chrome 133 در دسترس است. با سرصفحه‌های دسترسی به فضای ذخیره‌سازی، مرورگر می‌تواند تشخیص دهد که کاربر قبلاً مجوز storage-access را به منبع شخص ثالث در شرایط فعلی داده است و می‌تواند منابع را با دسترسی به کوکی‌های پارتیشن نشده در بازدیدهای بعدی بارگیری کند.

هدر دسترسی به فضای ذخیره سازی جریان دارد

با سربرگ‌های دسترسی به فضای ذخیره‌سازی، بازدیدهای بعدی از صفحات جریان زیر را آغاز می‌کنند:

کاربر قبلاً از website.example بازدید کرده است که یک منبع calendar.example را تعبیه کرده است و با فراخوان document.requestStorageAccess() به storage-access داده است.
کاربر از website.example بازدید می کند که منبع calendar.example را دوباره جاسازی کرده است. این درخواست هنوز مانند قبل به کوکی دسترسی ندارد. با این حال، کاربر قبلاً مجوز storage-access اعطا کرده است و واکشی شامل یک سرصفحه Sec-Fetch-Storage-Access: inactive که نشان می‌دهد دسترسی به کوکی بدون پارتیشن در دسترس است اما فعال نشده است.
سرور calendar.example با یک Activate-Storage-Access: retry; allowed-origin='<origin>' هدر Activate-Storage-Access: retry; allowed-origin='<origin>' (در این مورد، <origin> https://website.example خواهد بود)، برای نشان دادن این که واکشی منبع به استفاده از کوکی‌های پارتیشن نشده با مجوز storage-access نیاز دارد.
مرورگر درخواست را دوباره انجام می‌دهد، این بار شامل کوکی‌های پارتیشن نشده (فعال کردن مجوز storage-access برای این واکشی و واکشی‌های بعدی).
سرور calendar.example با محتوای شخصی‌شده iframe پاسخ می‌دهد. پاسخ شامل یک Activate-Storage-Access: load header است که نشان می دهد مرورگر باید محتوا را با مجوز storage-access فعال بارگیری کند (به عبارت دیگر، بارگیری با دسترسی به کوکی بدون پارتیشن، مثل اینکه document.requestStorageAccess() فراخوانی شده باشد).
عامل کاربر محتوای iframe را با دسترسی به کوکی بدون پارتیشن با استفاده از مجوز storage-access بارگیری می کند. پس از این مرحله، ویجت می تواند همانطور که انتظار می رود کار کند.

فلوچارتی که جریان سربرگ دسترسی به ذخیره سازی را نشان می دهد — نمودار جریان هدر دسترسی به ذخیره سازی.

از هدرهای دسترسی به فضای ذخیره سازی استفاده کنید

جدول زیر سرصفحه های دسترسی به حافظه را فهرست می کند.

جریان	سربرگ	ارزش	توضیحات
درخواست کنید	`Sec-Fetch-Storage-Access` توجه: مرورگر به طور خودکار این سرصفحه را در درخواست‌های بین سایتی که شامل اعتبار می‌شوند ارسال می‌کند (به عنوان مثال، `new Request('request.example', { credentials: 'include' });` ).	`none`	Embed هیچ مجوز دسترسی به فضای ذخیره‌سازی ندارد.
		`inactive`	Embed مجوز دارد، اما از آن استفاده نمی کند. درخواست باید شامل سرصفحه `Origin` نیز باشد.
		`active`	Embed دسترسی به کوکی بدون پارتیشن دارد.
پاسخ	`Activate-Storage-Access`	`load`	به مرورگر دستور می دهد تا به embedder اجازه دسترسی به کوکی های پارتیشن نشده برای منبع درخواستی بدهد. گنجاندن این سربرگ معادل فراخوانی `document.requestStorageAccess()` در صورتی است که مجوز `storage-access` داده شده باشد. این بدان معنی است که هیچ درخواست اضافی به کاربر نمایش داده نخواهد شد.
	`Activate-Storage-Access`	`retry`	به مرورگر دستور می‌دهد تا مجوز دسترسی به ذخیره‌سازی را فعال کند و سپس درخواست را دوباره امتحان کند.
	`allowed-origin`	`<origin>`	مشخص می‌کند که کدام مبدأ مجاز به شروع درخواست‌های اعتبارسنجی است (به عنوان مثال، `https://site.example` یا `*` ).

به عنوان مثال، سربرگ های دسترسی به فضای ذخیره سازی را می توان برای بارگیری تصویر از یک شخص ثالث استفاده کرد:

  // On the client side
  <img src="https://server.example/image">

در این مورد، server.example باید منطق زیر را در سمت سرور پیاده سازی کند:

  app.get('/image', (req, res) => {
  const storageAccessHeader = req.headers['sec-fetch-storage-access'];

  if (storageAccessHeader === 'inactive') {
    // The user needs to grant permission, trigger a prompt

    // Check if the requesting origin is allowed
    // to send credentialed requests to this server.
    // Assuming the `validate_origin(origin)` method is previously defined:
    if (!validate_origin(req.headers.origin)) {
      res.status(401).send(req.headers.origin +
        ' is not allowed to send credentialed requests to this server.');
      return;
    }
    // 'retry' header value indicates that the content load request should be re-sent after the user has granted permissions
    res.set('Activate-Storage-Access', `retry; allowed-origin='${req.headers.origin}'`);
    res.status(401).send('This resource requires storage access. Please grant permission.');
  } else if (storageAccessHeader === 'active') {
    // User has granted permission, proceed with access
    res.set('Activate-Storage-Access', 'load');
    // Include the actual iframe content here
    res.send('This is the content that requires cookie access.');
  } else {
    // Handle other cases (e.g., 'Sec-Fetch-Storage-Access': 'none')
  }
});

نسخه ی نمایشی Storage Access API محتوای شخص ثالث (از جمله تصویر غیر فریم) را با استفاده از سرصفحه های دسترسی به فضای ذخیره سازی جاسازی می کند.

از درخواست مجوز `storage-access` استفاده کنید

برای بررسی اینکه آیا می‌توان دسترسی بدون تعامل کاربر را اعطا کرد، می‌توانید وضعیت مجوز storage-access را بررسی کنید و فقط در صورتی که نیازی به اقدام کاربر نباشد، requestStoreAccess() را زودتر فراخوانی کنید، نه اینکه آن را فراخوانی کنید و در صورت نیاز به تعامل با شکست مواجه شوید.

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

احتیاط: مجوز storage-access در کروم و فایرفاکس پشتیبانی می شود، اما در سافاری پشتیبانی نمی شود. برای کاربران سافاری، تعامل کاربر همیشه مورد نیاز است (به استثنای مورد استفاده خاص از بارگذاری مجدد صفحه پس از اعطای دسترسی).

کد زیر بررسی مجوز storage-access را به مثال قبلی اضافه می کند:

// Set a hasAccess boolean variable which defaults to false except for
// browsers which don't support the API - where we assume
// such browsers also don't block third-party cookies.
let hasAccess = false;

async function hasCookieAccess() {
  // Check if Storage Access API is supported
  if (!document.requestStorageAccess) {
    // Storage Access API is not supported so best we can do is
    // hope it's an older browser that doesn't block 3P cookies.
    return true;
  }

  // Check if access has already been granted
  if (await document.hasStorageAccess()) {
    return true;
  }

  // Check the storage-access permission
  // Wrap this in a try/catch for browsers that support the
  // Storage Access API but not this permission check
  // (e.g. Safari and earlier versions of Firefox).
  let permission;
  try {
    permission = await navigator.permissions.query(
      {name: 'storage-access'}
    );
  } catch (error) {
    // storage-access permission not supported. Assume no cookie access.
    return false;
  }

    if (permission) {
    if (permission.state === 'granted') {
      // Permission has previously been granted so can just call
      // requestStorageAccess() without a user interaction and
      // it will resolve automatically.
      try {
        await document.requestStorageAccess();
        return true;
      } catch (error) {
        // This shouldn't really fail if access is granted, but return false
        // if it does.
        return false;
      }
    } else if (permission.state === 'prompt') {
      // Need to call requestStorageAccess() after a user interaction
      // (potentially with a prompt). Can't do anything further here,
      // so handle this in the click handler.
      return false;
          } else if (permission.state === 'denied') {
            // Not used: see https://github.com/privacycg/storage-access/issues/149
      return false;
          }
    }

  // By default return false, though should really be caught by earlier tests.
  return false;
}

async function handleCookieAccessInit() {
  hasAccess = await hasCookieAccess();

  if (hasAccess) {
    // Use the cookies.
  }
}

handleCookieAccessInit();

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

آیفریم های Sandboxed

هنگام استفاده از Storage Access API در iframes sandboxed ، مجوزهای sandbox زیر مورد نیاز است:

allow-storage-access-by-user-activation لازم است.
allow-scripts برای اجازه دادن به استفاده از جاوا اسکریپت برای فراخوانی API مورد نیاز است.
allow-same-origin برای اجازه دسترسی به کوکی‌های هم منبع و سایر فضای ذخیره‌سازی مورد نیاز است.

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

<iframe sandbox="allow-storage-access-by-user-activation
                 allow-scripts
                 allow-same-origin"
        src="..."></iframe>

الزامات کوکی

برای دسترسی به Storage Access API در کروم، کوکی‌های بین سایتی باید با دو ویژگی زیر تنظیم شوند:

SameSite=None - که برای علامت گذاری کوکی به عنوان متقاطع سایت مورد نیاز است
Secure - که تضمین می کند فقط کوکی های تنظیم شده توسط سایت های HTTPS قابل دسترسی هستند.

در فایرفاکس و سافاری، کوکی‌ها به صورت پیش‌فرض SameSite=None هستند و SAA را به کوکی‌های Secure محدود نمی‌کنند، بنابراین این ویژگی‌ها مورد نیاز نیستند. توصیه می شود در مورد ویژگی SameSite صریح باشید و همیشه از کوکی های Secure استفاده کنید.

دسترسی به صفحه سطح بالا

Storage Access API برای فعال کردن دسترسی به کوکی های شخص ثالث در iframe های تعبیه شده در نظر گرفته شده است.

موارد استفاده دیگری نیز وجود دارد که صفحه سطح بالا نیاز به دسترسی به کوکی های شخص ثالث دارد. به عنوان مثال، تصاویر یا اسکریپت‌هایی که توسط کوکی‌ها محدود شده‌اند، که صاحبان سایت ممکن است بخواهند مستقیماً در سند سطح بالا به جای iframe اضافه کنند. برای رسیدگی به این مورد استفاده، Chrome افزونه‌ای را برای Storage Access API پیشنهاد کرده است که یک متد requestStorageAccessFor() اضافه می‌کند.

متد `requestStorageAccessFor()` .

Browser Support

Source

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

برای جزئیات بیشتر در مورد نحوه استفاده از requestStorageAccessFor() Related Website Sets: developer guide را بخوانید.

درخواست مجوز `top-level-storage-access`

Browser Support

مشابه مجوز storage-access ، یک مجوز top-level-storage-access برای بررسی اینکه آیا می‌توان به requestStorageAccessFor() اعطا کرد، وجود دارد.

Storage Access API هنگام استفاده با RWS چگونه متفاوت است؟

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

	بدون RWS	با RWS
برای شروع درخواست دسترسی به فضای ذخیره‌سازی، به یک اشاره کاربر نیاز دارد
کاربر را ملزم می کند تا قبل از اعطای دسترسی، از منبع ذخیره سازی درخواستی در زمینه سطح بالا بازدید کند
اولین باری که درخواست کاربر را می توان نادیده گرفت
اگر قبلاً دسترسی داده شده باشد، `requestStorageAccess` لازم نیست فراخوانی شود
به طور خودکار به سایر دامنه ها در یک وب سایت مرتبط دسترسی می دهد
از `requestStorageAccessFor` برای دسترسی به صفحه سطح بالا پشتیبانی می کند

تفاوت بین استفاده از Storage Access API بدون و با مجموعه‌های وب‌سایت مرتبط

نسخه ی نمایشی: تنظیم و دسترسی به کوکی ها

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

storage-access-api-demo.glitch.me

نسخه ی نمایشی به مرورگری با کوکی های شخص ثالث غیرفعال نیاز دارد:

Chrome 118 یا بالاتر با مجموعه پرچم chrome://flags/#test-third-party-cookie-phaseout و مرورگر راه اندازی مجدد.
فایرفاکس
سافاری

نسخه ی نمایشی: تنظیم Local Storage

دمو زیر نحوه دسترسی به کانال‌های پخش بدون پارتیشن از iframe شخص ثالث را با استفاده از Storage Access API نشان می‌دهد:

https://saa-beyond-cookies.glitch.me/

نسخه ی نمایشی به Chrome 125 یا بالاتر با پرچم تست شخص ثالث-کوکی-فاصله فعال نیاز دارد.

منابع

مشخصات دسترسی به کوکی شخص ثالث را بخوانید یا مشکلات را دنبال کنید و مطرح کنید.
مشخصاتی که دسترسی به فضای ذخیره‌سازی پارتیشن نشده را فراهم می‌کند را بخوانید یا مشکلات را دنبال کنید و مطرح کنید.
مستندات و راهنمای API.
اسناد Chrome در مورد استفاده از Storage Access API در مجموعه‌های وب‌سایت مرتبط

وضعیت پیاده سازی

Browser Support

Source

کار برای حل و فصل همه مشکلات باقیمانده مسدود کردن قبل از استانداردسازی API ادامه دارد.

Storage Access API چیست؟

موارد استفاده کنید

موارد استفاده عبارتند از:

ویجت‌های کامنت‌گذاری تعبیه‌شده که به جزئیات جلسه ورود نیاز دارند.
دکمه های "پسندیدن" رسانه های اجتماعی که به جزئیات جلسه ورود نیاز دارند.
اسناد جاسازی شده که به جزئیات جلسه ورود نیاز دارند.
تجربه ممتازی که برای جاسازی ویدیو ارائه می‌شود (مثلاً برای نمایش ندادن تبلیغات برای کاربرانی که وارد سیستم شده‌اند، یا برای دانستن ترجیحات کاربر برای زیرنویس‌ها یا محدود کردن انواع خاصی از ویدیو).
سیستم های پرداخت تعبیه شده

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

زمان استفاده از Storage Access API بر روی سایر APIها

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

APIهای جایگزین برای موارد مختلف استفاده وجود دارد:

کوکی‌هایی که دارای وضعیت پارتیشن بندی شده مستقل هستند (CHIPS) به توسعه‌دهندگان اجازه می‌دهد تا یک کوکی را در فضای ذخیره‌سازی «پارتیشن‌بندی‌شده» با یک شیشه کوکی جداگانه برای هر سایت سطح بالا انتخاب کنند. برای مثال، ویجت چت وب شخص ثالث ممکن است به تنظیم یک کوکی برای ذخیره اطلاعات جلسه متکی باشد. اطلاعات جلسه در هر سایت ذخیره می شود، بنابراین کوکی تنظیم شده توسط ویجت نیازی به دسترسی به وب سایت های دیگر که در آن جاسازی شده نیز نیست. Storage Access API زمانی مفید است که یک ویجت شخص ثالث تعبیه شده وابسته به اشتراک گذاری اطلاعات یکسان در منابع مختلف باشد (مثلاً برای جزئیات جلسه وارد شده یا تنظیمات برگزیده).
پارتیشن بندی فضای ذخیره سازی راهی برای iframe های متقابل سایتی است تا از مکانیسم های ذخیره سازی جاوا اسکریپت موجود در حین تقسیم فضای ذخیره سازی در هر سایت استفاده کنند. این مانع از دسترسی به فضای ذخیره سازی جاسازی شده در یک وب سایت توسط همان جاسازی در وب سایت های دیگر می شود.
مجموعه‌های وب‌سایت‌های مرتبط (RWS) راهی است برای سازمان برای اعلام روابط بین سایت‌ها، به طوری که مرورگرها اجازه دسترسی محدود به کوکی‌ها و فضای ذخیره‌سازی را برای اهداف خاص می‌دهند. سایت‌ها همچنان نیاز به درخواست دسترسی با Storage Access API دارند، اما برای سایت‌های موجود در مجموعه، دسترسی می‌تواند بدون درخواست کاربر اعطا شود.
مدیریت اعتبار فدرال (FedCM) یک رویکرد حفظ حریم خصوصی برای خدمات هویتی فدرال است. Storage Access API با دسترسی به کوکی های پارتیشن نشده و ذخیره سازی پس از ورود به سیستم سروکار دارد. برای برخی موارد استفاده، FedCM یک راه حل جایگزین برای Storage Access API ارائه می دهد، و ممکن است ترجیح داده شود زیرا دارای یک درخواست مرورگر با ورود به سیستم است. با این حال، پذیرش FedCM معمولاً به تغییرات اضافی در کد شما نیاز دارد، به عنوان مثال برای پشتیبانی از نقاط پایانی HTTP.
APIهای ضد کلاهبرداری ، مرتبط با تبلیغات و اندازه‌گیری نیز وجود دارند، و API دسترسی به فضای ذخیره‌سازی برای رفع این نگرانی‌ها در نظر گرفته نشده است.

از Storage Access API استفاده کنید

Storage Access API دو روش مبتنی بر وعده دارد:

Document.hasStorageAccess() (همچنین با نام جدید Document.hasUnpartitionedCookieAccess() از Chrome 125 موجود است)
Document.requestStorageAccess()

navigator.permissions.query({name: "storage-access"});

از متد `hasStorageAccess()` استفاده کنید

// Set a hasAccess boolean variable which defaults to false.
let hasAccess = false;

async function handleCookieAccessInit() {
  if (!document.hasStorageAccess) {
    // Storage Access API is not supported so best we can do is
    // hope it's an older browser that doesn't block 3P cookies.
    hasAccess = true;
  } else {
    // Check whether access has been granted using the Storage Access API.
    // Note on page load this will always be false initially so we could be
    // skipped in this example, but including for completeness for when this
    // is not so obvious.
    hasAccess = await document.hasStorageAccess();
    if (!hasAccess) {
      // Handle the lack of access (covered later)
    }
  }
  if (hasAccess) {
    // Use the cookies.
  }
}
handleCookieAccessInit();

استفاده از `requestStorageAccess()`

اگر iframe دسترسی نداشته باشد، ممکن است نیاز به درخواست دسترسی با استفاده از متد requestStorageAccess() داشته باشد:

if (!hasAccess) {
  try {
    await document.requestStorageAccess();
  } catch (err) {
    // Access was not granted and it may be gated behind an interaction
    return;
  }
}

async function doClick() {

  // Only do this extra check if access hasn't already been given
  // based on the hasAccess variable.
  if (!hasAccess) {
    try {
      await document.requestStorageAccess();
      hasAccess = true; // Can assume this was true if requestStorageAccess() did not reject.
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  if (hasAccess) {
    // Use the cookies
  }
}

document.querySelector('#my-button').addEventListener('click', doClick);

اگر به جای کوکی ها نیاز به استفاده از حافظه محلی دارید، می توانید کارهای زیر را انجام دهید:

let handle = null;

async function doClick() {
  if (!handle) {
    try {
      handle = await document.requestStorageAccess({localStorage: true});
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  // Use handle to access unpartitioned local storage.
  handle.localStorage.setItem('foo', 'bar');
}

document.querySelector('#my-button').addEventListener('click', doClick);

مجوز درخواست می کند

این درخواست ممکن است توسط مرورگر نادیده گرفته شود و در شرایط خاصی مجوز به طور خودکار ارائه شود:

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

از طرف دیگر، ممکن است این روش به طور خودکار بدون نشان دادن درخواست در شرایط خاص رد شود:

اگر کاربر قبلاً از سایتی که iframe را در اختیار دارد به عنوان یک سند سطح بالا بازدید نکرده باشد و با آن تعامل نداشته باشد، نه در iframe. این بدان معناست که Storage Access API فقط برای سایت‌های تعبیه‌شده که کاربران قبلاً در زمینه شخص اول بازدید کرده‌اند مفید است.
اگر متد requestStorageAccess() خارج از یک رویداد تعامل کاربر بدون تأیید قبلی درخواست پس از یک تعامل فراخوانی شود.

FedCM به عنوان یک سیگنال اعتماد برای SAA

احراز هویت FedCM (وضعیت ورود کاربر) باید فعال باشد.
RP با تنظیم مجوز identity-credentials-get مجوز انتخاب کرده است، به عنوان مثال:

<iframe src="https://idp.example" allow="identity-credentials-get"></iframe>

rp.example یک تماس FedCM برای ورود کاربر با ارائه دهنده هویت idp.example برقرار می کند:

// The user will be asked to grant FedCM permission.
const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/fedcm.json',
      clientId: '123',
    }],
  },
});

// Make this call within the embedded IdP iframe:

// No user gesture is needed, and the storage access will be auto-granted.
await document.requestStorageAccess();

// This returns `true`.
const hasAccess = await document.hasStorageAccess();

بارگیری بعدی با سرصفحه های دسترسی به فضای ذخیره سازی

هدر دسترسی به فضای ذخیره سازی جریان دارد

با استفاده از هدر دسترسی به ذخیره سازی ، بازدید از صفحات بعدی باعث ایجاد جریان زیر می شود:

کاربر قبلاً از website.example بازدید کرده است. به document.requestStorageAccess() مثال که یک منبع calendar.example storage-access تعبیه کرده است.
کاربر از website.example بازدید می کند. نمونه ای که دارای calendar.example منبع مجدداً تعبیه شده است. این درخواست مانند گذشته هنوز به کوکی دسترسی ندارد. با این حال ، کاربر قبلاً مجوز storage-access را اعطا کرده است ، و Fetch شامل یک Sec-Fetch-Storage-Access: inactive است تا نشان دهد که دسترسی به کوکی های غیرقانونی در دسترس است اما فعال نشده است.
سرور calendar.example با یک Activate-Storage-Access: retry; allowed-origin='<origin>' هدر Activate-Storage-Access: retry; allowed-origin='<origin>' (در این حالت ، <origin> https://website.example ) خواهد بود ، تا نشان دهد که واکشی منابع نیاز به استفاده از کوکی های غیرقابل تصرف با اجازه storage-access دارد.
این مرورگر درخواست را دوباره احیا می کند ، این بار از جمله کوکی های غیرقانونی (فعال کردن مجوز storage-access برای این واکشی و بعد از آن).
سرور calendar.example با محتوای شخصی Iframe پاسخ می دهد. این پاسخ شامل یک Activate-Storage-Access: load ، برای نشان دادن اینکه مرورگر باید محتوا را با مجوز storage-access فعال شده بارگیری کند (به عبارت دیگر ، با دسترسی به کوکی های غیرقانونی بارگذاری شده ، گویی document.requestStorageAccess() فراخوانی شده است).
نماینده کاربر با استفاده از مجوز storage-access محتوای IFRame را با دسترسی به کوکی های غیرقانونی بارگیری می کند. پس از این مرحله ، ویجت می تواند همانطور که انتظار می رود کار کند.

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

از هدر دسترسی به ذخیره سازی استفاده کنید

در جدول زیر عنوان های دسترسی به ذخیره سازی لیست شده است.

جریان	سربرگ	ارزش	توضیحات
درخواست کنید	`Sec-Fetch-Storage-Access` توجه: مرورگر به طور خودکار این عنوان را در درخواست های متقاطع که شامل اعتبارنامه ها است (به عنوان مثال ، `new Request('request.example', { credentials: 'include' });` ) ارسال می کند.	`none`	Embed هیچ مجوز دسترسی به ذخیره سازی ندارد.
		`inactive`	Embed مجوز دارد ، اما از آن استفاده نمی کند. این درخواست همچنین باید شامل عنوان `Origin` باشد.
		`active`	Embed دارای دسترسی به کوکی های غیرقابل تحمل است.
پاسخ	`Activate-Storage-Access`	`load`	به مرورگر دستور می دهد تا دسترسی تعبیه شده به کوکی های بدون نقص را برای منابع درخواست شده اعطا کند. از جمله این هدر معادل تماس با `document.requestStorageAccess()` در صورت اعطای مجوز `storage-access` است. این بدان معنی است که هیچ فوری اضافی به کاربر نمایش داده نمی شود.
	`Activate-Storage-Access`	`retry`	به مرورگر دستور می دهد تا مجوز دسترسی به ذخیره سازی را فعال کرده و سپس درخواست را دوباره امتحان کنید.
	`allowed-origin`	`<origin>`	مشخص می کند که منشأ مجاز به شروع درخواست های معتبر است (به عنوان مثال ، `https://site.example` یا `*` ).

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

  // On the client side
  <img src="https://server.example/image">

در این حالت ، server.example باید منطق زیر را در سمت سرور پیاده سازی کند:

  app.get('/image', (req, res) => {
  const storageAccessHeader = req.headers['sec-fetch-storage-access'];

  if (storageAccessHeader === 'inactive') {
    // The user needs to grant permission, trigger a prompt

    // Check if the requesting origin is allowed
    // to send credentialed requests to this server.
    // Assuming the `validate_origin(origin)` method is previously defined:
    if (!validate_origin(req.headers.origin)) {
      res.status(401).send(req.headers.origin +
        ' is not allowed to send credentialed requests to this server.');
      return;
    }
    // 'retry' header value indicates that the content load request should be re-sent after the user has granted permissions
    res.set('Activate-Storage-Access', `retry; allowed-origin='${req.headers.origin}'`);
    res.status(401).send('This resource requires storage access. Please grant permission.');
  } else if (storageAccessHeader === 'active') {
    // User has granted permission, proceed with access
    res.set('Activate-Storage-Access', 'load');
    // Include the actual iframe content here
    res.send('This is the content that requires cookie access.');
  } else {
    // Handle other cases (e.g., 'Sec-Fetch-Storage-Access': 'none')
  }
});

نسخه ی نمایشی API دسترسی به ذخیره سازی محتوای شخص ثالث (از جمله یک تصویر غیر نمایشی) را با استفاده از هدرهای دسترسی به ذخیره سازی تعبیه می کند.

از پرس و جو اجازه `storage-access` استفاده کنید

برای بررسی اینکه آیا دسترسی بدون تعامل کاربر قابل دسترسی است ، می توانید وضعیت مجوز storage-access را بررسی کنید و فقط در صورت نیاز به اقدام کاربر ، با تماس تلفنی تماس بگیرید requestStoreAccess() .

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

احتیاط: اجازه storage-access در کروم و فایرفاکس پشتیبانی می شود ، اما در سافاری نیست. برای کاربران Safari ، تعامل کاربر همیشه مورد نیاز است (به جز مورد استفاده ویژه یک صفحه بارگیری مجدد پس از دسترسی).

کد زیر بررسی اجازه storage-access را به مثال قبلی اضافه می کند:

// Set a hasAccess boolean variable which defaults to false except for
// browsers which don't support the API - where we assume
// such browsers also don't block third-party cookies.
let hasAccess = false;

async function hasCookieAccess() {
  // Check if Storage Access API is supported
  if (!document.requestStorageAccess) {
    // Storage Access API is not supported so best we can do is
    // hope it's an older browser that doesn't block 3P cookies.
    return true;
  }

  // Check if access has already been granted
  if (await document.hasStorageAccess()) {
    return true;
  }

  // Check the storage-access permission
  // Wrap this in a try/catch for browsers that support the
  // Storage Access API but not this permission check
  // (e.g. Safari and earlier versions of Firefox).
  let permission;
  try {
    permission = await navigator.permissions.query(
      {name: 'storage-access'}
    );
  } catch (error) {
    // storage-access permission not supported. Assume no cookie access.
    return false;
  }

    if (permission) {
    if (permission.state === 'granted') {
      // Permission has previously been granted so can just call
      // requestStorageAccess() without a user interaction and
      // it will resolve automatically.
      try {
        await document.requestStorageAccess();
        return true;
      } catch (error) {
        // This shouldn't really fail if access is granted, but return false
        // if it does.
        return false;
      }
    } else if (permission.state === 'prompt') {
      // Need to call requestStorageAccess() after a user interaction
      // (potentially with a prompt). Can't do anything further here,
      // so handle this in the click handler.
      return false;
          } else if (permission.state === 'denied') {
            // Not used: see https://github.com/privacycg/storage-access/issues/149
      return false;
          }
    }

  // By default return false, though should really be caught by earlier tests.
  return false;
}

async function handleCookieAccessInit() {
  hasAccess = await hasCookieAccess();

  if (hasAccess) {
    // Use the cookies.
  }
}

handleCookieAccessInit();

نکته اصلی: به دلایل حریم خصوصی ، نمی توان گفت که آیا سریع نشان داده شده و رد شده است ، یا بر اساس اکتشافی مرورگر نشان داده نشده است - هر دو به عنوان حالت فعلی حتی در صورت درخواست دوباره prompt می گردند.

iframes sandboxed

هنگام استفاده از API دسترسی به ذخیره سازی در iframes sandboxed ، مجوزهای ماسهبازی زیر مورد نیاز است:

برای دسترسی به API allow-storage-access-by-user-activation استفاده کنید.
برای استفاده از JavaScript برای تماس با API ، allow-scripts استفاده شود.
برای دسترسی به کوکی های همان منبعی و سایر فضای ذخیره سازی ، allow-same-origin

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

<iframe sandbox="allow-storage-access-by-user-activation
                 allow-scripts
                 allow-same-origin"
        src="..."></iframe>

مورد نیاز کوکی

برای دسترسی به API دسترسی به ذخیره سازی در Chrome ، کوکی های متقابل سایت باید با دو ویژگی زیر تنظیم شوند:

SameSite=None - که برای علامت گذاری کوکی به عنوان سایت متقاطع لازم است
Secure - که فقط به کوکی های تعیین شده توسط سایت های HTTPS می توان دسترسی پیدا کرد.

در Firefox و Safari ، کوکی ها به SameSite=None پیش فرض می شوند و SAA را برای Secure کوکی ها محدود نمی کنند ، بنابراین این ویژگی ها لازم نیست. توصیه می شود در مورد ویژگی SameSite صریح و همیشه از کوکی های Secure استفاده کنید.

دسترسی به صفحه سطح بالا

API دسترسی به ذخیره سازی برای امکان دسترسی به کوکی های شخص ثالث در Iframes تعبیه شده در نظر گرفته شده است.

موارد استفاده دیگری نیز وجود دارد که صفحه سطح بالا نیاز به دسترسی به کوکی های شخص ثالث دارد. به عنوان مثال ، تصاویر یا اسکریپت هایی که توسط کوکی ها محدود شده اند ، که صاحبان سایت ممکن است بخواهند مستقیماً در سند سطح بالا قرار بگیرند و نه در یک IFRAME. برای پرداختن به این مورد استفاده ، Chrome یک برنامه افزودنی به API دسترسی به ذخیره سازی را ارائه داده است که یک روش requestStorageAccessFor() را اضافه می کند.

روش `requestStorageAccessFor()`

Browser Support

Source

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

برای اطلاعات بیشتر در مورد نحوه استفاده از requestStorageAccessFor() مجموعه وب سایت مرتبط را بخوانید: راهنمای توسعه دهنده .

پرس و جو مجوز `top-level-storage-access`

Browser Support

مشابه مجوز storage-access ، یک مجوز top-level-storage-access برای بررسی وجود دارد تا بررسی کند که آیا می توان دسترسی را برای requestStorageAccessFor() اعطا کرد.

API دسترسی به ذخیره سازی هنگام استفاده از RWS چگونه متفاوت است؟

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

	بدون RWS	با RWS
برای شروع درخواست دسترسی به ذخیره سازی به یک ژست کاربر نیاز دارد
قبل از اعطای دسترسی ، کاربر را ملزم به بازدید از منشأ ذخیره درخواست شده در یک زمینه سطح بالا می کند
اولین بار سریع کاربر می تواند رد شود
در صورت دسترسی قبلاً `requestStorageAccess` لازم نیست كه فراخوانده شود
به طور خودکار دسترسی به دامنه های دیگر را در یک سایت وب سایت مرتبط اعطا می کند
برای دسترسی به صفحه سطح بالا `requestStorageAccessFor` برای دسترسی پشتیبانی می کند

تفاوت بین استفاده از API دسترسی به ذخیره سازی بدون و با مجموعه های وب سایت مرتبط

نسخه ی نمایشی: تنظیم و دسترسی به کوکی ها

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

ذخیره سازی- ACCESS-API-DEMO.GLITCH.ME

نسخه ی نمایشی به یک مرورگر با کوکی های شخص ثالث غیرفعال نیاز دارد:

Chrome 118 یا بالاتر با chrome://flags/#test-third-party-cookie-phaseout Flag مجموعه و مرورگر راه اندازی مجدد.
فایرفاکس
سافاری

نسخه ی نمایشی: تنظیم فضای محلی

نسخه ی نمایشی زیر نحوه دسترسی به کانال های پخش نشده از یک IFRAME شخص ثالث را با استفاده از API دسترسی به ذخیره سازی نشان می دهد:

https://saa-beyond-cookies.glitch.me/

نسخه ی نمایشی با پرچم تست-سوم-کوکی-فاز فاز تست ، به Chrome 125 یا بالاتر نیاز دارد.

منابع

مشخصات دسترسی به کوکی های شخص ثالث را بخوانید یا مواردی را دنبال کنید و مواردی را دنبال کنید.
مشخصات را که دسترسی به ذخیره سازی غیرقانونی را ارائه می دهد ، بخوانید یا موارد را دنبال کنید.
مستندات و راهنمای API.
مستندات Chrome در مورد استفاده از API دسترسی به ذخیره سازی در مجموعه های وب سایت مرتبط

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

وضعیت پیاده سازی

Browser Support

Source

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

قبل از استاندارد سازی API ، کار برای حل و فصل تمام مسائل مسدود کننده باقی مانده ادامه دارد.

API دسترسی به ذخیره سازی چیست؟

API دسترسی به ذخیره سازی یک API JavaScript است که به Iframes اجازه می دهد مجوزهای دسترسی به ذخیره سازی را درخواست کنند در صورت دسترسی در غیر این صورت توسط تنظیمات مرورگر رد می شوند. تعبیه شده با موارد استفاده که به بارگیری منابع متقاطع بستگی دارد می تواند از API برای درخواست دسترسی به کاربر ، به صورت مورد نیاز استفاده کند.

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

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

موارد استفاده کنید

برخی از تعبیه های شخص ثالث نیاز به دسترسی به کوکی های غیرقانونی یا ذخیره سازی دارند تا تجربه بهتری را به کاربر ارائه دهند-چیزی که در صورت محدود شدن کوکی های شخص ثالث در دسترس نخواهد بود و پارتیشن بندی ذخیره سازی فعال می شود.

موارد استفاده عبارتند از:

ویجت های اظهار نظر تعبیه شده که نیاز به جزئیات جلسه ورود دارند.
دکمه های رسانه های اجتماعی "مانند" که نیاز به جزئیات جلسه ورود دارند.
اسناد تعبیه شده که نیاز به جزئیات جلسه ورود به سیستم دارند.
یک تجربه حق بیمه ارائه شده به یک فیلم تعبیه شده (به عنوان مثال ، برای نشان دادن تبلیغات برای ورود به سیستم در کاربران ، یا دانستن ترجیحات کاربر برای زیرنویس های بسته یا محدود کردن انواع خاص ویدیویی).
سیستم های پرداخت تعبیه شده.

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

چه زمانی از API دسترسی به ذخیره سازی بیش از سایر API ها استفاده کنید

API دسترسی به ذخیره سازی یکی از گزینه های دیگر برای استفاده از کوکی ها و ذخیره سازی های غیرقانونی است ، بنابراین درک این نکته مهم است که چه موقع از این API در مقایسه با سایرین استفاده کنید. این برای مواردی است که هر دو موارد زیر صحیح هستند:

کاربر با محتوای تعبیه شده تعامل خواهد داشت - یعنی ، این یک IFRAME منفعل یا یک Iframe پنهان نیست.
کاربر در یک زمینه سطح بالا از منشأ تعبیه شده بازدید کرده است-یعنی وقتی این مبدا در سایت دیگری تعبیه نشده است.

API های جایگزین برای موارد مختلف استفاده وجود دارد:

کوکی هایی که دارای حالت پارتیشن مستقل (تراشه) هستند ، به توسعه دهندگان این امکان را می دهد تا یک کوکی را برای ذخیره سازی "تقسیم شده" انتخاب کنند ، با یک کوزه کوکی جداگانه در هر سایت سطح بالا. به عنوان مثال ، ویجت چت وب شخص ثالث ممکن است برای ذخیره اطلاعات جلسه به تنظیم یک کوکی متکی باشد. اطلاعات جلسه در هر سایت ذخیره می شود ، بنابراین کوکی تنظیم شده توسط ویجت نیازی به دسترسی به وب سایت های دیگر که در آن نیز تعبیه شده است ، قابل دسترسی نیست. API دسترسی به ذخیره سازی هنگامی مفید است که یک ویجت شخص ثالث تعبیه شده به اشتراک گذاری اطلاعات یکسان در منشأ های مختلف (به عنوان مثال برای جزئیات جلسه وارد شده یا ترجیحات) بستگی دارد.
پارتیشن بندی ذخیره سازی راهی برای iframes در سایت برای استفاده از مکانیسم های ذخیره سازی جاوا اسکریپت موجود در ضمن تقسیم ذخیره سازی زیرین در هر سایت است. این امر مانع از دسترسی به ذخیره سازی در یک وب سایت توسط همان جاسازی شده در وب سایت های دیگر می شود.
مجموعه های وب سایت های مرتبط (RWS) راهی برای یک سازمان برای اعلام روابط بین سایت ها است ، به طوری که مرورگرها اجازه می دهند تا کوکی های محدود و دسترسی به ذخیره سازی را برای اهداف خاص محدود کنند. سایت ها هنوز هم باید با API دسترسی به ذخیره سازی دسترسی داشته باشند ، اما برای سایت های موجود در مجموعه ، می توان بدون اعطای کاربر دسترسی پیدا کرد.
مدیریت اعتبار فدرال (FEDCM) یک رویکرد حفظ حریم خصوصی برای خدمات هویت فدرال است. API دسترسی به ذخیره سازی با دسترسی به کوکی های بدون نقص و ذخیره سازی پس از لوژین سروکار دارد. برای برخی از موارد استفاده FEDCM یک راه حل جایگزین برای API دسترسی به ذخیره سازی ارائه می دهد ، و ممکن است ترجیح داده شود زیرا دارای یک مرورگر مرورگر با ورود بیشتر است. با این حال ، اتخاذ FEDCM معمولاً نیاز به تغییرات اضافی در کد شما دارد ، به عنوان مثال برای پشتیبانی از نقاط پایانی HTTP.
API های ضد کلاهبرداری ، مربوط به تبلیغات و اندازه گیری نیز وجود دارد ، و API دسترسی به ذخیره سازی برای رفع این نگرانی ها در نظر گرفته نشده است.

از API دسترسی به ذخیره سازی استفاده کنید

API دسترسی به ذخیره سازی دارای دو روش مبتنی بر وعده داده شده است:

Document.hasStorageAccess() (همچنین تحت نام جدید Document.hasUnpartitionedCookieAccess() در مورد Chrome 125)
Document.requestStorageAccess()

همچنین با مجوزهای API ادغام می شود. این به شما امکان می دهد وضعیت مجوز دسترسی به ذخیره سازی را در یک زمینه شخص ثالث بررسی کنید ، که نشان می دهد آیا تماس با document.requestStorageAccess() .

navigator.permissions.query({name: "storage-access"});

از روش `hasStorageAccess()` استفاده کنید

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

// Set a hasAccess boolean variable which defaults to false.
let hasAccess = false;

async function handleCookieAccessInit() {
  if (!document.hasStorageAccess) {
    // Storage Access API is not supported so best we can do is
    // hope it's an older browser that doesn't block 3P cookies.
    hasAccess = true;
  } else {
    // Check whether access has been granted using the Storage Access API.
    // Note on page load this will always be false initially so we could be
    // skipped in this example, but including for completeness for when this
    // is not so obvious.
    hasAccess = await document.hasStorageAccess();
    if (!hasAccess) {
      // Handle the lack of access (covered later)
    }
  }
  if (hasAccess) {
    // Use the cookies.
  }
}
handleCookieAccessInit();

دسترسی به ذخیره سازی فقط پس از تماس با requestStorageAccess(), بنابراین hasStorageAccess() همیشه در ابتدا کاذب را باز می گرداند-به جز هنگامی که یک سند همان منبعی دیگر در همان Iframe قبلاً دسترسی داشته باشد. این کمک هزینه در سراسر ناوبری های همان منبعی در داخل Iframe حفظ می شود تا پس از اعطای دسترسی به صفحاتی که نیاز به کوکی ها دارند ، در درخواست اولیه سند HTML وجود داشته باشد ، بارگیری مجدد را فراهم می کند.

استفاده از `requestStorageAccess()`

اگر Iframe دسترسی نداشته باشد ، ممکن است با استفاده از روش requestStorageAccess() نیاز به دسترسی داشته باشد:

if (!hasAccess) {
  try {
    await document.requestStorageAccess();
  } catch (err) {
    // Access was not granted and it may be gated behind an interaction
    return;
  }
}

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

برای جلوگیری از سوءاستفاده ، این فوری مرورگر فقط پس از تعامل کاربر نشان داده می شود. به همین دلیل است که در ابتدا باید از یک کنترل کننده رویداد فعال شده توسط کاربر requestStorageAccess() شود ، نه اینکه بلافاصله به عنوان Iframe بارهای خود را فراخوانی کنید:

async function doClick() {

  // Only do this extra check if access hasn't already been given
  // based on the hasAccess variable.
  if (!hasAccess) {
    try {
      await document.requestStorageAccess();
      hasAccess = true; // Can assume this was true if requestStorageAccess() did not reject.
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  if (hasAccess) {
    // Use the cookies
  }
}

document.querySelector('#my-button').addEventListener('click', doClick);

اگر نیاز به استفاده از فضای محلی به جای کوکی ها دارید ، می توانید موارد زیر را انجام دهید:

let handle = null;

async function doClick() {
  if (!handle) {
    try {
      handle = await document.requestStorageAccess({localStorage: true});
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  // Use handle to access unpartitioned local storage.
  handle.localStorage.setItem('foo', 'bar');
}

document.querySelector('#my-button').addEventListener('click', doClick);

مجوزها

هنگامی که کاربر برای اولین بار روی دکمه کلیک می کند ، سریع مرورگر در بیشتر موارد ، به طور معمول در نوار آدرس ، به طور خودکار ظاهر می شود. تصویر زیر نمونه ای از سریع Chrome را نشان می دهد ، اما مرورگرهای دیگر UI مشابه دارند:

مجوز دسترسی API ذخیره سازی Chrome — مجوز API API CHROME ACCESS API

سریع ممکن است توسط مرورگر و مجوز به طور خودکار در شرایط خاص رد شود:

اگر از صفحه و iframe در 30 روز گذشته پس از پذیرش سریع استفاده شده است.
اگر Iframe تعبیه شده بخشی از یک مجموعه وب سایت مرتبط است.
اگر از FEDCM به عنوان یک سیگنال اعتماد برای دسترسی به ذخیره استفاده می شود.
در Firefox ، سریع برای وب سایت های شناخته شده (آنهایی که در سطح بالا با آنها تعامل کرده اید) برای پنج تلاش اول از بین می رود.

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

اگر کاربر قبلاً با سایتی که صاحب Iframe به عنوان یک سند سطح بالا است ، بازدید نکرده و در تعامل بوده است ، نه در یک IFRAME. این بدان معناست که API دسترسی به ذخیره سازی فقط برای سایتهای تعبیه شده که کاربران قبلاً در یک زمینه شخص اول از آن بازدید کرده اند ، مفید است.
اگر روش requestStorageAccess() خارج از یک رویداد تعامل کاربر بدون تأیید قبلی از سریع پس از تعامل خوانده شود.

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

نکته اصلی: حتی پس از granted مجوز ، این امر به طور خودکار به تمام فریم ها دسترسی به کوکی های بدون تقسیم یا ذخیره سازی نمی دهد. روش requestStorageAccess() هنوز هم باید در هر صفحه توسط هر فریم که نیاز به کوکی های بدون تقسیم یا دسترسی به ذخیره سازی دارد ، فراخوانی شود. این تضمین می کند که این قاب فقط به جای دسترسی به همه فریم ها ، دسترسی به کوکی ها و ذخیره سازی را در هنگام نیاز به آنها دریافت می کند.

از آنجا که ممکن است کوکی و دسترسی به ذخیره سازی بدون تعامل سریع یا تعامل کاربر اعطا شود ، اغلب می توانید قبل از تعامل کاربر در مرورگرهایی که از این (Chrome و Firefox) پشتیبانی می کنند ، با تماس با requestStorageAccess() در بار صفحه ، دسترسی به کوکی یا دسترسی به ذخیره سازی را بدست آورید. این ممکن است به شما امکان دهد بلافاصله به کوکی ها و ذخیره سازی های غیرقانونی دسترسی پیدا کرده و تجربه ای کامل تر را ارائه دهید ، حتی قبل از اینکه کاربر با IFRAME تعامل داشته باشد. این می تواند یک تجربه کاربری بهتر برای برخی از موقعیت ها از انتظار برای تعامل کاربر باشد.

FEDCM به عنوان یک سیگنال اعتماد برای SAA

FEDCM (مدیریت اعتبار فدرال) یک رویکرد حفظ حریم خصوصی برای خدمات هویت فدرال (مانند "ورود به سیستم با ...") است که به کوکی های شخص ثالث یا تغییر مسیر ناوبری متکی نیست.

هنگامی که یک کاربر به یک طرف متکی (RP) وارد می شود که دارای برخی محتوای تعبیه شده از ارائه دهنده هویت شخص ثالث (IDP) با FEDCM است ، محتوای IDP تعبیه شده می تواند به طور خودکار دسترسی به کلوچه های سطح بالایی خود را به دست آورد. برای فعال کردن دسترسی به ذخیره سازی خودکار با FEDCM ، این شرایط باید برآورده شود:

احراز هویت FEDCM (وضعیت ورود به سیستم کاربر) باید فعال باشد.
RP با تنظیم مجوز identity-credentials-get به عنوان مثال ، انتخاب کرده است:

<iframe src="https://idp.example" allow="identity-credentials-get"></iframe>

به عنوان مثال ، یک idp.example IFRAME در rp.example تعبیه شده است. هنگامی که کاربر با FEDCM وارد سیستم می شود ، idp.example Iframe می تواند برای کوکی های سطح بالا خود دسترسی به ذخیره سازی را درخواست کند.

rp.example یک تماس FEDCM برای ورود کاربر با ارائه دهنده هویت idp.example ایجاد می کند:

// The user will be asked to grant FedCM permission.
const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/fedcm.json',
      clientId: '123',
    }],
  },
});

پس از ورود کاربر ، IDP می تواند از طریق idp.example Iframe با requestStorageAccess() تماس بگیرد ، تا زمانی که RP صریحاً این کار را با خط مشی مجوز مجاز داشته باشد. تعبیه شده به طور خودکار دسترسی به ذخیره سازی به کوکی سطح بالا ، بدون فعال سازی کاربر یا نیاز به مجوز دیگر اعطا می شود:

// Make this call within the embedded IdP iframe:

// No user gesture is needed, and the storage access will be auto-granted.
await document.requestStorageAccess();

// This returns `true`.
const hasAccess = await document.hasStorageAccess();

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

بارگیری بعدی با هدر دسترسی به ذخیره سازی

هدرهای دسترسی به ذخیره سازی یک روش توصیه شده و عملکردی تر برای فعال کردن بارگیری محتوای تعبیه شده از جمله منابع غیر نام است. این ویژگی از Chrome 133 در دسترس است. با استفاده از هدرهای دسترسی به ذخیره سازی ، مرورگر می تواند تشخیص دهد که کاربر قبلاً مجوز storage-access را به منشأ شخص ثالث در متن فعلی اعطا کرده است ، و می تواند با دسترسی به کوکی های غیرقانونی در بازدیدهای بعدی ، منابع را بارگیری کند.

هدر دسترسی به ذخیره سازی جریان دارد

با استفاده از هدر دسترسی به ذخیره سازی ، بازدید از صفحات بعدی باعث ایجاد جریان زیر می شود:

کاربر قبلاً از website.example بازدید کرده است. به document.requestStorageAccess() مثال که یک منبع calendar.example storage-access تعبیه کرده است.
کاربر از website.example بازدید می کند. نمونه ای که دارای calendar.example منبع مجدداً تعبیه شده است. این درخواست مانند گذشته هنوز به کوکی دسترسی ندارد. با این حال ، کاربر قبلاً مجوز storage-access را اعطا کرده است ، و Fetch شامل یک Sec-Fetch-Storage-Access: inactive است تا نشان دهد که دسترسی به کوکی های غیرقانونی در دسترس است اما فعال نشده است.
سرور calendar.example با یک Activate-Storage-Access: retry; allowed-origin='<origin>' هدر Activate-Storage-Access: retry; allowed-origin='<origin>' (در این حالت ، <origin> https://website.example ) خواهد بود ، تا نشان دهد که واکشی منابع نیاز به استفاده از کوکی های غیرقابل تصرف با اجازه storage-access دارد.
این مرورگر درخواست را دوباره احیا می کند ، این بار از جمله کوکی های غیرقانونی (فعال کردن مجوز storage-access برای این واکشی و بعد از آن).
سرور calendar.example با محتوای شخصی Iframe پاسخ می دهد. این پاسخ شامل یک Activate-Storage-Access: load ، برای نشان دادن اینکه مرورگر باید محتوا را با مجوز storage-access فعال شده بارگیری کند (به عبارت دیگر ، با دسترسی به کوکی های غیرقانونی بارگذاری شده ، گویی document.requestStorageAccess() فراخوانی شده است).
نماینده کاربر با استفاده از مجوز storage-access محتوای IFRame را با دسترسی به کوکی های غیرقانونی بارگیری می کند. پس از این مرحله ، ویجت می تواند همانطور که انتظار می رود کار کند.

از هدر دسترسی به ذخیره سازی استفاده کنید

در جدول زیر عنوان های دسترسی به ذخیره سازی لیست شده است.

جریان	سربرگ	ارزش	توضیحات
درخواست کنید	`Sec-Fetch-Storage-Access` توجه: مرورگر به طور خودکار این عنوان را در درخواست های متقاطع که شامل اعتبارنامه ها است (به عنوان مثال ، `new Request('request.example', { credentials: 'include' });` ) ارسال می کند.	`none`	Embed هیچ مجوز دسترسی به ذخیره سازی ندارد.
		`inactive`	Embed مجوز دارد ، اما از آن استفاده نمی کند. این درخواست همچنین باید شامل عنوان `Origin` باشد.
		`active`	Embed دارای دسترسی به کوکی های غیرقابل تحمل است.
پاسخ	`Activate-Storage-Access`	`load`	به مرورگر دستور می دهد تا دسترسی تعبیه شده به کوکی های بدون نقص را برای منابع درخواست شده اعطا کند. از جمله این هدر معادل تماس با `document.requestStorageAccess()` در صورت اعطای مجوز `storage-access` است. این بدان معنی است که هیچ فوری اضافی به کاربر نمایش داده نمی شود.
	`Activate-Storage-Access`	`retry`	به مرورگر دستور می دهد تا مجوز دسترسی به ذخیره سازی را فعال کرده و سپس درخواست را دوباره امتحان کنید.
	`allowed-origin`	`<origin>`	مشخص می کند که منشأ مجاز به شروع درخواست های معتبر است (به عنوان مثال ، `https://site.example` یا `*` ).

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

  // On the client side
  <img src="https://server.example/image">

در این حالت ، server.example باید منطق زیر را در سمت سرور پیاده سازی کند:

  app.get('/image', (req, res) => {
  const storageAccessHeader = req.headers['sec-fetch-storage-access'];

  if (storageAccessHeader === 'inactive') {
    // The user needs to grant permission, trigger a prompt

    // Check if the requesting origin is allowed
    // to send credentialed requests to this server.
    // Assuming the `validate_origin(origin)` method is previously defined:
    if (!validate_origin(req.headers.origin)) {
      res.status(401).send(req.headers.origin +
        ' is not allowed to send credentialed requests to this server.');
      return;
    }
    // 'retry' header value indicates that the content load request should be re-sent after the user has granted permissions
    res.set('Activate-Storage-Access', `retry; allowed-origin='${req.headers.origin}'`);
    res.status(401).send('This resource requires storage access. Please grant permission.');
  } else if (storageAccessHeader === 'active') {
    // User has granted permission, proceed with access
    res.set('Activate-Storage-Access', 'load');
    // Include the actual iframe content here
    res.send('This is the content that requires cookie access.');
  } else {
    // Handle other cases (e.g., 'Sec-Fetch-Storage-Access': 'none')
  }
});

از پرس و جو اجازه `storage-access` استفاده کنید

کد زیر بررسی اجازه storage-access را به مثال قبلی اضافه می کند:

// Set a hasAccess boolean variable which defaults to false except for
// browsers which don't support the API - where we assume
// such browsers also don't block third-party cookies.
let hasAccess = false;

async function hasCookieAccess() {
  // Check if Storage Access API is supported
  if (!document.requestStorageAccess) {
    // Storage Access API is not supported so best we can do is
    // hope it's an older browser that doesn't block 3P cookies.
    return true;
  }

  // Check if access has already been granted
  if (await document.hasStorageAccess()) {
    return true;
  }

  // Check the storage-access permission
  // Wrap this in a try/catch for browsers that support the
  // Storage Access API but not this permission check
  // (e.g. Safari and earlier versions of Firefox).
  let permission;
  try {
    permission = await navigator.permissions.query(
      {name: 'storage-access'}
    );
  } catch (error) {
    // storage-access permission not supported. Assume no cookie access.
    return false;
  }

    if (permission) {
    if (permission.state === 'granted') {
      // Permission has previously been granted so can just call
      // requestStorageAccess() without a user interaction and
      // it will resolve automatically.
      try {
        await document.requestStorageAccess();
        return true;
      } catch (error) {
        // This shouldn't really fail if access is granted, but return false
        // if it does.
        return false;
      }
    } else if (permission.state === 'prompt') {
      // Need to call requestStorageAccess() after a user interaction
      // (potentially with a prompt). Can't do anything further here,
      // so handle this in the click handler.
      return false;
          } else if (permission.state === 'denied') {
            // Not used: see https://github.com/privacycg/storage-access/issues/149
      return false;
          }
    }

  // By default return false, though should really be caught by earlier tests.
  return false;
}

async function handleCookieAccessInit() {
  hasAccess = await hasCookieAccess();

  if (hasAccess) {
    // Use the cookies.
  }
}

handleCookieAccessInit();

iframes sandboxed

هنگام استفاده از API دسترسی به ذخیره سازی در iframes sandboxed ، مجوزهای ماسهبازی زیر مورد نیاز است:

برای دسترسی به API allow-storage-access-by-user-activation استفاده کنید.
برای استفاده از JavaScript برای تماس با API ، allow-scripts استفاده شود.
برای دسترسی به کوکی های همان منبعی و سایر فضای ذخیره سازی ، allow-same-origin

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

<iframe sandbox="allow-storage-access-by-user-activation
                 allow-scripts
                 allow-same-origin"
        src="..."></iframe>

مورد نیاز کوکی

برای دسترسی به API دسترسی به ذخیره سازی در Chrome ، کوکی های متقابل سایت باید با دو ویژگی زیر تنظیم شوند:

SameSite=None - که برای علامت گذاری کوکی به عنوان سایت متقاطع لازم است
Secure - که فقط به کوکی های تعیین شده توسط سایت های HTTPS می توان دسترسی پیدا کرد.

دسترسی به صفحه سطح بالا

API دسترسی به ذخیره سازی برای امکان دسترسی به کوکی های شخص ثالث در Iframes تعبیه شده در نظر گرفته شده است.

روش `requestStorageAccessFor()`

Browser Support

Source

پرس و جو مجوز `top-level-storage-access`

Browser Support

API دسترسی به ذخیره سازی هنگام استفاده از RWS چگونه متفاوت است؟

	بدون RWS	با RWS
برای شروع درخواست دسترسی به ذخیره سازی به یک ژست کاربر نیاز دارد
قبل از اعطای دسترسی ، کاربر را ملزم به بازدید از منشأ ذخیره درخواست شده در یک زمینه سطح بالا می کند
اولین بار سریع کاربر می تواند رد شود
در صورت دسترسی قبلاً `requestStorageAccess` لازم نیست كه فراخوانده شود
به طور خودکار دسترسی به دامنه های دیگر را در یک سایت وب سایت مرتبط اعطا می کند
برای دسترسی به صفحه سطح بالا `requestStorageAccessFor` برای دسترسی پشتیبانی می کند

تفاوت بین استفاده از API دسترسی به ذخیره سازی بدون و با مجموعه های وب سایت مرتبط

نسخه ی نمایشی: تنظیم و دسترسی به کوکی ها

ذخیره سازی- ACCESS-API-DEMO.GLITCH.ME

نسخه ی نمایشی به یک مرورگر با کوکی های شخص ثالث غیرفعال نیاز دارد:

Chrome 118 یا بالاتر با chrome://flags/#test-third-party-cookie-phaseout Flag مجموعه و مرورگر راه اندازی مجدد.
فایرفاکس
سافاری

نسخه ی نمایشی: تنظیم فضای محلی

https://saa-beyond-cookies.glitch.me/

نسخه ی نمایشی با پرچم تست-سوم-کوکی-فاز فاز تست ، به Chrome 125 یا بالاتر نیاز دارد.

منابع

مشخصات دسترسی به کوکی های شخص ثالث را بخوانید یا مواردی را دنبال کنید و مواردی را دنبال کنید.
مشخصات را که دسترسی به ذخیره سازی غیرقانونی را ارائه می دهد ، بخوانید یا موارد را دنبال کنید.
مستندات و راهنمای API.
مستندات Chrome در مورد استفاده از API دسترسی به ذخیره سازی در مجموعه های وب سایت مرتبط

وضعیت پیاده سازی

Browser Support

Source

قبل از استاندارد سازی API ، کار برای حل و فصل تمام مسائل مسدود کننده باقی مانده ادامه دارد.

API دسترسی به ذخیره سازی چیست؟

موارد استفاده کنید

موارد استفاده عبارتند از:

ویجت های اظهار نظر تعبیه شده که نیاز به جزئیات جلسه ورود دارند.
دکمه های رسانه های اجتماعی "مانند" که نیاز به جزئیات جلسه ورود دارند.
اسناد تعبیه شده که نیاز به جزئیات جلسه ورود به سیستم دارند.
یک تجربه حق بیمه ارائه شده به یک فیلم تعبیه شده (به عنوان مثال ، برای نشان دادن تبلیغات برای ورود به سیستم در کاربران ، یا دانستن ترجیحات کاربر برای زیرنویس های بسته یا محدود کردن انواع خاص ویدیویی).
سیستم های پرداخت تعبیه شده.

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

چه زمانی از API دسترسی به ذخیره سازی بیش از سایر API ها استفاده کنید

کاربر با محتوای تعبیه شده تعامل خواهد داشت - یعنی ، این یک IFRAME منفعل یا یک Iframe پنهان نیست.
کاربر در یک زمینه سطح بالا از منشأ تعبیه شده بازدید کرده است-یعنی وقتی این مبدا در سایت دیگری تعبیه نشده است.

API های جایگزین برای موارد مختلف استفاده وجود دارد:

کوکی هایی که دارای حالت پارتیشن مستقل (تراشه) هستند ، به توسعه دهندگان این امکان را می دهد تا یک کوکی را برای ذخیره سازی "تقسیم شده" انتخاب کنند ، با یک کوزه کوکی جداگانه در هر سایت سطح بالا. به عنوان مثال ، ویجت چت وب شخص ثالث ممکن است برای ذخیره اطلاعات جلسه به تنظیم یک کوکی متکی باشد. اطلاعات جلسه در هر سایت ذخیره می شود ، بنابراین کوکی تنظیم شده توسط ویجت نیازی به دسترسی به وب سایت های دیگر که در آن نیز تعبیه شده است ، قابل دسترسی نیست. API دسترسی به ذخیره سازی هنگامی مفید است که یک ویجت شخص ثالث تعبیه شده به اشتراک گذاری اطلاعات یکسان در منشأ های مختلف (به عنوان مثال برای جزئیات جلسه وارد شده یا ترجیحات) بستگی دارد.
پارتیشن بندی ذخیره سازی راهی برای iframes در سایت برای استفاده از مکانیسم های ذخیره سازی جاوا اسکریپت موجود در ضمن تقسیم ذخیره سازی زیرین در هر سایت است. This prevents embedded storage in one website from being accessed by the same embed on other websites.
Related Websites Sets (RWS) is a way for an organization to declare relationships among sites, so that browsers allow limited unpartitioned cookie and storage access for specific purposes. Sites still need to request access with the Storage Access API, but for sites within the set, access can be granted without user prompts.
Federated Credential Management (FedCM) is a privacy-preserving approach to federated identity services. The Storage Access API deals with accessing unpartitioned cookies and storage post-login. For some use cases FedCM provides an alternative solution to the Storage Access API, and may be preferable as it features a more login-oriented browser prompt. However, adopting FedCM usually requires additional changes to your code, for example to support its HTTP endpoints.
Anti-fraud , ad-related , and measurement APIs also exist, and the Storage Access API is not intended to address those concerns.

Use the Storage Access API

The Storage Access API has two promised-based methods:

Document.hasStorageAccess() (also available under the new name Document.hasUnpartitionedCookieAccess() as of Chrome 125)
Document.requestStorageAccess()

It also integrates with the Permissions API . This lets you check the status of the storage-access permission in a third-party context, which indicates whether a call to document.requestStorageAccess() would be automatically granted:

navigator.permissions.query({name: "storage-access"});

Use the `hasStorageAccess()` method

When a site first loads, it can use the hasStorageAccess() method to check whether access to third-party cookies has already been granted.

// Set a hasAccess boolean variable which defaults to false.
let hasAccess = false;

async function handleCookieAccessInit() {
  if (!document.hasStorageAccess) {
    // Storage Access API is not supported so best we can do is
    // hope it's an older browser that doesn't block 3P cookies.
    hasAccess = true;
  } else {
    // Check whether access has been granted using the Storage Access API.
    // Note on page load this will always be false initially so we could be
    // skipped in this example, but including for completeness for when this
    // is not so obvious.
    hasAccess = await document.hasStorageAccess();
    if (!hasAccess) {
      // Handle the lack of access (covered later)
    }
  }
  if (hasAccess) {
    // Use the cookies.
  }
}
handleCookieAccessInit();

Storage access is only granted to an iframe document after it calls requestStorageAccess(), so hasStorageAccess() will always return false initially—except when another same-origin document in the same iframe had already been granted access. The grant is preserved across same-origin navigations inside the iframe specifically to allow reloads after granting access for pages that require cookies to be present in the initial request for the HTML document.

Use `requestStorageAccess()`

If the iframe does not have access it may need to request access using the requestStorageAccess() method:

if (!hasAccess) {
  try {
    await document.requestStorageAccess();
  } catch (err) {
    // Access was not granted and it may be gated behind an interaction
    return;
  }
}

The first time this is requested, the user may need to approve this access with a browser prompt, after which the promise will resolve, or will reject resulting in an exception if await is used.

To prevent abuse, this browser prompt will only be shown after a user interaction. That's why requestStorageAccess() initially needs to be called from a user-activated event handler, rather than immediately as the iframe loads:

async function doClick() {

  // Only do this extra check if access hasn't already been given
  // based on the hasAccess variable.
  if (!hasAccess) {
    try {
      await document.requestStorageAccess();
      hasAccess = true; // Can assume this was true if requestStorageAccess() did not reject.
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  if (hasAccess) {
    // Use the cookies
  }
}

document.querySelector('#my-button').addEventListener('click', doClick);

If you need to use local storage instead of cookies, you could do the following:

let handle = null;

async function doClick() {
  if (!handle) {
    try {
      handle = await document.requestStorageAccess({localStorage: true});
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  // Use handle to access unpartitioned local storage.
  handle.localStorage.setItem('foo', 'bar');
}

document.querySelector('#my-button').addEventListener('click', doClick);

Permission prompts

When the user clicks the button for the first time, the browser prompt will automatically appear in most cases, typically in the address bar. The following screenshot shows an example of Chrome's prompt, but other browsers have a similar UI:

Chrome Storage Access API permission prompt — Chrome's Storage Access API permission prompt

The prompt may be skipped by the browser and permission automatically provided in certain circumstances:

If the page and iframe have been used in the last 30 days after accepting the prompt.
If the embedded iframe is part of a Related Website Set .
If FedCM is used as a trust signal for storage access.
In Firefox, the prompt is also skipped for known websites (those you have interacted with at the top level) for the first five attempts.

Alternatively, the method may be automatically rejected without showing the prompt in certain circumstances:

If the user has not previously visited and interacted with the site that owns the iframe as a top-level document, not in an iframe. This means the Storage Access API is only useful for embedded sites that users have previously visited in a first-party context.
If the requestStorageAccess() method is called outside of a user interaction event without prior approval of the prompt after an interaction.

While the user will be prompted on the initial use, subsequent visits can resolve requestStorageAccess() without a prompt and without requiring user interaction in Chrome and Firefox. Note that Safari always requires a user interaction.

Key point: Even once the permission is granted , that does not automatically give all frames access to unpartitioned cookies or storage. The requestStorageAccess() method must still be called on each page load by each frame that requires unpartitioned cookies or storage access. This ensures the frame only receives access to cookies and storage when it needs them, rather than granting access to all frames.

As cookie and storage access may be granted without a prompt, or user interaction, it is often possible to get unpartitioned cookie or storage access before a user interaction on browsers that support this (Chrome and Firefox) by calling requestStorageAccess() on page load. This may allow you to access unpartitioned cookies and storage immediately and provide a fuller experience, even before the user interacts with the iframe. This can be a better user experience for some situations than waiting for user interaction.

FedCM as a trust signal for SAA

FedCM (Federated Credential Management) is a privacy-preserving approach to federated identity services (such as "Sign in with...") that doesn't rely on third-party cookies or navigational redirects.

When a user logs in to a Relying Party (RP) that has some embedded content from a third-party identity provider (IdP) with FedCM, the embedded IdP content can automatically get storage access to its own top-level unpartitioned cookies. To enable automatic storage access with FedCM, these conditions must be met:

The FedCM authentication (the user sign-in state) must be active.
The RP has opted in by setting the identity-credentials-get permission, for example:

<iframe src="https://idp.example" allow="identity-credentials-get"></iframe>

For example, an idp.example iframe is embedded in rp.example . When the user logs in with FedCM, the idp.example iframe can request storage access for its own top-level cookies.

The rp.example makes a FedCM call to log the user in with the identity provider idp.example :

// The user will be asked to grant FedCM permission.
const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/fedcm.json',
      clientId: '123',
    }],
  },
});

After the user logs in, IdP can call requestStorageAccess() from within the idp.example iframe, as long as the RP has explicitly allowed this with Permissions Policy . The embed will be automatically granted storage access to its own top-level cookie, without user activation or the need for another permission prompt :

// Make this call within the embedded IdP iframe:

// No user gesture is needed, and the storage access will be auto-granted.
await document.requestStorageAccess();

// This returns `true`.
const hasAccess = await document.hasStorageAccess();

The permission will be auto-granted only as long as the user is signed in with FedCM. Once the authentication is inactive, standard SAA requirements apply to grant storage access.

Subsequent loading with Storage Access Headers

Storage Access Headers is a recommended, more performant way to enable loading of embedded content, including non-iframe resources. The feature is available from Chrome 133. With Storage Access Headers, the browser can recognize when the user has already granted storage-access permission to the third-party origin in the current context, and can load resources with access to unpartitioned cookies during subsequent visits.

Storage access headers flow

With Storage Access Headers, the subsequent pages visits will trigger the following flow:

The user has previously visited website.example that embeds a calendar.example resource and granted storage-access with the document.requestStorageAccess() call .
The user visits website.example that has the calendar.example resource embedded again . This request doesn't yet have access to the cookie, as before. However, the user has previously granted storage-access permission, and the fetch includes a Sec-Fetch-Storage-Access: inactive header, to indicate that unpartitioned cookie access is available but not activated.
The calendar.example server responds with an Activate-Storage-Access: retry; allowed-origin='<origin>' header (in this case, <origin> would be https://website.example ), to indicate that the resource fetch requires the use of unpartitioned cookies with the storage-access permission.
The browser retries the request, this time including unpartitioned cookies (activating the storage-access permission for this fetch and subsequent fetches).
The calendar.example server responds with the personalized iframe content. The response includes an Activate-Storage-Access: load header, to indicate that the browser should load the content with the storage-access permission activated (in other words, load with unpartitioned cookie access, as if document.requestStorageAccess() had been called).
The user agent loads the iframe content with unpartitioned cookie access using the storage-access permission. After this step, the widget can work as expected.

A flowchart illustrating the Storage Access Header flow — Storage Access Header flow diagram.

Use storage access headers

The following table lists Storage Access headers.

جریان	سربرگ	ارزش	توضیحات
درخواست کنید	`Sec-Fetch-Storage-Access` Note: The browser automatically sends this header in cross-site requests that include credentials (for example, `new Request('request.example', { credentials: 'include' });` ).	`none`	Embed has no storage access permission.
		`inactive`	Embed has permission, but isn't using it. The request must also include the `Origin` header.
		`active`	Embed has unpartitioned cookie access.
پاسخ	`Activate-Storage-Access`	`load`	Instructs the browser to grant the embedder access to unpartitioned cookies for the requested resource. Including this header is equivalent to calling `document.requestStorageAccess()` if the `storage-access` permission has been granted. This means that no additional prompt will be displayed to the user.
	`Activate-Storage-Access`	`retry`	Instructs the browser to activate the storage-access permission, and then retry the request.
	`allowed-origin`	`<origin>`	Specifies which origin is allowed to initiate credentialed requests (eg, `https://site.example` or `*` ).

For example, Storage Access Headers can be used to load an image image from a third-party:

  // On the client side
  <img src="https://server.example/image">

In this case, server.example should implement the following logic on the server side:

  app.get('/image', (req, res) => {
  const storageAccessHeader = req.headers['sec-fetch-storage-access'];

  if (storageAccessHeader === 'inactive') {
    // The user needs to grant permission, trigger a prompt

    // Check if the requesting origin is allowed
    // to send credentialed requests to this server.
    // Assuming the `validate_origin(origin)` method is previously defined:
    if (!validate_origin(req.headers.origin)) {
      res.status(401).send(req.headers.origin +
        ' is not allowed to send credentialed requests to this server.');
      return;
    }
    // 'retry' header value indicates that the content load request should be re-sent after the user has granted permissions
    res.set('Activate-Storage-Access', `retry; allowed-origin='${req.headers.origin}'`);
    res.status(401).send('This resource requires storage access. Please grant permission.');
  } else if (storageAccessHeader === 'active') {
    // User has granted permission, proceed with access
    res.set('Activate-Storage-Access', 'load');
    // Include the actual iframe content here
    res.send('This is the content that requires cookie access.');
  } else {
    // Handle other cases (e.g., 'Sec-Fetch-Storage-Access': 'none')
  }
});

The Storage Access API demo embeds third-party content (including a non-iframe image) using Storage Access Headers.

Use the `storage-access` permission query

To check whether access can be granted without a user interaction, you can check the status of the storage-access permission and only make the requestStoreAccess() call early if no user action is required, rather than call it and have it fail when an interaction is required.

This also lets you potentially handle the need for a prompt upfront by displaying different content—for example, a login button.

Caution: The storage-access permission is supported in Chrome and Firefox, but not in Safari. For Safari users, a user interaction is always required (except for the special use case of a page reload after access is granted).

The following code adds the storage-access permission check to the earlier example:

// Set a hasAccess boolean variable which defaults to false except for
// browsers which don't support the API - where we assume
// such browsers also don't block third-party cookies.
let hasAccess = false;

async function hasCookieAccess() {
  // Check if Storage Access API is supported
  if (!document.requestStorageAccess) {
    // Storage Access API is not supported so best we can do is
    // hope it's an older browser that doesn't block 3P cookies.
    return true;
  }

  // Check if access has already been granted
  if (await document.hasStorageAccess()) {
    return true;
  }

  // Check the storage-access permission
  // Wrap this in a try/catch for browsers that support the
  // Storage Access API but not this permission check
  // (e.g. Safari and earlier versions of Firefox).
  let permission;
  try {
    permission = await navigator.permissions.query(
      {name: 'storage-access'}
    );
  } catch (error) {
    // storage-access permission not supported. Assume no cookie access.
    return false;
  }

    if (permission) {
    if (permission.state === 'granted') {
      // Permission has previously been granted so can just call
      // requestStorageAccess() without a user interaction and
      // it will resolve automatically.
      try {
        await document.requestStorageAccess();
        return true;
      } catch (error) {
        // This shouldn't really fail if access is granted, but return false
        // if it does.
        return false;
      }
    } else if (permission.state === 'prompt') {
      // Need to call requestStorageAccess() after a user interaction
      // (potentially with a prompt). Can't do anything further here,
      // so handle this in the click handler.
      return false;
          } else if (permission.state === 'denied') {
            // Not used: see https://github.com/privacycg/storage-access/issues/149
      return false;
          }
    }

  // By default return false, though should really be caught by earlier tests.
  return false;
}

async function handleCookieAccessInit() {
  hasAccess = await hasCookieAccess();

  if (hasAccess) {
    // Use the cookies.
  }
}

handleCookieAccessInit();

Key point: For privacy reasons, it is not possible to tell if the prompt was shown and rejected , or not shown based on browser heuristics—both will return prompt as the current state even when queried again.

Sandboxed iframes

When using the Storage Access API in sandboxed iframes , the following sandbox permissions are required:

allow-storage-access-by-user-activation is required to allow access to the Storage Access API.
allow-scripts is required to allow use of JavaScript to call the API.
allow-same-origin is required to allow access to same-origin cookies and other storage.

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

<iframe sandbox="allow-storage-access-by-user-activation
                 allow-scripts
                 allow-same-origin"
        src="..."></iframe>

Cookie requirements

To be accessed with the Storage Access API in Chrome, cross-site cookies must be set with the following two attributes:

SameSite=None - which is required to mark the cookie as cross-site
Secure - which ensures only cookies set by HTTPS sites can be accessed.

In Firefox and Safari, cookies are defaulted to SameSite=None and they don't restrict SAA to Secure cookies so these attributes are not required. It is recommended to be explicit about the SameSite attribute and to always use Secure cookies.

Top-level page access

The Storage Access API is intended for enabling access to third-party cookies within embedded iframes.

There are also other use cases when the top-level page requires access to third-party cookies. For example, images or scripts which are restricted by cookies, which site owners may want to include directly in the top-level document rather than in an iframe. To address this use case Chrome has proposed an extension to the Storage Access API which adds a requestStorageAccessFor() method.

The `requestStorageAccessFor()` method

Browser Support

Source

requestStorageAccessFor() method works in a similar way to requestStorageAccess() but for top-level resources. It can only be used for sites within a Related Website Set to prevent granting general access to third-party cookies.

For more details on how to use requestStorageAccessFor() read the Related Website Sets: developer guide .

The `top-level-storage-access` permission query

Browser Support

Similar to the storage-access permission, there is a top-level-storage-access permission to check whether access can be granted for requestStorageAccessFor() .

How is the Storage Access API different when used with RWS?

When Related Website Sets are used with the Storage Access API, certain additional capabilities are available as detailed in the following table:

	Without RWS	With RWS
Requires a user gesture to initiate the request for storage access
Requires user to visit requested storage origin in a top-level context before granting access
First time user prompt can be skipped
`requestStorageAccess` not required to be called if access has been previously granted
Automatically grants access across other domains in a Related Website Site
Supports `requestStorageAccessFor` for top-level page access

Differences between using Storage Access API without and with Related Website Sets

Demo: setting and accessing cookies

The following demo shows how a cookie set by yourself in the first screen of the demo can be accessed in an embedded frame in the second site of the demo:

storage-access-api-demo.glitch.me

The demo requires a browser with third-party cookies disabled:

Chrome 118 or higher with the chrome://flags/#test-third-party-cookie-phaseout flag set and browser restarted.
فایرفاکس
سافاری

Demo: setting Local Storage

The following demo shows how to access unpartitioned Broadcast Channels from a third-party iframe using the Storage Access API:

https://saa-beyond-cookies.glitch.me/

The demo requires Chrome 125 or higher with the test-third-party-cookie-phaseout flag enabled.

منابع

Read the specification providing third-party cookie access or follow and raise issues .
Read the specification providing unpartitioned storage access or follow and raise issues .
API documentation and guide .
Chrome documentation on using Storage Access API in Related Website Sets

Storage Access API

وضعیت پیاده سازی

Storage Access API چیست؟

موارد استفاده کنید

زمان استفاده از Storage Access API بر روی سایر APIها

از Storage Access API استفاده کنید

از متد hasStorageAccess() استفاده کنید

استفاده از requestStorageAccess()

مجوز درخواست می کند

FedCM به عنوان یک سیگنال اعتماد برای SAA

بارگیری بعدی با سرصفحه های دسترسی به فضای ذخیره سازی

هدر دسترسی به فضای ذخیره سازی جریان دارد

از هدرهای دسترسی به فضای ذخیره سازی استفاده کنید

از درخواست مجوز storage-access استفاده کنید

آیفریم های Sandboxed

الزامات کوکی

دسترسی به صفحه سطح بالا

متد requestStorageAccessFor() .

درخواست مجوز top-level-storage-access

Storage Access API هنگام استفاده با RWS چگونه متفاوت است؟

نسخه ی نمایشی: تنظیم و دسترسی به کوکی ها

نسخه ی نمایشی: تنظیم Local Storage

منابع

وضعیت پیاده سازی

Storage Access API چیست؟

موارد استفاده کنید

زمان استفاده از Storage Access API بر روی سایر APIها

از Storage Access API استفاده کنید

از متد hasStorageAccess() استفاده کنید

استفاده از requestStorageAccess()

مجوز درخواست می کند

FedCM به عنوان یک سیگنال اعتماد برای SAA

بارگیری بعدی با سرصفحه های دسترسی به فضای ذخیره سازی

هدر دسترسی به فضای ذخیره سازی جریان دارد

از هدر دسترسی به ذخیره سازی استفاده کنید

از پرس و جو اجازه storage-access استفاده کنید

iframes sandboxed

مورد نیاز کوکی

دسترسی به صفحه سطح بالا

روش requestStorageAccessFor()

پرس و جو مجوز top-level-storage-access

API دسترسی به ذخیره سازی هنگام استفاده از RWS چگونه متفاوت است؟

نسخه ی نمایشی: تنظیم و دسترسی به کوکی ها

نسخه ی نمایشی: تنظیم فضای محلی

منابع

وضعیت پیاده سازی

API دسترسی به ذخیره سازی چیست؟

موارد استفاده کنید

چه زمانی از API دسترسی به ذخیره سازی بیش از سایر API ها استفاده کنید

از API دسترسی به ذخیره سازی استفاده کنید

از روش hasStorageAccess() استفاده کنید

استفاده از requestStorageAccess()

مجوزها

FEDCM به عنوان یک سیگنال اعتماد برای SAA

بارگیری بعدی با هدر دسترسی به ذخیره سازی

هدر دسترسی به ذخیره سازی جریان دارد

از هدر دسترسی به ذخیره سازی استفاده کنید

از پرس و جو اجازه storage-access استفاده کنید

iframes sandboxed

مورد نیاز کوکی

دسترسی به صفحه سطح بالا

روش requestStorageAccessFor()

پرس و جو مجوز top-level-storage-access

API دسترسی به ذخیره سازی هنگام استفاده از RWS چگونه متفاوت است؟

نسخه ی نمایشی: تنظیم و دسترسی به کوکی ها

نسخه ی نمایشی: تنظیم فضای محلی

منابع

وضعیت پیاده سازی

API دسترسی به ذخیره سازی چیست؟

موارد استفاده کنید

چه زمانی از API دسترسی به ذخیره سازی بیش از سایر API ها استفاده کنید

Use the Storage Access API

Use the hasStorageAccess() method

Use requestStorageAccess()

Permission prompts

FedCM as a trust signal for SAA

Subsequent loading with Storage Access Headers

Storage access headers flow

Use storage access headers

Use the storage-access permission query

از متد `hasStorageAccess()` استفاده کنید

استفاده از `requestStorageAccess()`

از درخواست مجوز `storage-access` استفاده کنید

متد `requestStorageAccessFor()` .

درخواست مجوز `top-level-storage-access`

از متد `hasStorageAccess()` استفاده کنید

استفاده از `requestStorageAccess()`

از پرس و جو اجازه `storage-access` استفاده کنید

روش `requestStorageAccessFor()`

پرس و جو مجوز `top-level-storage-access`

از روش `hasStorageAccess()` استفاده کنید

استفاده از `requestStorageAccess()`

از پرس و جو اجازه `storage-access` استفاده کنید

روش `requestStorageAccessFor()`

پرس و جو مجوز `top-level-storage-access`

Use the `hasStorageAccess()` method

Use `requestStorageAccess()`

Use the `storage-access` permission query

The `requestStorageAccessFor()` method

The `top-level-storage-access` permission query