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

مانیفست نسخه ۳ نحوه مدیریت تغییرات درخواست‌های شبکه توسط افزونه‌ها را تغییر می‌دهد. به جای رهگیری درخواست‌های شبکه و تغییر آنها در زمان اجرا با chrome.webRequest ، افزونه شما قوانینی را مشخص می‌کند که اقداماتی را که باید در صورت برآورده شدن مجموعه‌ای از شرایط خاص انجام شوند، توصیف می‌کند. این کار را با استفاده از Declarative Net Request API انجام دهید.

API درخواست وب و APIهای درخواست اعلانی Net تفاوت‌های قابل توجهی دارند. به جای جایگزینی یک فراخوانی تابع با فراخوانی تابع دیگر، باید کد خود را بر اساس موارد استفاده بازنویسی کنید. این بخش شما را در این فرآیند راهنمایی می‌کند.

اگر افزونه شما توسط سیاست نصب شده باشد، نیازی به انجام این تغییرات ندارید. برای افزونه‌های نصب شده با سیاست، مجوز webRequestBlocking هنوز در Manifest V3 موجود است.

این دومین بخش از سه بخشی است که تغییرات مورد نیاز برای کدی را که بخشی از سرویس دهنده افزونه نیست، شرح می‌دهد. این بخش تبدیل درخواست‌های مسدودکننده وب، که توسط Manifest V2 استفاده می‌شود، به درخواست‌های اعلانی شبکه، که توسط Manifest V3 استفاده می‌شود، را شرح می‌دهد. دو بخش دیگر، به‌روزرسانی کد مورد نیاز شما برای مهاجرت به Manifest V3 و بهبود امنیت را پوشش می‌دهد.

مقدمه

در Manifest V2، مسدود کردن درخواست‌های وب می‌تواند به طور قابل توجهی هم عملکرد افزونه‌ها و هم عملکرد صفحاتی که با آنها کار می‌کنند را کاهش دهد. فضای نام webRequest از نه رویداد بالقوه مسدودکننده پشتیبانی می‌کند که هر کدام تعداد نامحدودی از کنترل‌کننده‌های رویداد را می‌پذیرند. بدتر از همه، هر صفحه وب به طور بالقوه توسط چندین افزونه مسدود می‌شود و مجوزهای مورد نیاز برای این کار تهاجمی هستند. Manifest V3 با جایگزینی callbackها با قوانین اعلانی، از این مشکل جلوگیری می‌کند.

به‌روزرسانی مجوزها

تغییرات زیر را در فیلد "permissions" در manifest.json خود اعمال کنید.

  • اگر دیگر نیازی به مشاهده درخواست‌های شبکه ندارید، مجوز "webRequest" را حذف کنید.
  • الگوهای تطبیق را از "permissions" به "host_permissions" منتقل کنید.

بسته به مورد استفاده‌تان، باید مجوزهای دیگری را اضافه کنید. این مجوزها به همراه مورد استفاده‌ای که پشتیبانی می‌کنند، شرح داده شده‌اند.

ایجاد قوانین درخواست شبکه اعلانی

ایجاد قوانین درخواست اعلانی شبکه نیاز به اضافه کردن یک شیء "declarative_net_request" به manifest.json شما دارد. بلوک "declarative_net_request" شامل آرایه‌ای از اشیاء "rule_resource" است که به یک فایل قانون اشاره می‌کنند. فایل قانون شامل آرایه‌ای از اشیاء است که یک عمل و شرایطی را که در آن این اعمال فراخوانی می‌شوند، مشخص می‌کند.

موارد استفاده رایج

بخش‌های زیر موارد استفاده رایج برای درخواست‌های اعلانی شبکه را شرح می‌دهند. دستورالعمل‌های زیر فقط یک طرح کلی مختصر ارائه می‌دهند. اطلاعات بیشتر در مورد تمام اطلاعات موجود در اینجا در مرجع API تحت chrome.declarativeNetRequest شرح داده شده است.

مسدود کردن یک URL واحد

یک مورد استفاده رایج در Manifest V2 مسدود کردن درخواست‌های وب با استفاده از رویداد onBeforeRequest در اسکریپت پس‌زمینه بود.

اسکریپت پس‌زمینه Manifest V2 
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" حذف شده است زیرا محتوای مسدودکننده نیازی به مجوزهای میزبان ندارد. همانطور که در بالا نشان داده شده است، فایل قانون، میزبان یا میزبان‌هایی را که یک درخواست اعلانی net به آنها اعمال می‌شود، مشخص می‌کند.

اگر می‌خواهید این را امتحان کنید، کد زیر در مخزن نمونه‌های ما موجود است.

مانیفست نسخه ۲ 
  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]
مانیفست نسخه ۳ 
  "permissions": [
    "declarativeNetRequest",
  ]

چندین URL را ریدایرکت کنید

یکی دیگر از کاربردهای رایج در Manifest V2، استفاده از رویداد BeforeRequest برای هدایت درخواست‌های وب بود.

اسکریپت پس‌زمینه Manifest V2 
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، مسدود کردن کوکی‌ها مستلزم رهگیری هدرهای درخواست وب قبل از ارسال و حذف یک مورد خاص است.

اسکریپت پس‌زمینه Manifest V2 
chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    removeHeader(details.requestHeaders, 'cookie');
    return {requestHeaders: details.requestHeaders};
  },
  // filters
  {urls: ['https://*/*', 'http://*/*']},
  // extraInfoSpec
  ['blocking', 'requestHeaders', 'extraHeaders']);

مانیفست نسخه ۳ نیز این کار را با یک قانون در یک فایل قانون انجام می‌دهد. این بار نوع اکشن "modifyHeaders" است. این فایل آرایه‌ای از اشیاء "requestHeaders" را دریافت می‌کند که هدرهایی را که باید تغییر کنند و نحوه تغییر آنها را مشخص می‌کند. توجه داشته باشید که شیء "condition" فقط شامل یک آرایه "resourceTypes" است. این شیء از همان مقادیر مثال‌های قبلی پشتیبانی می‌کند.

اگر می‌خواهید این را امتحان کنید، کد زیر در مخزن نمونه‌های ما موجود است.

فایل مانیفست نسخه ۳ به صورت manifest.json 
[
  {
    "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": [
    ""
  ]