Storage Access API

يشكّل حظر ملفات تعريف الارتباط التابعة لجهات خارجية من خلال المتصفّحات وإعدادات المستخدمين وتقسيم مساحة التخزين تحديًا للمواقع الإلكترونية والخدمات التي تعتمد على ملفات تعريف الارتباط ومساحة التخزين الأخرى في السياقات المضمّنة، وذلك في ما يتعلّق برحلات المستخدمين، مثل المصادقة. تسمح Storage Access API (SAA) باستمرار عمل حالات الاستخدام هذه، مع الحدّ من التتبّع على عدة مواقع إلكترونية قدر الإمكان.

حالة التنفيذ

تتوفّر واجهة برمجة التطبيقات Storage Access API في جميع المتصفّحات الرئيسية، ولكن هناك اختلافات طفيفة في التنفيذ بين المتصفّحات. وقد تمّ تسليط الضوء على هذه الاختلافات في الأقسام ذات الصلة في هذه المشاركة.

نواصل العمل على حلّ جميع مشاكل الحظر المتبقية قبل توحيد واجهة برمجة التطبيقات.

ما هي Storage Access API؟

‫Storage Access API هي واجهة برمجة تطبيقات JavaScript تتيح لإطارات iframe طلب أذونات الوصول إلى مساحة التخزين عندما ترفض إعدادات المتصفّح الوصول إليها. يمكن أن تستخدم عمليات التضمين التي تتضمّن حالات استخدام تعتمد على تحميل موارد من مواقع إلكترونية متعددة واجهة برمجة التطبيقات لطلب إذن الوصول من المستخدم، حسب الحاجة.

في حال الموافقة على طلب الوصول إلى مساحة التخزين، سيتمكّن إطار iframe من الوصول إلى ملفات تعريف الارتباط ومساحة التخزين غير المقسّمة، والتي تكون متاحة أيضًا عندما ينتقل المستخدمون إلى الموقع الإلكتروني كأحد المواقع الإلكترونية من المستوى الأعلى.

تسمح واجهة برمجة التطبيقات Storage Access API بتوفير إمكانية الوصول إلى ملفات تعريف الارتباط ومساحة التخزين غير المقسّمة بشكل محدّد بأقلّ عبء على المستخدم النهائي، مع استمرار منع الوصول العام إلى ملفات تعريف الارتباط ومساحة التخزين غير المقسّمة كما هو الحال غالبًا عند تتبُّع المستخدمين.

حالات الاستخدام

تتطلّب بعض عمليات التضمين التابعة لجهات خارجية الوصول إلى ملفات تعريف الارتباط أو مساحة التخزين غير المقسّمة لتوفير تجربة أفضل للمستخدم، وهو أمر لن يكون متاحًا عند حظر ملفات تعريف الارتباط التابعة لجهات خارجية وتفعيل تقسيم مساحة التخزين.

تشمل حالات الاستخدام ما يلي:

• أدوات التعليق المضمّنة التي تتطلّب تفاصيل جلسة تسجيل الدخول
• أزرار "أعجبني" على وسائل التواصل الاجتماعي التي تتطلّب تفاصيل جلسة تسجيل الدخول
• المستندات المضمّنة التي تتطلّب تفاصيل جلسة تسجيل الدخول
• تجربة مميّزة يتم توفيرها لفيديو مضمّن (على سبيل المثال، عدم عرض الإعلانات للمستخدمين الذين سجّلوا الدخول، أو معرفة إعدادات المستخدم المفضّلة بشأن الترجمة والشرح أو حظر أنواع معيّنة من الفيديوهات).
• أنظمة الدفع المضمّنة

تتضمّن العديد من حالات الاستخدام هذه الاحتفاظ بإذن تسجيل الدخول في إطارات iframe المضمّنة.

حالات استخدام Storage Access API بدلاً من واجهات برمجة التطبيقات الأخرى

إنّ Storage Access API هو أحد البدائل لاستخدام ملفات تعريف الارتباط ومساحة التخزين غير المقسّمة، لذا من المهم معرفة متى يجب استخدام واجهة برمجة التطبيقات هذه مقارنةً بالبدائل الأخرى. وهي مخصّصة لحالات الاستخدام التي ينطبق عليها الشرطان التاليان:

• سيتفاعل المستخدم مع المحتوى المضمّن، أي أنّه ليس إطار iframe غير نشط أو مخفي.
• زار المستخدم المصدر المضمّن في سياق أعلى مستوى، أي عندما لا يكون هذا المصدر مضمّنًا في موقع إلكتروني آخر.

تتوفّر واجهات برمجة تطبيقات بديلة لمجموعة متنوعة من حالات الاستخدام:

• تتيح ملفات تعريف الارتباط في الحالة المقسَّمة المنفصلة (CHIPS) للمطوّرين الموافقة على تخزين ملف تعريف الارتباط في مساحة تخزين "مقسَّمة"، مع توفير حاوية منفصلة لملفات تعريف الارتباط لكل موقع إلكتروني من المستوى الأعلى. على سبيل المثال، قد تعتمد أداة محادثة ويب تابعة لجهة خارجية على ضبط ملف تعريف ارتباط لحفظ معلومات الجلسة. يتم حفظ معلومات الجلسة لكل موقع إلكتروني، لذا لا يلزم الوصول إلى ملف تعريف الارتباط الذي تم ضبطه من خلال الأداة على المواقع الإلكترونية الأخرى التي تم تضمينها فيها أيضًا. تكون Storage Access API مفيدة عندما تعتمد أداة مضمَّنة تابعة لجهة خارجية على مشاركة المعلومات نفسها على جميع المصادر المختلفة (على سبيل المثال، تفاصيل الجلسة أو الإعدادات المفضّلة التي تم تسجيل الدخول إليها).
• تقسيم مساحة التخزين هو طريقة تتيح لإطارات iframe المتعدّدة المواقع الإلكترونية استخدام آليات تخزين JavaScript الحالية مع تقسيم مساحة التخزين الأساسية لكل موقع إلكتروني. يمنع ذلك الوصول إلى مساحة التخزين المضمّنة في موقع إلكتروني واحد من خلال عملية التضمين نفسها على مواقع إلكترونية أخرى.
• مجموعات المواقع الإلكترونية المرتبطة (RWS) هي طريقة تتيح للمؤسسة الإعلان عن العلاقات بين المواقع الإلكترونية، كي تسمح المتصفّحات بالوصول المحدود إلى ملفات تعريف الارتباط ومساحة التخزين غير المقسّمة لأغراض محدّدة. ستظل المواقع الإلكترونية بحاجة إلى طلب الوصول باستخدام Storage Access API، ولكن بالنسبة إلى المواقع الإلكترونية ضمن المجموعة، يمكن منح إذن الوصول بدون طلبات من المستخدم.
• ‫Federated Credential Management (FedCM) هي طريقة للحفاظ على الخصوصية في خدمات الهوية المتّحدة. تتعامل واجهة برمجة التطبيقات Storage Access API مع الوصول إلى ملفات تعريف الارتباط ومساحة التخزين غير المقسّمة بعد تسجيل الدخول. في بعض حالات الاستخدام، توفّر واجهة FedCM API حلاً بديلاً لواجهة Storage Access API، وقد يكون من الأفضل استخدامها لأنّها تتضمّن طلبًا من المتصفّح أكثر تركيزًا على تسجيل الدخول. ومع ذلك، يتطلّب استخدام FedCM عادةً إجراء تغييرات إضافية على الرمز، مثل توفير نقاط نهاية HTTP.
• تتوفّر أيضًا واجهات برمجة تطبيقات مكافحة الاحتيال وذات الصلة بالإعلانات والقياس، ولا يهدف Storage Access API إلى معالجة هذه المخاوف.

استخدام Storage Access API

تتضمّن واجهة برمجة التطبيقات Storage Access API طريقتَين تستندان إلى الوعود:

• Document.hasStorageAccess() (تتوفّر أيضًا بالاسم الجديد Document.hasUnpartitionedCookieAccess() اعتبارًا من الإصدار 125 من Chrome)
• 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.
    hasAccess = await document.hasStorageAccess();
    if (!hasAccess) {
      // Handle the lack of access (covered later)
    }
  }
  if (hasAccess) {
    // Use the cookies.
  }
}
handleCookieAccessInit();

لا تمنح واجهة برمجة التطبيقات Storage Access API إذن الوصول إلى مساحة التخزين لمستند iframe إلا بعد أن تطلب requestStorageAccess(),، لذا قد تعرض hasStorageAccess() القيمة "خطأ" في البداية، مثلاً إذا حظر المستخدم ملفات تعريف الارتباط التابعة لجهات خارجية تلقائيًا. (ومع ذلك، قد تسمح إعدادات المستخدم الخاصة بموقع إلكتروني معيّن أيضًا بالوصول إلى ملفات تعريف الارتباط على موقع إلكتروني معيّن، حتى إذا حظر المستخدم ملفات تعريف الارتباط الخارجية تلقائيًا). يتم الاحتفاظ بإذن الوصول إلى مساحة التخزين باستخدام واجهة برمجة التطبيقات هذه أثناء عمليات التنقّل من المصدر نفسه داخل الإطار 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);

طلبات الحصول على الأذونات

عندما ينقر المستخدم على الزر للمرة الأولى، سيظهر طلب المتصفح تلقائيًا في معظم الحالات، وعادةً في شريط العناوين. تعرض لقطة الشاشة التالية مثالاً على طلب Chrome، ولكن تتضمّن المتصفّحات الأخرى واجهة مستخدم مشابهة:

قد يتخطّى المتصفّح طلب الإذن ويمنحه تلقائيًا في ظروف معيّنة:

• إذا تم استخدام الصفحة وإطار iframe خلال آخر 30 يومًا بعد قبول الطلب
• إذا كان إطار iframe المضمّن جزءًا من مجموعة مواقع إلكترونية مرتبطة
• إذا تم استخدام FedCM كإشارة ثقة للوصول إلى مساحة التخزين
• في Firefox، يتم أيضًا تخطّي الطلب للمواقع الإلكترونية المعروفة (التي تفاعلت معها على المستوى الأعلى) في المحاولات الخمس الأولى.

بدلاً من ذلك، قد يتم رفض الطريقة تلقائيًا بدون عرض الطلب في ظروف معيّنة:

• إذا لم يسبق للمستخدم زيارة الموقع الإلكتروني الذي يملك إطار iframe والتفاعل معه كمستند أعلى مستوى، وليس في إطار iframe وهذا يعني أنّ واجهة برمجة التطبيقات Storage Access API لا تفيد إلا المواقع الإلكترونية المضمّنة التي سبق للمستخدمين زيارتها في سياق الطرف الأول.
• إذا تم استدعاء الطريقة requestStorageAccess() خارج حدث تفاعل المستخدم بدون موافقة مسبقة على الطلب بعد التفاعل.

مع أنّ المستخدم سيُطلب منه الموافقة عند الاستخدام الأوّلي، يمكن أن يتم حلّ requestStorageAccess() في الزيارات اللاحقة بدون طلب موافقة وبدون الحاجة إلى تفاعل المستخدم في Chrome وFirefox. يُرجى العِلم أنّ Safari يتطلّب دائمًا تفاعلاً من المستخدم.

بما أنّه يمكن منح إذن الوصول إلى ملفات تعريف الارتباط ومساحة التخزين بدون طلب أو تفاعل من المستخدم، من الممكن غالبًا الحصول على إذن الوصول إلى ملفات تعريف الارتباط أو مساحة التخزين غير المقسّمة قبل تفاعل المستخدم على المتصفّحات التي تتيح ذلك (Chrome وFirefox) من خلال طلب requestStorageAccess() عند تحميل الصفحة. قد يتيح لك ذلك الوصول إلى ملفات تعريف الارتباط ومساحة التخزين غير المقسّمة على الفور وتقديم تجربة أكثر اكتمالاً، حتى قبل أن يتفاعل المستخدم مع الإطار iframe. قد يوفّر ذلك تجربة أفضل للمستخدم في بعض الحالات مقارنةً بالانتظار إلى أن يتفاعل المستخدم.

استخدام FedCM كمؤشر ثقة في SAA

‫FedCM (إدارة بيانات الاعتماد الموحّدة) هي طريقة تحافظ على الخصوصية في خدمات الهوية الموحّدة (مثل "تسجيل الدخول باستخدام...") ولا تعتمد على ملفات تعريف الارتباط التابعة لجهات خارجية أو عمليات إعادة التوجيه.

عندما يسجّل مستخدم الدخول إلى طرف معتمَد (RP) يتضمّن بعض المحتوى المضمّن من موفِّر هوية تابع لجهة خارجية (IdP) باستخدام FedCM، يمكن أن يحصل محتوى موفِّر الهوية المضمّن تلقائيًا على إذن الوصول إلى مساحة التخزين لملفات تعريف الارتباط غير المقسّمة الخاصة به على المستوى الأعلى. لتفعيل إمكانية الوصول التلقائي إلى مساحة التخزين باستخدام FedCM، يجب استيفاء الشروط التالية:

• يجب أن تكون مصادقة FedCM (حالة تسجيل دخول المستخدم) نشطة.
• وافق صاحب الملكية على ذلك من خلال ضبط الإذن 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',
    }],
  },
});

بعد تسجيل دخول المستخدم، يمكن لموفّر الهوية استدعاء requestStorageAccess() من داخل إطار idp.example iframe، طالما أنّ الجهة المعتمِدة سمحت بذلك صراحةً باستخدام سياسة الأذونات. سيتم تلقائيًا منح المحتوى المضمّن إذن الوصول إلى مساحة التخزين لملف تعريف الارتباط الخاص به على المستوى الأعلى، بدون أن يفعّله المستخدم أو أن تظهر رسالة طلب إذن أخرى:

// 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 العادية لمنح إذن الوصول إلى مساحة التخزين.

‫Storage Access API لمساحة التخزين غير المستندة إلى ملفات تعريف الارتباط

يمكنك طلب الوصول إلى مساحة التخزين المحلية غير المقسَّمة من خلال تمرير المَعلمة types إلى طلب requestStorageAccess. على سبيل المثال، لطلب الوصول إلى مساحة التخزين المحلية غير المقسّمة، يمكنك استدعاء requestStorageAccess({localStorage: true}).

في حال تفعيل ملفات تعريف الارتباط التابعة لجهات خارجية، ستمنح هذه الطريقة إذن الوصول بدون طلب تفعيل من المستخدم أو أي طلب للحصول على إذن. إذا أوقف المستخدم ملفات تعريف الارتباط التابعة لجهات خارجية، يجب أن يُطلب منه الإذن قبل منح إذن الوصول إلى مساحة التخزين.

تحقَّق أولاً ممّا إذا كان المتصفّح لديه إذن الوصول إلى مساحة التخزين:

async function hasCookieAccess(){
  // Check if Storage Access API is supported
  if (!document.requestStorageAccess) {
    // Storage Access API is not supported, so we assume it's an older browser that doesn't partition storage.
    throw new Error("requestStorageAccess is not supported")
  }

  // Check if access has already been granted or if the user has 3-party cookies enabled
  return document.hasStorageAccess();
}

إذا كانت ملفات تعريف الارتباط التابعة لجهات خارجية مفعّلة، اطلب إذن الوصول إلى مساحة التخزين باتّباع الخطوات التالية:

// Request storage access and return the storage handle
async function requestStorageHandle(){
// You can request for multiple types of non-cookie storage
// at once, or request for all of them with all:true
return document.requestStorageAccess({all:true});
}

في حال حظر ملفات تعريف الارتباط التابعة لجهات خارجية (على سبيل المثال، في "وضع التصفّح المتخفي")، تحقَّق من أذونات طلب البحث لتحديد ما إذا كان يجب عرض طلب من المستخدم. يمكن أن تتضمّن navigator.permissions.query({name: 'storage-access'}) حالة الأذونات القيم التالية:

• granted. سبق أن منح المستخدم الإذن بالوصول إلى الحساب. يمكنك طلب الإذن requestStorageAccess للحصول على إذن الوصول إلى مساحة التخزين غير المقسَّمة بدون الحاجة إلى طلب إذن إضافي من المستخدم.
• ‫prompt: لم يمنح المستخدم الإذن بالوصول إلى البيانات بعد. اضبط أداة معالجة النقرات واستدعِ requestStorageAccess مرة أخرى بعد تفاعل المستخدم.
• error. الإذن غير متاح. عندما تكون واجهة برمجة التطبيقات Storage Access API متاحة، من المحتمل أن يكون هذا الإذن متاحًا أيضًا.

// Returns `granted`, or `prompt`; or throws an error if storage-access
// permission is not supported
async function getStorageAccessPermission(){
  // Check the storage-access permission
  // Wrap this in a try/catch for browsers that support the
  // Storage Access API but not this permission check
    return navigator.permissions.query({name: 'storage-access'});
}

يمكن تنفيذ عملية معالجة مساحة التخزين المقسّمة بدون الاحتفاظ بملفات تعريف الارتباط على النحو التالي:

async function getStorageHandle() {
    // Check if the user has 3-party cookie access
    if (await hasCookieAccess()) {
    // If the user has access, requestStorageAccess() will resolve automatically
        return requestStorageHandle();
    }

    // If the browser blocks third party cookies, check if the user has
    // accepted the prompt and granted access. If they have,
    // requestStorageAccess() will resolve automatically
    const permission = await getStorageAccessPermission();
    if (permission == 'granted') { // User has seen prompt and granted access
        return requestStorageHandle();
    }

    // Wait for user activation to prompt the user again
    // (or put your silent failure logic here instead)
    return new Promise((resolve, reject) => {
        document.querySelector('#myButton').addEventListener(e => {
            requestStorageHandle().then(resolve, reject);
        })
    })
}

// Use your storage
getStorageHandle().then(handle=>{
    handle.indexedDB.open(...);
}).catch(() => {
    // If the promise is rejected, you can use regular partitioned storage
    indexedDB.open(...);
})

التحميل اللاحق باستخدام عناوين Storage Access API

تمثّل Storage Access Headers طريقة مقترَحة وأكثر فعالية لإتاحة تحميل المحتوى المضمّن، بما في ذلك الموارد غير إطارات iframe. تتوفّر هذه الميزة بدءًا من الإصدار 133 من Chrome. باستخدام Storage Access Headers، يمكن للمتصفّح التعرّف على الحالات التي سبق فيها أن منح المستخدم الإذن storage-access للمصدر التابع لجهة خارجية في السياق الحالي، ويمكنه تحميل الموارد مع إمكانية الوصول إلى ملفات تعريف الارتباط غير المقسّمة خلال الزيارات اللاحقة.

مسار عناوين الوصول إلى مساحة التخزين

باستخدام عناوين Storage Access API، ستؤدي زيارات الصفحات اللاحقة إلى تشغيل التسلسل التالي:

1. زار المستخدم سابقًا website.example الذي يتضمّن مورد calendar.example ومنح storage-access الإذن باستخدام طلب document.requestStorageAccess().
2. يزور المستخدم website.example الذي يتضمّن المورد calendar.example مرة أخرى. لا يمكن لهذا الطلب الوصول إلى ملف تعريف الارتباط بعد، كما كان الحال في السابق. ومع ذلك، سبق أن منح المستخدم إذن storage-access، ويتضمّن طلب الجلب العنوان Sec-Fetch-Storage-Access: inactive، للإشارة إلى أنّ إمكانية الوصول إلى ملفات تعريف الارتباط غير المقسّمة متاحة ولكن لم يتم تفعيلها.
3. يستجيب الخادم calendar.example بعنوان Activate-Storage-Access: retry; allowed-origin='<origin>' (في هذه الحالة، ستكون قيمة <origin> هي https://website.example)، للإشارة إلى أنّ عملية جلب المورد تتطلّب استخدام ملفات تعريف ارتباط غير مقسّمة مع إذن storage-access.
4. يعيد المتصفّح محاولة إرسال الطلب، ويتضمّن هذه المرة ملفات تعريف الارتباط غير المقسّمة (يتم تفعيل إذن storage-access لعملية الجلب هذه وعمليات الجلب اللاحقة).
5. يستجيب خادم calendar.example بمحتوى إطار iframe المخصّص. تتضمّن الاستجابة العنوان Activate-Storage-Access: load للإشارة إلى أنّه على المتصفّح تحميل المحتوى مع تفعيل الإذن storage-access (أي التحميل مع إمكانية الوصول إلى ملفات تعريف الارتباط غير المقسّمة، كما لو تم استدعاء document.requestStorageAccess()).
6. يحمّل وكيل المستخدم محتوى iframe مع إمكانية الوصول إلى ملفات تعريف الارتباط غير المقسّمة باستخدام الإذن storage-access. بعد هذه الخطوة، يمكن أن تعمل الأداة على النحو المتوقّع.

استخدام عناوين الوصول إلى مساحة التخزين

يعرض الجدول التالي عناوين Storage Access.

على سبيل المثال، يمكن استخدام عناوين Storage Access API لتحميل صورة من جهة خارجية:

  // 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 محتوى تابعًا لجهة خارجية (بما في ذلك صورة غير مضمّنة في إطار iframe) باستخدام عناوين Storage Access.

استخدام طلب إذن storage-access

للتحقّق مما إذا كان يمكن منح إذن الوصول بدون تفاعل المستخدم، يمكنك التحقّق من حالة الإذن storage-access وإجراء طلب requestStoreAccess() مبكرًا فقط إذا لم يكن هناك حاجة إلى إجراء من المستخدم، بدلاً من إجراء الطلب ثم تعذّره عند الحاجة إلى تفاعل.

يتيح لك ذلك أيضًا إمكانية التعامل مع الحاجة إلى طلب مقدّمًا من خلال عرض محتوى مختلف، مثل زر تسجيل الدخول.

تضيف التعليمة البرمجية التالية عملية التحقّق من إذن 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();

إطارات iframe المحصورة

عند استخدام Storage Access API في إطارات iframe في وضع الحماية، يجب توفّر أذونات وضع الحماية التالية:

• يجب توفُّر allow-storage-access-by-user-activation للسماح بالوصول إلى Storage Access API.
• يجب توفّر allow-scripts للسماح باستخدام JavaScript لطلب بيانات من واجهة برمجة التطبيقات.
• يجب توفُّر allow-same-origin للسماح بالوصول إلى ملفات تعريف الارتباط ومساحات التخزين الأخرى من المصدر نفسه.

على سبيل المثال:

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

متطلبات ملفات تعريف الارتباط

للوصول إلى ملفات تعريف الارتباط على مواقع إلكترونية متعددة باستخدام Storage Access API في Chrome، يجب ضبط ملفات تعريف الارتباط باستخدام السمتَين التاليتَين:

• ‫SameSite=None: السمة المطلوبة لوضع علامة على ملف تعريف الارتباط للإشارة إلى أنّه متاح على عدة مواقع إلكترونية
• Secure، ما يضمن عدم إمكانية الوصول إلا إلى ملفات تعريف الارتباط التي تضبطها المواقع الإلكترونية التي تستخدم HTTPS.

في متصفّحَي Firefox وSafari، يتم ضبط ملفات تعريف الارتباط تلقائيًا على SameSite=None ولا تحصر هذه المتصفّحات الوصول إلى SAA على ملفات تعريف الارتباط Secure، لذا لا تكون هذه السمات مطلوبة. ننصحك بأن تكون واضحًا بشأن السمة SameSite وأن تستخدم دائمًا ملفات تعريف الارتباط Secure.

الوصول إلى الصفحة ذات المستوى الأعلى

تهدف Storage Access API إلى السماح بالوصول إلى ملفات تعريف الارتباط التابعة لجهات خارجية ضِمن إطارات iframe المضمّنة.

هناك أيضًا حالات استخدام أخرى تتطلّب فيها الصفحة الأعلى مستوى الوصول إلى ملفات تعريف الارتباط التابعة لجهات خارجية. على سبيل المثال، الصور أو النصوص البرمجية التي يتم حظرها باستخدام ملفات تعريف الارتباط، والتي قد يريد مالكو المواقع الإلكترونية تضمينها مباشرةً في المستند ذي المستوى الأعلى بدلاً من تضمينها في إطار iframe. لمعالجة حالة الاستخدام هذه، اقترح Chrome إضافة إلى Storage Access API تضيف طريقةrequestStorageAccessFor().

طريقة requestStorageAccessFor()

تعمل طريقة requestStorageAccessFor() بشكل مشابه لطريقة requestStorageAccess() ولكن للموارد ذات المستوى الأعلى. لا يمكن استخدامها إلا للمواقع الإلكترونية ضمن مجموعة المواقع الإلكترونية ذات الصلة لمنع منح إذن عام بالوصول إلى ملفات تعريف الارتباط التابعة لجهات خارجية.

لمزيد من التفاصيل حول كيفية استخدام requestStorageAccessFor()، يُرجى قراءة مجموعات المواقع الإلكترونية المرتبطة: دليل المطوّرين.

طلب الإذن top-level-storage-access

على غرار إذن storage-access، هناك إذن top-level-storage-access للتحقّق مما إذا كان يمكن منح إذن الوصول إلى requestStorageAccessFor().

كيف تختلف واجهة برمجة التطبيقات Storage Access API عند استخدامها مع RWS؟

عند استخدام "مجموعات المواقع الإلكترونية المرتبطة" مع Storage Access API، تتوفّر بعض الإمكانات الإضافية على النحو المفصّل في الجدول التالي:

عرض توضيحي: ضبط ملفات تعريف الارتباط والوصول إليها

يوضّح العرض التوضيحي التالي كيف يمكن الوصول إلى ملف تعريف ارتباط تم ضبطه بنفسك في الشاشة الأولى من العرض التوضيحي في إطار مضمَّن في الموقع الإلكتروني الثاني من العرض التوضيحي:

storage-access-api-demo.glitch.me

يتطلّب العرض التوضيحي متصفّحًا تم فيه إيقاف ملفات تعريف الارتباط التابعة لجهات خارجية:

• الإصدار 118 من Chrome أو إصدار أحدث مع ضبط العلامة chrome://flags/#test-third-party-cookie-phaseout وإعادة تشغيل المتصفّح
• Firefox
• Safari

عرض توضيحي: ضبط مساحة التخزين المحلية

يوضّح العرض التوضيحي التالي كيفية الوصول إلى قنوات البث غير المقسَّمة من إطار iframe تابع لجهة خارجية باستخدام Storage Access API:

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

تتطلّب النسخة التجريبية استخدام الإصدار 125 أو إصدار أحدث من Chrome مع تفعيل العلامة test-third-party-cookie-phaseout.

الموارد

• اطّلِع على المواصفات التي تتيح الوصول إلى ملفات تعريف الارتباط التابعة لجهات خارجية أو تابِع المشاكل وأبلِغ عنها.
• يمكنك الاطّلاع على المواصفات التي تتيح الوصول إلى مساحة التخزين غير المقسّمة أو متابعة المشاكل والإبلاغ عنها.
• مستندات واجهة برمجة التطبيقات والدليل
• مستندات Chrome حول استخدام Storage Access API في "مجموعات المواقع الإلكترونية المرتبطة"