차단 웹 요청 리스너 교체

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

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

Web Request API와 선언형 Net Request API는 상당한 차이가 있습니다. 함수 호출을 다른 함수 호출로 대체하는 대신 사용 사례의 코드를 다시 작성해야 합니다. 이 섹션에서는 그 과정을 안내합니다.

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

이 섹션은 확장 프로그램 서비스 워커의 일부가 아닌 코드에 필요한 변경사항을 설명하는 세 개의 섹션 중 두 번째 섹션입니다. Manifest V2에서 사용되는 차단 웹 요청을 Manifest V3에서 사용하는 선언적 net 요청으로 변환하는 방법을 설명합니다. 다른 두 섹션에서는 Manifest V3로 이전하고 보안을 개선하는 데 필요한 코드 업데이트를 다룹니다.

권한 업데이트

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

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

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

선언적 순 요청 규칙 만들기

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

일반적인 사용 사례

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

단일 URL 차단하기

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

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

Manifest V3의 경우 "block" 작업 유형을 사용하여 새 declarativeNetRequest 규칙을 만듭니다. 규칙 예에 있는 "condition" 객체를 확인합니다. "urlFilter"는 webRequest 리스너에 전달된 urls 옵션을 대체합니다. "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"는 webRequest 리스너에 전달된 url 옵션을 대체합니다. 이 예에서 규칙 파일의 "action" 객체에는 필터링되는 URL 대신 반환할 URL이 포함된 "redirect" 필드가 포함됩니다.

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