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

تعديل طلبات الشبكة في إصدار Manifest V3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

chrome.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 لإعادة توجيه طلبات الويب.

chrome.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/*"
  ]

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

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

chrome.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": [
    ""
  ]