استبدال أدوات معالجة طلبات الويب المحظورة

يغيّر الإصدار Manifest V3 طريقة تعامل الإضافات مع تعديل طلبات الشبكة. بدلاً من اعتراض طلبات الشبكة وتعديلها في وقت التشغيل باستخدام browser.webRequest، يحدّد الإضافة قواعد تصف الإجراءات المطلوب تنفيذها عند استيفاء مجموعة معيّنة من الشروط. يمكنك إجراء ذلك باستخدام Declarative Net Request API.

تختلف واجهة برمجة التطبيقات Web Request API عن واجهة برمجة التطبيقات Declarative Net Request API بشكل كبير. بدلاً من استبدال استدعاء دالة بآخر، عليك إعادة كتابة الرمز البرمجي من حيث حالات الاستخدام. يشرح لك هذا القسم هذه العملية.

ليس عليك إجراء هذه التغييرات إذا كانت الإضافة مثبّتة بموجب سياسة. بالنسبة إلى الإضافات المثبَّتة بموجب سياسة، لا يزال الإذن webRequestBlocking متاحًا في الإصدار 3 من بيان الإضافة.

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

مقدمة

في الإصدار Manifest V2، كان حظر طلبات الويب يؤدي إلى انخفاض كبير في أداء الإضافات وأداء الصفحات التي تعمل معها. تتيح مساحة الاسم webRequest تسعة أحداث يمكن أن تحظر، ويستقبل كل منها عددًا غير محدود من معالِجات الأحداث. والأسوأ من ذلك، أنّ كل صفحة ويب يمكن أن تحظرها عدة إضافات، والأذونات المطلوبة لذلك تكون متطفلة. يمنع الإصدار Manifest V3 حدوث هذه المشكلة من خلال استبدال عمليات معاودة الاتصال بقواعد تعريفية.

تحديث الأذونات

أدخِل التغييرات التالية على الحقل "permissions" في manifest.json.

• أزِل إذن "webRequest" إذا لم تعُد بحاجة إلى مراقبة طلبات الشبكة.
• نقل "أنماط المطابقة" من "permissions" إلى "host_permissions"

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

إنشاء قواعد طلب شبكة تعريفية

يتطلّب إنشاء قواعد طلبات الشبكة التعريفية إضافة عنصر "declarative_net_request" إلى manifest.json. يحتوي الحظر "declarative_net_request" على مصفوفة من عناصر "rule_resource" تشير إلى ملف قاعدة. يحتوي ملف القاعدة على مصفوفة من العناصر التي تحدّد إجراءً والشروط التي يتم فيها تنفيذ هذه الإجراءات.

حالات الاستخدام الشائعة

توضّح الأقسام التالية حالات الاستخدام الشائعة لطلبات الشبكة التعريفية. تقدّم التعليمات أدناه مخططًا موجزًا فقط. يمكنك الاطّلاع على مزيد من المعلومات حول كل البيانات الواردة هنا في مرجع واجهة برمجة التطبيقات ضمن browser.declarativeNetRequest.

حظر عنوان URL واحد

كانت إحدى حالات الاستخدام الشائعة في الإصدار Manifest V2 هي حظر طلبات الويب باستخدام الحدث onBeforeRequest في النص البرمجي للخلفية.

browser.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

بالنسبة إلى Manifest V3، أنشئ قاعدة declarativeNetRequest جديدة باستخدام نوع الإجراء "block". لاحظ عنصر "condition" في قاعدة المثال. يحلّ "urlFilter" محلّ الخيار urls الذي تم تمريره إلى أداة معالجة webRequest. تحدّد مصفوفة "resourceTypes" فئة الموارد التي سيتم حظرها. يحظر هذا المثال صفحة HTML الرئيسية فقط، ولكن يمكنك، على سبيل المثال، حظر الخطوط فقط.

[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

لإتاحة هذه الميزة، عليك تعديل أذونات الإضافة. في manifest.json، استبدِل الإذن "webRequestBlocking" بالإذن "declarativeNetRequest". يُرجى العِلم أنّه تتم إزالة عنوان URL من الحقل "permissions" لأنّ حظر المحتوى لا يتطلّب أذونات المضيف. كما هو موضّح أعلاه، يحدّد ملف القاعدة المضيف أو المضيفين الذين ينطبق عليهم طلب الشبكة التعريفية.

إذا أردت تجربة ذلك، يتوفّر الرمز البرمجي أدناه في مستودع العيّنات.

  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]

  "permissions": [
    "declarativeNetRequest",
  ]

إعادة توجيه عناوين URL متعددة

كانت إحدى حالات الاستخدام الشائعة الأخرى في Manifest V2 هي استخدام حدث BeforeRequest لإعادة توجيه طلبات الويب.

browser.webRequest.onBeforeRequest.addListener((e) => {
    console.log(e);
    return { redirectUrl: "https://developer.chrome.com/docs/extensions/mv3/intro/" };
  }, { 
    urls: [
      "https://developer.chrome.com/docs/extensions/mv2/"
    ]
  }, 
  ["blocking"]
);

بالنسبة إلى Manifest V3، استخدِم نوع الإجراء "redirect". كما كان من قبل، يحلّ "urlFilter" محلّ الخيار url الذي تم تمريره إلى أداة الاستماع webRequest. يُرجى العِلم أنّه في هذا المثال، يحتوي الكائن "action" في ملف القاعدة على الحقل "redirect" الذي يتضمّن عنوان URL المطلوب عرضه بدلاً من عنوان URL الذي يتم فلترته.

[
  {
    "id" : 1,
    "priority": 1,
    "action": {
      "type": "redirect",
      "redirect": { "url": "https://developer.chrome.com/docs/extensions/mv3/intro/" }
    },
    "condition": {
      "urlFilter": "https://developer.chrome.com/docs/extensions/mv2/",
      "resourceTypes": ["main_frame"]
    }
  }
]

يتطلّب هذا السيناريو أيضًا إجراء تغييرات على أذونات الإضافة. كما في السابق، استبدِل الإذن "webRequestBlocking" بالإذن "declarativeNetRequest". يتم نقل عناوين URL مرة أخرى من manifest.json إلى ملف قاعدة. يُرجى العِلم أنّ إعادة التوجيه تتطلّب أيضًا إذن "declarativeNetRequestWithHostAccess" بالإضافة إلى إذن المضيف.

إذا أردت تجربة ذلك، يتوفّر الرمز البرمجي أدناه في مستودع العيّنات.

  "permissions": [
    "webRequestBlocking",
    "https://developer.chrome.com/docs/extensions/*",
    "https://developer.chrome.com/docs/extensions/reference"
  ]

  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]

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

في الإصدار 2 من ملف البيان، يتطلّب حظر ملفات تعريف الارتباط اعتراض عناوين طلبات الويب قبل إرسالها وإزالة ملف تعريف ارتباط معيّن.

browser.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    removeHeader(details.requestHeaders, 'cookie');
    return {requestHeaders: details.requestHeaders};
  },
  // filters
  {urls: ['https://*/*', 'http://*/*']},
  // extraInfoSpec
  ['blocking', 'requestHeaders', 'extraHeaders']);

يتم ذلك أيضًا في Manifest V3 باستخدام قاعدة في ملف قواعد. في هذه المرة، يكون نوع الإجراء هو "modifyHeaders". يستقبل الملف مصفوفة من عناصر "requestHeaders" تحدّد العناوين المطلوب تعديلها وكيفية تعديلها. يُرجى العِلم أنّ الكائن "condition" يحتوي فقط على مصفوفة "resourceTypes". يمكن استخدام القيم نفسها كما في الأمثلة السابقة.

إذا أردت تجربة ذلك، يتوفّر الرمز البرمجي أدناه في مستودع العيّنات.

[
  {
    "id": 1,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        { "header": "cookie", "operation": "remove" }
      ]
    },
    "condition": {
      "urlFilter": "|*?no-cookies=1",
      "resourceTypes": ["main_frame"]
    }
  }
]

يتطلّب هذا السيناريو أيضًا إجراء تغييرات على أذونات الإضافة. كما في السابق، استبدِل الإذن "webRequestBlocking" بالإذن "declarativeNetRequest".

  "permissions": [
    "webRequest",
    "webRequestBlocking",
    "https://*/*",
    "http://*/*"
  ],

  "permissions": [
    "declarativeNetRequest",
  ],
  "host_permissions": [
    ""
  ]