واجهة برمجة التطبيقات Storage Access API

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

حالة التنفيذ

التوافق مع المتصفح

  • 119
  • 85
  • 65
  • 11.1

المصدر

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

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

ما هي واجهة برمجة التطبيقات Storage Access API؟

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

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

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

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

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

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

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

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

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

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

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

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

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

استخدام Storage Access API

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

وهي تتكامل أيضًا مع Permissions API. يتيح لك ذلك التحقّق من حالة إذن الوصول إلى مساحة التخزين في سياق تابع لجهة خارجية، والتي تشير إلى ما إذا كان سيتم تلقائيًا منح الاتصال بـ document.requestStorageAccess() أم لا:

استخدام طريقة 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 via 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();

يتم منح الإذن بالوصول إلى مساحة التخزين لمستند iframe فقط بعد طلب البيانات من 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 above did not reject.
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

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

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

الطلبات بالأذونات

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

لقطة شاشة لموجّه Chrome Storage Access API
طلب إذن واجهة برمجة التطبيقات Storage Access API في Chrome

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

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

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

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

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

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

استخدام طلب البحث عن إذن "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 older 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') {
            // Currently not used. See:
      // https://github.com/privacycg/storage-access/issues/149
      return false;
          }
    }

  // By default return false, though should really be caught by one of above.
  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 ولا يتم حصر SSA بملفات تعريف الارتباط Secure، وبالتالي لا تكون هذه السمات مطلوبة. ننصحك بأن تكون واضحًا جدًا في السمة SameSite وأن تستخدم دائمًا ملفات تعريف الارتباط Secure.

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

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

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

طريقة requestStorageAccessFor()

التوافق مع المتصفح

  • 119
  • 119
  • x
  • x

المصدر

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

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

طلب البحث عن إذن "top-level-storage-access"

التوافق مع المتصفح

  • 119
  • 119
  • x
  • x

يشبه إذن storage-access، هناك إذن top-level-storage-access للتحقّق مما إذا كان من الممكن منح إذن الوصول لـ requestStorageAccessFor().

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

عند استخدام ميزة Related Website Sets مع واجهة برمجة التطبيقات Storage Access API، تتوفّر بعض الإمكانيات الإضافية كما هو موضّح في الجدول التالي:

بدون RWS مع RWS
يجب استخدام إيماءة المستخدم لبدء طلب الوصول إلى مساحة التخزين.
على المستخدم الانتقال إلى مصدر مساحة التخزين المطلوب في سياق أعلى مستوى قبل منح إذن الوصول.
يمكن تخطّي طلب المستخدم لأول مرة.
ليس من الضروري الاتصال بـ "requestStorageAccess" إذا تم منح الإذن بالوصول سابقًا
منح الإذن بالوصول تلقائيًا عبر النطاقات الأخرى في موقع إلكتروني مرتبط
تتيح requestStorageAccessFor الوصول إلى الصفحة ذات المستوى الأعلى
الاختلافات بين استخدام Storage Access API بدون استخدام ميزة Related Website Sets

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

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

storage-access-api-demo.glitch.me

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

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

المراجِع