Thay thế việc chặn trình nghe yêu cầu web

Manifest V3 thay đổi cách tiện ích xử lý việc sửa đổi các yêu cầu mạng. Thay vì chặn các yêu cầu mạng và thay đổi chúng trong thời gian chạy bằng chrome.webRequest, tiện ích của bạn chỉ định các quy tắc mô tả những hành động cần thực hiện khi một nhóm điều kiện nhất định được đáp ứng. Hãy làm việc này bằng cách sử dụng Declarative Net Request API.

Web Request API và Declarative Net Request API có sự khác biệt đáng kể. Thay vì thay thế một lệnh gọi hàm bằng một lệnh gọi hàm khác, bạn cần viết lại mã theo các trường hợp sử dụng. Phần này sẽ hướng dẫn bạn thực hiện quy trình đó.

Bạn không cần thực hiện những thay đổi này nếu tiện ích của bạn được cài đặt theo chính sách. Đối với các tiện ích được cài đặt theo chính sách, quyền webRequestBlocking vẫn có trong Manifest V3.

Đây là phần thứ hai trong số ba phần mô tả những thay đổi cần thiết đối với mã không thuộc trình chạy dịch vụ của tiện ích. Tài liệu này mô tả cách chuyển đổi các yêu cầu chặn trên web (do Manifest V2 sử dụng) thành các yêu cầu mạng khai báo (do Manifest V3 sử dụng). Hai phần còn lại đề cập đến việc cập nhật mã cần thiết để di chuyển sang Manifest V3 và cải thiện tính bảo mật.

Giới thiệu

Trong Manifest V2, việc chặn các yêu cầu trên web có thể làm giảm đáng kể cả hiệu suất của tiện ích và hiệu suất của các trang mà tiện ích đó hoạt động cùng. Không gian tên webRequest hỗ trợ 9 sự kiện có khả năng chặn, mỗi sự kiện có số lượng trình xử lý sự kiện không giới hạn. Tệ hơn nữa, mỗi trang web có khả năng bị chặn bởi nhiều tiện ích và các quyền cần thiết cho việc này là xâm phạm. Manifest V3 ngăn chặn vấn đề này bằng cách thay thế các lệnh gọi lại bằng các quy tắc khai báo.

Cập nhật quyền

Thực hiện các thay đổi sau đối với trường "permissions" trong manifest.json.

  • Xoá quyền "webRequest" nếu bạn không cần theo dõi các yêu cầu mạng nữa.
  • Di chuyển Mẫu so khớp từ "permissions" sang "host_permissions".

Bạn sẽ cần thêm các quyền khác, tuỳ thuộc vào trường hợp sử dụng của mình. Những quyền đó được mô tả cùng với trường hợp sử dụng mà chúng hỗ trợ.

Tạo quy tắc khai báo yêu cầu mạng

Để tạo các quy tắc yêu cầu mạng khai báo, bạn cần thêm một đối tượng "declarative_net_request" vào manifest.json. Khối "declarative_net_request" chứa một mảng gồm các đối tượng "rule_resource" trỏ đến một tệp quy tắc. Tệp quy tắc chứa một mảng các đối tượng chỉ định một thao tác và các điều kiện mà trong đó những thao tác đó được gọi.

Các trường hợp sử dụng phổ biến

Các phần sau đây mô tả các trường hợp sử dụng phổ biến cho các yêu cầu mạng khai báo. Hướng dẫn bên dưới chỉ cung cấp thông tin vắn tắt. Bạn có thể xem thêm thông tin về tất cả thông tin tại đây trong tài liệu tham khảo về API trong phần chrome.declarativeNetRequest

Chặn một URL

Một trường hợp sử dụng phổ biến trong Manifest V2 là chặn các yêu cầu trên web bằng sự kiện onBeforeRequest trong tập lệnh nền.

Tập lệnh nền Manifest V2
chrome.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

Đối với Manifest V3, hãy tạo một quy tắc declarativeNetRequest mới bằng cách sử dụng loại hành động "block". Lưu ý đối tượng "condition" trong quy tắc ví dụ. "urlFilter" của nó sẽ thay thế lựa chọn urls được truyền đến trình nghe webRequest. Mảng "resourceTypes" chỉ định danh mục tài nguyên cần chặn. Ví dụ này chỉ chặn trang HTML chính, nhưng bạn có thể chỉ chặn phông chữ.

Tệp quy tắc Manifest V3
[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

Để tính năng này hoạt động, bạn cần cập nhật các quyền của tiện ích. Trong manifest.json, hãy thay thế quyền "webRequestBlocking" bằng quyền "declarativeNetRequest". Xin lưu ý rằng URL này sẽ bị xoá khỏi trường "permissions" vì việc chặn nội dung không yêu cầu quyền của máy chủ lưu trữ. Như minh hoạ ở trên, tệp quy tắc chỉ định (các) máy chủ mà một yêu cầu mạng khai báo áp dụng.

Nếu bạn muốn thử, mã dưới đây có trong kho lưu trữ mẫu của chúng tôi.

Manifest V2
  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]
Manifest V3
  "permissions": [
    "declarativeNetRequest",
  ]

Chuyển hướng nhiều URL

Một trường hợp sử dụng phổ biến khác trong Manifest V2 là sử dụng sự kiện BeforeRequest để chuyển hướng các yêu cầu trên web.

Tập lệnh nền 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"]
);

Đối với Manifest V3, hãy sử dụng loại hành động "redirect". Như trước đây, "urlFilter" sẽ thay thế lựa chọn url được truyền đến trình nghe webRequest. Xin lưu ý rằng trong ví dụ này, đối tượng "action" của tệp quy tắc chứa một trường "redirect" chứa URL cần trả về thay vì URL đang được lọc.

Tệp quy tắc Manifest V3
[
  {
    "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"]
    }
  }
]

Trường hợp này cũng yêu cầu thay đổi các quyền của tiện ích. Như trước đây, hãy thay thế quyền "webRequestBlocking" bằng quyền "declarativeNetRequest". Các URL này sẽ được di chuyển từ manifest.json sang một tệp quy tắc. Xin lưu ý rằng việc chuyển hướng cũng yêu cầu quyền "declarativeNetRequestWithHostAccess" ngoài quyền truy cập vào máy chủ lưu trữ.

Nếu bạn muốn thử, mã dưới đây có trong kho lưu trữ mẫu của chúng tôi.

Manifest V2
  "permissions": [
    "webRequestBlocking",
    "https://developer.chrome.com/docs/extensions/*",
    "https://developer.chrome.com/docs/extensions/reference"
  ]
Manifest V3
  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]

Chặn cookie

Trong Manifest V2, việc chặn cookie đòi hỏi phải chặn tiêu đề yêu cầu web trước khi chúng được gửi và xoá một tiêu đề cụ thể.

Tập lệnh nền 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 cũng thực hiện việc này bằng một quy tắc trong tệp quy tắc. Lần này, loại hành động là "modifyHeaders". Tệp này lấy một mảng các đối tượng "requestHeaders" chỉ định các tiêu đề cần sửa đổi và cách sửa đổi các tiêu đề đó. Xin lưu ý rằng đối tượng "condition" chỉ chứa một mảng "resourceTypes". Nó hỗ trợ các giá trị giống như các ví dụ trước.

Nếu bạn muốn thử, mã dưới đây có trong kho lưu trữ mẫu của chúng tôi.

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

Trường hợp này cũng yêu cầu thay đổi các quyền của tiện ích. Như trước đây, hãy thay thế quyền "webRequestBlocking" bằng quyền "declarativeNetRequest".

Manifest V2
  "permissions": [
    "webRequest",
    "webRequestBlocking",
    "https://*/*",
    "http://*/*"
  ],
Manifest V3
  "permissions": [
    "declarativeNetRequest",
  ],
  "host_permissions": [
    ""
  ]