차단 웹 요청 리스너 교체

Manifest V3에서 네트워크 요청 수정

Manifest V3에서는 확장 프로그램이 네트워크 요청 수정을 처리하는 방식이 변경됩니다. 확장 프로그램은 네트워크 요청을 가로채고 chrome.webRequest를 사용하여 런타임에 이를 변경하는 대신, 지정된 조건 집합이 충족될 때 실행할 작업을 설명하는 규칙을 지정합니다. 선언형 네트워크 요청 API를 사용하여 이 작업을 실행합니다.

Web Request API와 Declarative Net Request API는 상당히 다릅니다. 한 함수 호출을 다른 함수 호출로 대체하는 대신 사용 사례 측면에서 코드를 다시 작성해야 합니다. 이 섹션에서는 이 프로세스를 안내합니다.

Manifest V2에서 웹 요청을 차단하면 확장 프로그램의 성능과 확장 프로그램이 작동하는 페이지의 성능이 모두 크게 저하될 수 있습니다. webRequest 네임스페이스는 각각 무제한 수의 이벤트 핸들러를 사용하는 9개의 잠재적으로 차단 이벤트를 지원합니다. 설상가상으로 각 웹페이지는 여러 확장 프로그램에 의해 차단될 수 있으며, 이때 필요한 권한은 침입적입니다. 매니페스트 V3는 콜백을 선언적 규칙으로 대체하여 이 문제를 방지합니다.

이 섹션은 확장 프로그램 서비스 워커에 포함되지 않는 코드에 필요한 변경사항을 설명하는 세 섹션 중 두 번째 섹션입니다. Manifest V2에서 사용하는 차단 웹 요청을 Manifest V3에서 사용하는 선언적 네트워크 요청으로 변환하는 방법을 설명합니다. 나머지 두 섹션에서는 Manifest V3로 이전하는 데 필요한 코드 업데이트와 보안 개선에 대해 설명합니다.

권한 업데이트

manifest.json의 "permissions" 필드를 다음과 같이 변경합니다.

  • 더 이상 네트워크 요청을 관찰할 필요가 없으면 "webRequest" 권한을 삭제합니다.
  • 일치 패턴을 "permissions"에서 "host_permissions"로 이동합니다.

사용 사례에 따라 다른 권한을 추가해야 합니다. 이러한 권한은 지원하는 사용 사례와 함께 설명됩니다.

선언적 네트워크 요청 규칙 만들기

선언적 순수 요청 규칙을 만들려면 manifest.json에 "declarative_net_request" 객체를 추가해야 합니다. "declarative_net_request" 블록에는 규칙 파일을 가리키는 "rule_resource" 객체의 배열이 포함됩니다. 규칙 파일에는 작업과 이러한 작업이 호출되는 조건을 지정하는 객체 배열이 포함됩니다.

일반적인 사용 사례

다음 섹션에서는 선언적 네트워크 요청의 일반적인 사용 사례를 설명합니다. 아래 안내는 간략한 개요만 제공합니다. 여기에 나와 있는 모든 정보에 관한 자세한 내용은 API 참조의 chrome.declarativeNetRequest에 설명되어 있습니다.

단일 URL 차단

매니페스트 V2의 일반적인 사용 사례는 백그라운드 스크립트에서 onBeforeRequest 이벤트를 사용하여 웹 요청을 차단하는 것이었습니다.

Manifest V2 백그라운드 스크립트
chrome.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

Manifest V3의 경우 "block" 작업 유형을 사용하여 새 declarativeNetRequest 규칙을 만듭니다. 예시 규칙에서 "condition" 객체를 확인합니다. "urlFilter"는 webRequest 리스너에 전달된 urls 옵션을 대체합니다. "resourceTypes" 배열은 차단할 리소스의 카테고리를 지정합니다. 이 예에서는 기본 HTML 페이지만 차단하지만, 예를 들어 글꼴만 차단할 수도 있습니다.

매니페스트 V3 규칙 파일
[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

이렇게 하려면 확장 프로그램의 권한을 업데이트해야 합니다. manifest.json에서 "webRequestBlocking" 권한을 "declarativeNetRequest" 권한으로 바꿉니다. 콘텐츠를 차단하는 데 호스트 권한이 필요하지 않으므로 URL이 "permissions" 필드에서 삭제됩니다. 위와 같이 규칙 파일은 선언적 네트워크 요청이 적용되는 호스트를 지정합니다.

이 방법을 사용해 보려면 아래 코드를 샘플 저장소에서 가져오세요.

Manifest V2
  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]
Manifest V3
  "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"는 webRequest 리스너에 전달된 url 옵션을 대체합니다. 이 예시에서 규칙 파일의 "action" 객체에는 필터링되는 URL 대신 반환할 URL이 포함된 "redirect" 필드가 포함되어 있습니다.

매니페스트 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"]
    }
  }

이 시나리오에서는 확장 프로그램의 권한도 변경해야 합니다. 이전과 마찬가지로 "webRequestBlocking" 권한을 "declarativeNetRequest" 권한으로 바꿉니다. URL이 다시 manifest.json에서 규칙 파일로 이동합니다. 리디렉션하려면 호스트 권한 외에도 "declarativeNetRequestWithHostAccess" 권한도 필요합니다.

이 방법을 사용해 보려면 아래 코드를 샘플 저장소에서 가져오세요.

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

쿠키 차단

매니페스트 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']);

Manifest V3도 규칙 파일의 규칙을 사용하여 이를 실행합니다. 이번에는 작업 유형이 "modifyHeaders"입니다. 이 파일은 수정할 헤더와 수정 방법을 지정하는 "requestHeaders" 객체 배열을 사용합니다. "condition" 객체에는 "resourceTypes" 배열만 포함되어 있습니다. 이전 예와 동일한 값을 지원합니다.

이 방법을 사용해 보려면 아래 코드를 샘플 저장소에서 가져오세요.

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

이 시나리오에서는 확장 프로그램의 권한도 변경해야 합니다. 이전과 마찬가지로 "webRequestBlocking" 권한을 "declarativeNetRequest" 권한으로 바꿉니다.

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