declarativeNetRequestFeedback Permission — Chrome Extension Reference

4 min read

declarativeNetRequestFeedback Permission — Chrome Extension Reference

Overview

Permission Relationship

The declarativeNetRequestFeedback permission is an addon to the base declarativeNetRequest permission:

Permission What it enables
declarativeNetRequest Define and use declarative rules to block/redirect/modify requests
declarativeNetRequestWithHostAccess Same as above + can redirect to URLs the extension doesn’t have host permissions for
declarativeNetRequestFeedback Read-only feedback on which rules matched (requires base DNR permission)

manifest.json Setup

{
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback"
  ]
}

Note: You must include declarativeNetRequest as well — declarativeNetRequestFeedback alone doesn’t grant rule capabilities.

API: onRuleMatchedDebug

The onRuleMatchedDebug event fires whenever a DNR rule matches a network request. This is useful for debugging and analytics.

Basic Usage

onRuleMatchedDebug Basic Usage

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener((info) => {
  console.log("Rule matched:", {
    ruleId: info.rule.ruleId,
    rulesetId: info.rule.rulesetId,
    requestId: info.request.requestId,
    url: info.request.url,
    method: info.request.method,
    type: info.request.type,
    tabId: info.request.tabId,
    frameId: info.request.frameId
  });
});

MatchedRuleInfo Properties

Property Type Description
rule.ruleId number ID of the matched rule
rule.rulesetId string ID of the ruleset containing the rule
request.requestId string Unique identifier for the request
request.tabId number ID of the tab that initiated the request
request.frameId number ID of the frame that initiated the request
request.url string URL of the request
request.method string HTTP method (GET, POST, etc.)
request.type string Resource type (script, image, xmlhttprequest, etc.)

Use Cases

Debugging Which Rules Fired

Rule Testing

Rule Analytics

Performance Considerations

Important: onRuleMatchedDebug is intended for development and debugging only. It has significant performance overhead:

Best Practice for Production

// Instead of always listening, query matched rules periodically
async function getMatchedRulesAnalysis() {
  const rules = await chrome.declarativeNetRequest.getMatchedRules();
  
  // Process rules array for analytics
  return rules.map(r => ({
    ruleId: r.rule.ruleId,
    url: r.request.url,
    type: r.request.type
  }));
}

Runtime Permission Check

import { checkPermission } from '@theluckystrike/webext-permissions';

const result = await checkPermission('declarativeNetRequestFeedback');
// Returns true if permission is granted

Common Errors

API Reference

Frequently Asked Questions

How do I get feedback on blocked requests?

Add “declarativeNetRequestFeedback” permission to receive onRuleMatchedDebug events showing which rules matched for each request.

Can I see which ads are being blocked?

Yes, with declarativeNetRequestFeedback, you can log or display statistics about matched rules and blocked requests. —

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.

No previous article
No next article