browser.declarativeNetRequest

תיאור

‫chrome.declarativeNetRequest API משמש לחסימה או לשינוי של בקשות לאחזור מהרשת על ידי ציון כללים הצהרתיים. כך התוספים יכולים לשנות בקשות לאחזור מהרשת בלי ליירט אותן ולראות את התוכן שלהן, וכך לשמור על פרטיות המשתמשים.

הרשאות

declarativeNetRequest
declarativeNetRequestWithHostAccess

ההרשאות "declarativeNetRequest" ו-"declarativeNetRequestWithHostAccess" מספקות את אותן יכולות. ההבדל ביניהן הוא מתי מבקשים או מעניקים את ההרשאות.

"declarativeNetRequest"
מפעיל אזהרת הרשאה בזמן ההתקנה, אבל מספק גישה משתמעת לכללים של allow, allowAllRequests ו-block. מומלץ להשתמש באפשרות הזו כשאפשר, כדי להימנע מהצורך לבקש גישה מלאה למארחים.
"declarativeNetRequestFeedback"
הפעלת תכונות לניפוי באגים בתוספים מסוג unpacked, במיוחד getMatchedRules() ו-onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
אזהרת הרשאה לא מוצגת בזמן ההתקנה, אבל צריך לבקש הרשאות מארח לפני שאפשר לבצע פעולה כלשהי במארח. האפשרות הזו מתאימה כשרוצים להשתמש בכללים של בקשות רשת הצהרתיות בתוסף שכבר יש לו הרשאות מארח, בלי ליצור אזהרות נוספות.

זמינות

‫Chrome 84 ואילך ‫browser.* ‎ מגרסת Chrome 148

מניפסט

בנוסף להרשאות שמתוארות למעלה, סוגים מסוימים של קבוצות כללים, במיוחד קבוצות כללים סטטיות, דורשים הצהרה על מפתח המניפסט "declarative_net_request", שצריך להיות מילון עם מפתח יחיד שנקרא "rule_resources". המפתח הזה הוא מערך שמכיל מילונים מסוג Ruleset, כמו שמוצג בהמשך. (שימו לב שהשם Ruleset לא מופיע ב-JSON של המניפסט כי הוא רק מערך). בהמשך המסמך הזה מוסבר על קבוצות כללים סטטיות.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback"
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

כללים וקבוצות כללים

כדי להשתמש ב-API הזה, צריך לציין קבוצת כללים אחת או יותר. קבוצת כללים מכילה מערך של כללים. כלל בודד מבצע אחת מהפעולות הבאות:

  • חסימת בקשה לאחזור מהרשת.
  • לשדרג את הסכימה (מ-http ל-https).
  • כדי למנוע חסימה של בקשה, אפשר לבטל את כל כללי החסימה התואמים.
  • הפניה אוטומטית של בקשה לאחזור מהרשת.
  • לשנות כותרות של בקשות או תגובות.

יש שלושה סוגים של קבוצות כללים, והניהול שלהם שונה מעט.

דינמית
הם נשמרים בין סשנים בדפדפן ושדרוגים של התוסף, ומנוהלים באמצעות JavaScript כשהתוסף בשימוש.
סשן
הנתונים נמחקים כשהדפדפן נסגר וכשמותקנת גרסה חדשה של התוסף. כללי הסשן מנוהלים באמצעות JavaScript בזמן שמשתמשים בתוסף.
סטטי
הם נארזים, מותקנים ומתעדכנים כשמתקינים או משדרגים תוסף. כללים סטטיים מאוחסנים בקובצי כללים בפורמט JSON ומופיעים בקובץ המניפסט.

קבוצות כללים דינמיות וברמת הסשן

קבוצות כללים דינמיות וקבוצות כללים של סשנים מנוהלות באמצעות JavaScript בזמן שמשתמשים בתוסף.

  • כללים דינמיים נשמרים בסשנים של הדפדפן ובשדרוגים של התוספים.
  • כללי הסשן נמחקים כשהדפדפן נסגר וכשמותקנת גרסה חדשה של התוסף.

יש רק סוג אחד של כל אחד מהכללים האלה. תוסף יכול להוסיף או להסיר כללים באופן דינמי על ידי קריאה ל-updateDynamicRules() ול-updateSessionRules(), בתנאי שלא חורגים ממגבלות הכללים. מידע נוסף על מגבלות של כללים זמין במאמר מגבלות של כללים. אפשר לראות דוגמה לכך בקטע דוגמאות קוד.

קבוצות כללים סטטיות

בניגוד לכללים דינמיים ולכללים של סשן, כללים סטטיים נארזים, מותקנים ומתעדכנים כשהתוסף מותקן או משודרג. הם מאוחסנים בקובצי כללים בפורמט JSON, שמצוינים בתוסף באמצעות המפתחות "declarative_net_request" ו-"rule_resources" כפי שמתואר למעלה, וגם מילון אחד או יותר של Ruleset. מילון Ruleset מכיל נתיב לקובץ הכללים, מזהה של קבוצת הכללים שכלולה בקובץ, וציון אם קבוצת הכללים מופעלת או מושבתת. שני המאפיינים האחרונים חשובים כשמפעילים או משביתים קבוצת כללים באופן פרוגרמטי.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

כדי לבדוק קובצי כללים, טוענים את התוסף כשהוא לא ארוז. שגיאות ואזהרות לגבי כללים סטטיים לא תקינים מוצגות רק לתוספים לא ארוזים. המערכת מתעלמת מכללים סטטיים לא תקינים בתוספים ארוזים.

בדיקה מהירה

יכול להיות ששינויים בקבוצות כללים סטטיות יהיו זכאים לבדיקה מזורזת. בדיקה מזורזת של שינויים שעומדים בדרישות

הפעלה והשבתה של כללים וקבוצות כללים סטטיים

אפשר להפעיל או להשבית גם כללים סטטיים ספציפיים וגם קבוצות שלמות של כללים סטטיים בזמן הריצה.

קבוצת הכללים הסטטיים וקבוצות הכללים שמופעלים נשמרת בסשנים של הדפדפן. אף אחד מהם לא נשמר בין עדכוני התוסף, כלומר רק הכללים שבחרתם להשאיר בקובצי הכללים זמינים אחרי עדכון.

מסיבות שקשורות לביצועים, יש גם מגבלות על מספר הכללים וקבוצות הכללים שאפשר להפעיל בו-זמנית. כדי לבדוק כמה כללים נוספים אפשר להפעיל, צריך להתקשר למספר getAvailableStaticRuleCount(). מידע נוסף על מגבלות של כללים זמין במאמר מגבלות של כללים.

כדי להפעיל או להשבית כללים סטטיים, צריך להפעיל את updateStaticRules(). השיטה הזו מקבלת אובייקט UpdateStaticRulesOptions, שמכיל מערכים של מזהי כללים להפעלה או להשבתה. המזהים מוגדרים באמצעות המפתח "id" של המילון Ruleset. אפשר להשבית עד 5,000 כללים סטטיים.

כדי להפעיל או להשבית קבוצות כללים סטטיות, צריך להפעיל את updateEnabledRulesets(). השיטה הזו מקבלת אובייקט UpdateRulesetOptions, שמכיל מערכים של מזהים של קבוצות כללים להפעלה או להשבתה. המזהים מוגדרים באמצעות המפתח "id" של המילון Ruleset.

יצירת כללים

לא משנה מה סוג הכלל, הוא מתחיל בארבעה שדות, כמו שמוצג בהמשך. המפתחות "id" ו-"priority" מקבלים מספר, אבל המפתחות "action" ו-"condition" יכולים לספק כמה תנאים לחסימה ולהפניה אוטומטית. הכלל הבא חוסם את כל בקשות הסקריפטים שמקורן ב-"foo.com" לכל כתובת URL עם "abc" כמחרוזת משנה.

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

התאמה לכתובת URL

Declarative Net Request מאפשר להתאים כתובות URL באמצעות תחביר של התאמת תבניות או ביטויים רגולריים.

תחביר של מסנן כתובות URL

המפתח "condition" של כלל מאפשר למפתח "urlFilter" לפעול בכתובות URL בדומיין שצוין. כדי ליצור תבניות, משתמשים באסימונים להתאמת דפוסים. הנה כמה דוגמאות.

urlFilter התאמות לא תואם
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz
https://a.example.company		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

ביטויים רגולריים

אפשר להשתמש בתנאים גם בביטויים רגולריים. שימו לב למפתח "regexFilter". במאמר כללים שמשתמשים בביטויים רגולריים מפורט מידע על המגבלות שחלות על התנאים האלה.

איך לכתוב תנאים טובים לכתובות URL

כשכותבים כללים, חשוב להקפיד שהם תמיד יתאימו לדומיין שלם. אחרת, יכול להיות שהכלל יתאים למצבים לא צפויים. לדוגמה, כשמשתמשים בתחביר של התאמה לתבנית:

  • המאפיין google.com תואם באופן שגוי לערך https://example.com/?param=google.com
  • המאפיין ||google.com תואם באופן שגוי לערך https://google.company
  • המאפיין https://www.google.com תואם באופן שגוי לערך https://example.com/?param=https://www.google.com

כדאי להשתמש ב:

  • ‫||google.com/, שתואם לכל הנתיבים ולכל תת-הדומיינים.
  • |https://www.google.com/, שתואם לכל הנתיבים ולא לתת-דומיינים.

באופן דומה, משתמשים בתווים ^ ו-/ כדי לעגן ביטוי רגולרי. לדוגמה, ^https:\/\/www\.google\.com\/ תואם לכל נתיב ב-https://www.google.com.

הערכת הכלל

הדפדפן מחיל את כללי ה-DNR בשלבים שונים של מחזור החיים של הבקשה לאחזור מהרשת.

לפני הבקשה

לפני שמתבצעת בקשה, תוסף יכול לחסום אותה או להפנות אותה לכתובת אחרת (כולל שדרוג הסכימה מ-HTTP ל-HTTPS) באמצעות כלל תואם.

לכל תוסף, הדפדפן קובע רשימה של כללים תואמים. כללים עם פעולת modifyHeaders לא נכללים כאן כי הם יטופלו בהמשך. בנוסף, כללים עם תנאי responseHeaders יישקלו בשלב מאוחר יותר (כשכותרות התגובה יהיו זמינות) והם לא נכללים.

לאחר מכן, לכל תוסף, Chrome בוחר לכל היותר מועמד אחד לכל בקשה. ‫Chrome מוצא כלל תואם על ידי סידור כל הכללים התואמים לפי עדיפות. כללים עם אותה עדיפות מסודרים לפי פעולה (allow או allowAllRequests > block > upgradeScheme > redirect).

אם המועמד הוא כלל allow או allowAllRequests, או אם המסגרת שבה הבקשה מתבצעת תאמה בעבר לכלל allowAllRequests בעדיפות גבוהה יותר או שווה מהתוסף הזה, הבקשה "מותרת" ולתוסף לא תהיה השפעה על הבקשה.

אם יותר מתוסף אחד רוצה לחסום את הבקשה הזו או להפנות אותה לכתובת אחרת, נבחרת פעולה אחת לביצוע. כדי לעשות את זה, Chrome ממיין את הכללים לפי הסדר הבא: block > redirect או upgradeScheme > allow או allowAllRequests. אם שני כללים הם מאותו סוג, Chrome בוחר את הכלל מהתוסף שהותקן לאחרונה.

לפני שליחת כותרות הבקשות

לפני ש-Chrome שולח כותרות של בקשות לשרת, הכותרות מתעדכנות על סמך כללי modifyHeaders תואמים.

בתוסף אחד, Chrome יוצר את רשימת השינויים לביצוע על ידי איתור כל כללי modifyHeaders התואמים. בדומה למצב הקודם, רק כללים עם עדיפות גבוהה יותר מכל כללי allow או allowAllRequests תואמים נכללים.

הכללים האלה מופעלים על ידי Chrome בסדר שבו כללים מתוסף שהותקן לאחרונה תמיד נבדקים לפני כללים מתוסף ישן יותר. בנוסף, כללים בעדיפות גבוהה יותר מתוסף מסוים תמיד חלים לפני כללים בעדיפות נמוכה יותר מאותו תוסף. חשוב לציין שגם בתוספים:

  • אם כלל מוסיף לכותרת, כללים בעדיפות נמוכה יותר יכולים רק להוסיף לכותרת הזו. אי אפשר להגדיר ולהסיר פעולות.
  • אם כלל מגדיר כותרת, רק כללים בעדיפות נמוכה יותר מאותו תוסף יכולים להוסיף לכותרת הזו. אסור לבצע שינויים אחרים.
  • אם כלל מסיר כותרת, כללים בעדיפות נמוכה יותר לא יכולים לשנות את הכותרת.

אחרי שמתקבלת תשובה

אחרי שכותרות התגובה מתקבלות, Chrome מעריך את הכללים עם תנאי responseHeaders.

אחרי מיון הכללים האלה לפי action ו-priority והחרגת כל הכללים שהפכו למיותרים בגלל כלל allow או allowAllRequests תואם (זה קורה באופן זהה לשלבים בקטע "לפני הבקשה"), Chrome עשוי לחסום או להפנות מחדש את הבקשה בשם תוסף.

חשוב לדעת: אם בקשה הגיעה לשלב הזה, היא כבר נשלחה לשרת והשרת קיבל נתונים כמו גוף הבקשה. כלל חסימה או הפניה אוטומטית עם תנאי של כותרות תגובה עדיין יפעל, אבל לא יוכל לחסום את הבקשה או להפנות אותה אוטומטית.

במקרה של כלל חסימה, הדף ששלח את הבקשה מקבל תגובה שהבקשה נחסמה, ו-Chrome מסיים את הבקשה מוקדם. במקרה של כלל הפניה אוטומטית, Chrome שולח בקשה חדשה לכתובת ה-URL שאליה המשתמש מופנה. חשוב לבדוק אם ההתנהגויות האלה עומדות בציפיות בנוגע לפרטיות בתוסף.

אם הבקשה לא נחסמת או מופנית לכתובת אחרת, Chrome מחיל את כללי modifyHeaders. החלת שינויים על כותרות תגובה פועלת באותו אופן שמתואר בקטע "לפני שליחת כותרות הבקשה". החלת שינויים על כותרות של בקשות לא עושה כלום, כי הבקשה כבר נשלחה.

כללים בטוחים

כללים בטוחים מוגדרים ככללים עם הפעולה block,‏ allow,‏ allowAllRequests או upgradeScheme. הכללים האלה כפופים למכסה מוגדלת של כללים דינמיים.

מגבלות על כללים

יש תקורה של ביצועים לטעינה ולהערכה של כללים בדפדפן, ולכן חלות מגבלות מסוימות כשמשתמשים ב-API. המגבלות תלויות בסוג הכלל שבו משתמשים.

כללים סטטיים

כללים סטטיים הם כללים שצוינו בקובצי כללים שהוצהרו בקובץ המניפסט. תוסף יכול לציין עד 100 קבוצות כללים סטטיות כחלק ממפתח המניפסט "rule_resources", אבל אפשר להפעיל רק 50 קבוצות כללים כאלה בכל פעם. האפשרות השנייה נקראת MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. ביחד, קבוצות הכללים האלה כוללות לפחות 30,000 כללים. זה נקרא GUARANTEED_MINIMUM_STATIC_RULES.

מספר הכללים שזמינים אחרי זה תלוי במספר הכללים שמופעלים על ידי כל התוספים שמותקנים בדפדפן של המשתמש. אפשר למצוא את המספר הזה בזמן הריצה באמצעות קריאה ל-getAvailableStaticRuleCount(). אפשר לראות דוגמה לכך בקטע דוגמאות קוד.

כללי סשן

תוסף יכול לכלול עד 5,000 כללי סשן. הוא מוצג בתור MAX_NUMBER_OF_SESSION_RULES.

בגרסאות ישנות יותר מ-Chrome 120, הייתה מגבלה של 5,000 כללים דינמיים וכללי סשן ביחד.

כללים דינמיים

תוסף יכול לכלול לפחות 5,000 כללים דינמיים. הוא מוצג בתור MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

החל מגרסה 121 של Chrome, יש מגבלה גדולה יותר של 30,000 כללים שזמינים לכללים דינמיים בטוחים, שמוצגים בתור MAX_NUMBER_OF_DYNAMIC_RULES. כל כלל לא בטוח שנוסף במסגרת המגבלה של 5,000 כללים ייספר גם הוא במגבלה הזו.

בגרסאות ישנות יותר מ-Chrome 120, הייתה מגבלה של 5,000 כללים דינמיים וכללי סשן משולבים.

כללים שמשתמשים בביטויים רגולריים

אפשר להשתמש בביטויים רגולריים בכל סוגי הכללים, אבל המספר הכולל של כללי ביטויים רגולריים מכל סוג לא יכול להיות יותר מ-1,000. המספר הזה נקרא MAX_NUMBER_OF_REGEX_RULES.

בנוסף, כל כלל צריך להיות קטן מ-2KB אחרי ההידור. הזמן הזה תלוי במורכבות של הכלל. אם תנסו לטעון כלל שחורג מהמגבלה הזו, תופיע אזהרה כמו זו שבהמשך והמערכת תתעלם מהכלל.

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

אינטראקציות עם קובצי שירות (service workers)

‫declarativeNetRequest חל רק על בקשות שמגיעות למקבץ הרשת (network stack). זה כולל תגובות ממטמון ה-HTTP, אבל יכול להיות שלא כולל תגובות שעוברות דרך ה-handler onfetch של ה-Service Worker. ‏declarativeNetRequest לא ישפיע על תגובות שנוצרו על ידי ה-Service Worker או שאוחזרו מ-CacheStorage, אבל הוא ישפיע על קריאות ל-fetch() שבוצעו ב-Service Worker.

מקורות מידע נגישים באינטרנט

כלל declarativeNetRequest לא יכול להפנות מבקשת משאב ציבורי למשאב שלא נגיש באינטרנט. אם תנסו לעשות את זה, תופיע שגיאה. זה נכון גם אם המשאב שצוין שנגיש באינטרנט נמצא בבעלות התוסף שמבצע את ההפניה האוטומטית. כדי להצהיר על משאבים ל-declarativeNetRequest, משתמשים במערך "web_accessible_resources" של המניפסט.

שינוי הכותרת

פעולת ה-append נתמכת רק ב-request headers הבאים: accept, accept-encoding, accept-language, access-control-request-headers, cache-control, connection, content-language, cookie, forwarded, if-match, if-none-match, keep-alive, range, te, trailer, transfer-encoding, upgrade, user-agent, via, want-digest, x-forwarded-for. רשימת ההיתרים הזו תלוית אותיות רישיות (באג 449152902).

כשמוסיפים לכותרת של בקשה או כותרת תגובה, הדפדפן ישתמש במפריד המתאים כשאפשר.

דוגמאות

דוגמאות לקוד

עדכון כללים דינמיים

בדוגמה הבאה אפשר לראות איך קוראים ל-updateDynamicRules(). התהליך זהה גם ב-updateSessionRules().

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await browser.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await browser.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

עדכון של קבוצות כללים סטטיות

בדוגמה הבאה מוסבר איך להפעיל ולהשבית קבוצות של כללים, תוך התחשבות במספר קבוצות הכללים הסטטיות הזמינות ובמספר המקסימלי של קבוצות הכללים הסטטיות המופעלות. כדאי לעשות את זה כשמספר הכללים הסטטיים שאתם צריכים חורג מהמספר המותר. כדי שזה יעבוד, צריך להתקין חלק מקבוצות הכללים כשהן מושבתות (הגדרת "Enabled" ל-false בקובץ המניפסט).

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await browser.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > browser.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await browser.declarativeNetRequest.updateEnabledRulesets(options);
}

דוגמאות לכללים

הדוגמאות הבאות ממחישות איך Chrome מתעדף כללים בתוסף. כשבודקים את הכללים, כדאי לפתוח את הכללים של קביעת סדר העדיפויות בחלון נפרד.

המפתח "priority"

הדוגמאות האלה דורשות הרשאת מארח ל-*://*.example.com/*.

כדי לחשב את העדיפות של כתובת URL מסוימת, צריך לבדוק את המפתח "priority" (שמוגדר על ידי המפתח), את המפתח "action" ואת המפתח "urlFilter". הדוגמאות האלה מתייחסות לקובץ הכללים לדוגמה שמוצג מתחתיהן.

ניווט אל https://google.com
שני כללים חלים על כתובת ה-URL הזו: הכללים עם המזהים 1 ו-4. הכלל עם המזהה 1 חל כי לפעולות "block" יש עדיפות גבוהה יותר מאשר לפעולות "redirect". שאר הכללים לא חלים כי הם מיועדים לכתובות URL ארוכות יותר.
ניווט אל https://google.com/1234
בגלל שכתובת ה-URL ארוכה יותר, הכלל עם מזהה 2 תואם עכשיו בנוסף לכללים עם מזהים 1 ו-4. הכלל עם המזהה 2 חל כי ל-"allow" יש עדיפות גבוהה יותר מאשר ל-"block" ול-"redirect".
ניווט אל https://google.com/12345
כל ארבעת הכללים תואמים לכתובת ה-URL הזו. הכלל עם מזהה 3 חל כי העדיפות שהוגדרה לו על ידי המפתח היא הגבוהה ביותר בקבוצה.
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "||google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "||google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
]

הפניות אוטומטיות

בדוגמה הבאה נדרשת הרשאת מארח ל-*://*.example.com/*.

בדוגמה הבאה אפשר לראות איך להפנות בקשה מ-example.com לדף בתוך התוסף עצמו. נתיב התוסף /a.jpg מפנה אל chrome-extension://EXTENSION_ID/a.jpg, כאשר EXTENSION_ID הוא המזהה של התוסף. כדי שזה יעבוד, המניפסט צריך להצהיר על /a.jpg כמשאב נגיש באינטרנט.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "||https://www.example.com/",
    "resourceTypes": ["main_frame"]
  }
}

בדוגמה הבאה, המפתח "transform" משמש להפניה אוטומטית לתת-דומיין של example.com. הוא משתמש בעוגן של שם דומיין ("||") כדי ליירט בקשות עם כל סכימה מ-example.com. המפתח "scheme" ב-"transform" מציין שהפניות אוטומטיות לתת-הדומיין תמיד ישתמשו ב-"https".

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com/",
    "resourceTypes": ["main_frame"]
  }
}

בדוגמה הבאה נעשה שימוש בביטויים רגולריים כדי להפנות מ-https://www.abc.xyz.com/path אל https://abc.xyz.com/path. במפתח "regexFilter", שימו לב איך הנקודות מופיעות עם תו בריחה ושהקבוצה לחילוץ בוחרת את "abc" או את "def". המפתח "regexSubstitution" מציין את ההתאמה הראשונה שהוחזרה של הביטוי הרגולרי באמצעות "\1". במקרה הזה, הערך "abc" נלקח מכתובת ה-URL להפניה אוטומטית ומוצב בהחלפה.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

כותרות

בדוגמה הבאה, כל קובצי ה-Cookie מוסרים גם מהמסגרת הראשית וגם מכל מסגרות המשנה.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

סוגים

DomainType

השדה הזה מתאר אם הבקשה היא של צד ראשון או של צד שלישי למסגרת שבה היא נוצרה. בקשה נחשבת לבקשה מצד ראשון אם יש לה את אותו דומיין (eTLD+1) כמו למסגרת שבה הבקשה נוצרה.

טיפוסים בני מנייה (enum)

"firstParty"
הבקשה לאחזור מהרשת היא צד ראשון למסגרת שבה היא נוצרה.

‫"thirdParty"
הבקשה לאחזור מהרשת היא של צד שלישי למסגרת שבה היא נוצרה.

ExtensionActionOptions

‫Chrome 88 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

  • displayActionCountAsBadgeText

    בוליאני אופציונלי

    ההגדרה קובעת אם להציג באופן אוטומטי את מספר הפעולות בדף כטקסט התג של התוסף. ההעדפה הזו נשמרת בכל הסשנים.

  • tabUpdate

    ‫TabActionCountUpdate אופציונלי

    ‫Chrome 89 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    פרטים על האופן שבו צריך לשנות את מספר הפעולות בכרטיסייה.

GetDisabledRuleIdsOptions

‫Chrome 111 ואילך browser.* ‎ מ-Chrome 148

מאפיינים

  • rulesetId

    מחרוזת

    המזהה שתואם ל-Ruleset סטטי.

GetRulesFilter

‫Chrome 111 ואילך browser.* ‎ מ-Chrome 148

מאפיינים

  • ruleIds

    number[] אופציונלי

    אם מציינים מזהים, רק כללים עם מזהים תואמים נכללים.

HeaderInfo

‫Chrome 128 ואילך ‫‎browser.* ‎ מגרסה Chrome 148

מאפיינים

  • excludedValues

    string[] אופציונלי

    אם התנאי הזה צוין, הוא לא יתקיים אם הכותרת קיימת אבל הערך שלה מכיל לפחות רכיב אחד ברשימה הזו. התחביר של תבנית ההתאמה זהה לזה של values.

  • כותרת

    מחרוזת

    שם הכותרת. התנאי הזה תואם לשם רק אם לא צוינו גם values וגם excludedValues.

  • ערכים

    string[] אופציונלי

    אם התנאי הזה צוין, הוא מתקיים אם הערך של הכותרת תואם לפחות לתבנית אחת ברשימה הזו. התכונה הזו תומכת בהתאמה של ערכי כותרות ללא תלות ברישיות, וגם במבנים הבאים:

    ‫'*' : תואם לכל מספר של תווים.

    ‫'?' : תואם לאפס תווים או לתו אחד.

    אפשר להוסיף לוכסן הפוך לפני התווים "*" ו-"?", למשל "‎\*‎" ו-"‎\?‎"

HeaderOperation

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148

כאן מתוארות הפעולות האפשריות לכלל modifyHeaders.

טיפוסים בני מנייה (enum)

‫"append"
הוספת רשומה חדשה לכותרת שצוינה. כשמשנים את הכותרות של בקשה, הפעולה הזו נתמכת רק בכותרות ספציפיות.

"set"
מגדיר ערך חדש לכותרת שצוינה, ומסיר כותרות קיימות עם אותו שם.

"remove"
מסיר את כל הרשומות של הכותרת שצוינה.

IsRegexSupportedResult

‫Chrome 87 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

מאפיינים

  • isSupported

    בוליאני

  • reason

    ‫UnsupportedRegexReason אופציונלי

    מציין את הסיבה לכך שהביטוי הרגולרי לא נתמך. השדה הזה מופיע רק אם הערך של isSupported הוא false.

MatchedRule

מאפיינים

  • ruleId

    number

    מזהה של כלל תואם.

  • rulesetId

    מחרוזת

    המזהה של Ruleset שהכלל הזה שייך אליו. בכלל שמקורו בקבוצת הכללים הדינמיים, הערך יהיה שווה ל-DYNAMIC_RULESET_ID.

MatchedRuleInfo

מאפיינים

  • כלל

    MatchedRule

  • tabId

    number

    ה-tabId של הכרטיסייה שממנה הגיעה הבקשה, אם הכרטיסייה עדיין פעילה. אחרת, הערך הוא ‎-1.

  • timeStamp

    number

    המועד שבו הכלל הותאם. חותמות הזמן יתאימו למוסכמה של JavaScript לזמנים, כלומר מספר אלפיות השנייה מאז תחילת התקופה.

MatchedRuleInfoDebug

מאפיינים

MatchedRulesFilter

מאפיינים

  • minTimeStamp

    מספר אופציונלי

    אם מציינים את הפרמטר הזה, המערכת תתאים רק כללים שנוצרו אחרי חותמת הזמן שצוינה.

  • tabId

    מספר אופציונלי

    אם צוין, תואם רק לכללים של הכרטיסייה הנתונה. אם הערך מוגדר כ-1-, המדיניות תואמת לכללים שלא משויכים לאף כרטיסייה פעילה.

ModifyHeaderInfo

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148

מאפיינים

  • כותרת

    מחרוזת

    שם הכותרת שרוצים לשנות.

  • פעולה

    HeaderOperation

    הפעולה שתתבצע בכותרת.

  • ערך

    מחרוזת אופציונלי

    הערך החדש של הכותרת. חובה לציין את המאפיין הזה בפעולות append ו-set.

QueryKeyValue

מאפיינים

  • מקש

    מחרוזת

  • replaceOnly

    בוליאני אופציונלי

    ‫Chrome 94 ואילך ‫browser.* ‎ החל מ-Chrome 148

    אם הערך הוא True, מפתח השאילתה מוחלף רק אם הוא כבר קיים. אחרת, המפתח יתווסף גם אם הוא חסר. ברירת המחדל היא False.

  • ערך

    מחרוזת

QueryTransform

מאפיינים

  • addOrReplaceParams

    QueryKeyValue[] אופציונלי

    רשימת צמדי המפתח/ערך של השאילתה שצריך להוסיף או להחליף.

  • removeParams

    string[] אופציונלי

    רשימת מפתחות השאילתה שצריך להסיר.

Redirect

מאפיינים

  • extensionPath

    מחרוזת אופציונלי

    הנתיב היחסי לספריית התוספים. הוא צריך להתחיל ב-'/'.

  • regexSubstitution

    מחרוזת אופציונלי

    תבנית החלפה לכללים שמציינים regexFilter. ההתאמה הראשונה של regexFilter בכתובת ה-URL תוחלף בתבנית הזו. בתוך regexSubstitution, אפשר להשתמש בספרות עם תו בריחה של לוכסן הפוך (‎\1 עד ‎\9) כדי להוסיף את הקבוצות לחילוץ המתאימות. ‫\0 מתייחס לכל הטקסט התואם.

  • ונבצע טרנספורמציה

    URLTransform אופציונלי

    טרנספורמציות של כתובות URL שצריך לבצע.

  • url

    מחרוזת אופציונלי

    כתובת ה-URL להפניה אוטומטית. אסור להפנות לכתובות URL של JavaScript.

RegexOptions

‫Chrome 87 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

מאפיינים

  • isCaseSensitive

    בוליאני אופציונלי

    אם הערך שצוין ב-regex תלוי אותיות רישיות. ערך ברירת המחדל הוא true.

  • ביטוי רגולרי (regex)

    מחרוזת

    הביטוי הרגולרי שצריך לבדוק.

  • requireCapturing

    בוליאני אופציונלי

    אם צריך לתעד את ה-regex שצוין. צריך להגדיר תיעוד רק לכללי הפניה אוטומטית שמציינים פעולת regexSubstition. ערך ברירת המחדל הוא False.

RequestDetails

מאפיינים

  • documentId

    מחרוזת אופציונלי

    ‫Chrome 106 ואילך browser.* ‎ מגרסה 148 של Chrome

    המזהה הייחודי של המסמך של המסגרת, אם הבקשה הזו מיועדת למסגרת.

  • documentLifecycle

    DocumentLifecycle אופציונלי

    ‫Chrome 106 ואילך browser.* ‎ מגרסה 148 של Chrome

    מחזור החיים של מסמך המסגרת, אם הבקשה הזו מיועדת למסגרת.

  • frameId

    number

    הערך 0 מציין שהבקשה מתרחשת במסגרת הראשית. ערך חיובי מציין את המזהה של מסגרת משנה שבה הבקשה מתרחשת. אם המסמך של מסגרת (משנה) נטען (type הוא main_frame או sub_frame), frameId מציין את המזהה של המסגרת הזו, ולא את המזהה של המסגרת החיצונית. מזהי המסגרות הם ייחודיים בכרטיסייה.

  • frameType

    ‫FrameType אופציונלי

    ‫Chrome 106 ואילך browser.* ‎ מגרסה 148 של Chrome

    סוג המסגרת, אם הבקשה היא למסגרת.

  • הגורם היוזם

    מחרוזת אופציונלי

    המקור שממנו נשלחה הבקשה. ההגדרה הזו לא משתנה בהפניות אוטומטיות. אם המקור אטום, המערכת תשתמש במחרוזת "null".

  • method

    מחרוזת

    שיטת HTTP רגילה.

  • parentDocumentId

    מחרוזת אופציונלי

    ‫Chrome 106 ואילך browser.* ‎ מגרסה 148 של Chrome

    המזהה הייחודי של מסמך האב של המסגרת, אם הבקשה הזו מיועדת למסגרת ויש לה מסגרת אב.

  • parentFrameId

    number

    מזהה המסגרת שעוטפת את המסגרת ששלחה את הבקשה. אם אין מסגרת אב, הערך הוא ‎-1.

  • requestId

    מחרוזת

    מזהה הבקשה. מזהי הבקשות הם ייחודיים לסשן בדפדפן.

  • tabId

    number

    מזהה הכרטיסייה שבה מתבצעת הבקשה. הערך מוגדר כ-1- אם הבקשה לא קשורה לכרטיסייה.

  • סוג

    ResourceType

    סוג המשאב של הבקשה.

  • url

    מחרוזת

    כתובת ה-URL של הבקשה.

RequestMethod

‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

השדה הזה מתאר את שיטת בקשת ה-HTTP של בקשה לאחזור מהרשת.

טיפוסים בני מנייה (enum)

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

כאן מתואר סוג המשאב של הבקשה לאחזור מהרשת.

טיפוסים בני מנייה (enum)

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

מאפיינים

  • פעולה

    RuleAction

    הפעולה שצריך לבצע אם יש התאמה לכלל הזה.

  • תנאי

    RuleCondition

    התנאי שבו הכלל הזה מופעל.

  • id [מזהה]

    number

    מזהה ייחודי של כלל. חובה, וצריך להיות >= 1.

  • הקמפיין

    מספר אופציונלי

    עדיפות הכלל. ברירת המחדל היא 1. אם מציינים את הערך, הוא צריך להיות גדול מ-1 או שווה לו.

RuleAction

מאפיינים

  • הפניה לכתובת אתר אחרת

    הפניה לכתובת אחרת אופציונלי

    מתאר איך לבצע את ההפניה האוטומטית. רלוונטי רק לכללי הפניה אוטומטית.

  • requestHeaders

    ModifyHeaderInfo[] אופציונלי

    ‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148

    כותרות הבקשה שצריך לשנות בבקשה. תקף רק אם RuleActionType הוא modifyHeaders.

  • responseHeaders

    ModifyHeaderInfo[] אופציונלי

    ‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148

    כותרות התגובה שצריך לשנות בבקשה. תקף רק אם RuleActionType הוא modifyHeaders.

  • סוג הפעולה שרוצים לבצע.

RuleActionType

תיאור של סוג הפעולה שצריך לבצע אם יש התאמה ל-RuleCondition נתון.

טיפוסים בני מנייה (enum)

"block"
חסימת הבקשה לאחזור מהרשת.

"redirect"
הפניה מחדש של הבקשה לאחזור מהרשת.

"allow"
אישור הבקשה לאחזור מהרשת. הבקשה לא תופסק אם יש כלל "אישור" שתואם לה.

‫"upgradeScheme"
שדרוג הסכימה של כתובת ה-URL של הבקשה לאחזור מהרשת ל-https אם הבקשה היא http או ftp.

‫"modifyHeaders"
שינוי כותרות של בקשות או תגובות מהבקשה לאחזור מהרשת.

‫"allowAllRequests"
אישור כל הבקשות בהיררכיית מסגרות, כולל בקשת המסגרת עצמה.

RuleCondition

מאפיינים

  • domainType

    DomainType אופציונלי

    מציין אם הבקשה לאחזור מהרשת היא של צד ראשון או של צד שלישי לדומיין שממנו היא הגיעה. אם לא מציינים את הפרמטר, כל הבקשות מתקבלות.

  • דומיינים

    string[] אופציונלי

    הוצאה משימוש בגרסה Chrome 101

    במקום זאת, אתם צריכים להשתמש ב-initiatorDomains

    הכלל יתאים רק לבקשות לאחזור מהרשת שמקורן ברשימה של domains.

  • excludedDomains

    string[] אופציונלי

    הוצאה משימוש בגרסה Chrome 101

    במקום זאת, אתם צריכים להשתמש ב-excludedInitiatorDomains

    הכלל לא יתאים לבקשות לאחזור מהרשת שמקורן ברשימת excludedDomains.

  • excludedInitiatorDomains

    string[] אופציונלי

    ‫Chrome 101 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

    הכלל לא יתאים לבקשות לאחזור מהרשת שמקורן ברשימת excludedInitiatorDomains. אם הרשימה ריקה או לא קיימת, לא יוחרגו דומיינים. ההגדרה הזו מקבלת עדיפות על פני initiatorDomains.

    הערות:

    • אפשר גם להשתמש בתת-דומיינים כמו "a.example.com".
    • הערכים חייבים להכיל רק תווי ASCII.
    • בדומיינים בינלאומיים, צריך להשתמש בקידוד Punycode.
    • ההתאמה הזו מתבצעת מול יוזם הבקשה ולא מול כתובת ה-URL של הבקשה.
    • גם תת-דומיינים של הדומיינים שברשימה מוחרגים.
  • excludedRequestDomains

    string[] אופציונלי

    ‫Chrome 101 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

    הכלל לא יתאים לבקשות לאחזור מהרשת כשהדומיינים תואמים לאחד מהדומיינים ברשימה של excludedRequestDomains. אם הרשימה ריקה או לא קיימת, לא יוחרגו דומיינים. ההגדרה הזו מקבלת עדיפות על פני requestDomains.

    הערות:

    • אפשר גם להשתמש בתת-דומיינים כמו "a.example.com".
    • הערכים חייבים להכיל רק תווי ASCII.
    • בדומיינים בינלאומיים, צריך להשתמש בקידוד Punycode.
    • גם תת-דומיינים של הדומיינים שברשימה מוחרגים.
  • excludedRequestMethods

    RequestMethod[] אופציונלי

    ‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    רשימה של שיטות בקשה שהכלל לא יתאים להן. צריך לציין רק אחד מהשדות requestMethods ו-excludedRequestMethods. אם לא מציינים אף אחת מהן, מתבצעת התאמה לכל שיטות הבקשה.

  • excludedResourceTypes

    ResourceType[] אופציונלי

    רשימה של סוגי משאבים שהכלל לא יתאים להם. צריך לציין רק אחד מהשדות resourceTypes ו-excludedResourceTypes. אם אף אחד מהם לא צוין, כל סוגי המשאבים נחסמים, חוץ מ-"main_frame".

  • excludedResponseHeaders

    HeaderInfo[] אופציונלי

    ‫Chrome 128 ואילך ‫‎browser.* ‎ מגרסה Chrome 148

    הכלל לא תואם אם הבקשה תואמת לתנאי כלשהו של כותרת תגובה ברשימה הזו (אם צוינה). אם מציינים גם את excludedResponseHeaders וגם את responseHeaders, המאפיין excludedResponseHeaders מקבל עדיפות.

  • excludedTabIds

    number[] אופציונלי

    ‫Chrome 92 ואילך ‫browser.* ‎ מגרסה Chrome 148

    רשימה של tabs.Tab.id שהכלל לא אמור להתאים להם. מזהה של tabs.TAB_ID_NONE מחריג בקשות שלא מגיעות מכרטיסייה. האפשרות הזו נתמכת רק בכללים ברמת הסשן.

  • excludedTopDomains

    string[] אופציונלי

    ‫Chrome מגרסה 145 ואילך ‫browser.* ‎ מ-Chrome מגרסה 148

    הכלל לא יתאים לבקשות לאחזור מהרשת כשהדומיין של המסגרת המשויכת ברמה העליונה תואם לאחד מהדומיינים ברשימה של excludedTopDomains. אם הרשימה ריקה או לא קיימת, לא יוחרגו דומיינים. ההגדרה הזו מקבלת עדיפות על פני topDomains.

    הערות:

    • אפשר גם להשתמש בתת-דומיינים כמו "a.example.com".
    • הערכים חייבים להכיל רק תווי ASCII.
    • בדומיינים בינלאומיים, צריך להשתמש בקידוד Punycode.
    • גם תת-דומיינים של הדומיינים שברשימה מוחרגים.
    • בבקשות שאין להן מסגרת ברמה העליונה (למשל, בקשות שנשלחות על ידי ServiceWorker), המערכת מתייחסת לדומיין של יוזם הבקשה.
  • initiatorDomains

    string[] אופציונלי

    ‫Chrome 101 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

    הכלל יתאים רק לבקשות לאחזור מהרשת שמקורן ברשימה של initiatorDomains. אם הרשימה מושמטת, הכלל חל על בקשות מכל הדומיינים. אסור להשתמש ברשימה ריקה.

    הערות:

    • אפשר גם להשתמש בתת-דומיינים כמו "a.example.com".
    • הערכים חייבים להכיל רק תווי ASCII.
    • בדומיינים בינלאומיים, צריך להשתמש בקידוד Punycode.
    • ההתאמה הזו מתבצעת מול יוזם הבקשה ולא מול כתובת ה-URL של הבקשה.
    • גם תת-דומיינים של הדומיינים שברשימה נכללים בהתאמה.
  • isUrlFilterCaseSensitive

    בוליאני אופציונלי

    אם urlFilter או regexFilter (מה שצוין) תלוי אותיות רישיות. ברירת המחדל היא false.

  • regexFilter

    מחרוזת אופציונלי

    ביטוי רגולרי שיתאים לכתובת ה-URL של הבקשה לאחזור מהרשת. התחביר של הביטויים הרגולריים הוא RE2.

    הערה: אפשר לציין רק את urlFilter או את regexFilter.

    הערה: הערך של regexFilter יכול להכיל רק תווים מסוג ASCII. התבנית הזו מושווית לכתובת URL שבה המארח מקודד בפורמט punycode (במקרה של דומיינים בינלאומיים) וכל תו אחר שאינו ASCII מקודד ב-URL ב-utf-8.

  • requestDomains

    string[] אופציונלי

    ‫Chrome 101 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

    הכלל יתאים לבקשות לאחזור מהרשת רק אם הדומיין תואם לאחד מהדומיינים ברשימה של requestDomains. אם הרשימה מושמטת, הכלל חל על בקשות מכל הדומיינים. אסור להשתמש ברשימה ריקה.

    הערות:

    • אפשר גם להשתמש בתת-דומיינים כמו "a.example.com".
    • הערכים חייבים להכיל רק תווי ASCII.
    • בדומיינים בינלאומיים, צריך להשתמש בקידוד Punycode.
    • גם תת-דומיינים של הדומיינים שברשימה נכללים בהתאמה.
  • requestMethods

    RequestMethod[] אופציונלי

    ‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    רשימה של שיטות בקשת HTTP שהכלל יכול להתאים להן. אסור להשתמש ברשימה ריקה.

    הערה: אם מציינים תנאי כלל של requestMethods, גם בקשות שאינן מסוג HTTP(s)‎ יוחרגו, ואילו אם מציינים excludedRequestMethods, הן לא יוחרגו.

  • resourceTypes

    ResourceType[] אופציונלי

    רשימה של סוגי משאבים שהכלל יכול להתאים להם. אסור להשתמש ברשימה ריקה.

    הערה: צריך לציין את זה לכללי allowAllRequests, והם יכולים לכלול רק את סוגי המשאבים sub_frame ו-main_frame.

  • responseHeaders

    HeaderInfo[] אופציונלי

    ‫Chrome 128 ואילך ‫‎browser.* ‎ מגרסה Chrome 148

    הכלל תואם אם הבקשה תואמת לתנאי כלשהו של כותרת תגובה ברשימה הזו (אם צוין).

  • tabIds

    number[] אופציונלי

    ‫Chrome 92 ואילך ‫browser.* ‎ מגרסה Chrome 148

    רשימה של tabs.Tab.id שהכלל צריך להתאים להם. מזהה של tabs.TAB_ID_NONE תואם לבקשות שלא מגיעות מכרטיסייה. אסור להשתמש ברשימה ריקה. האפשרות הזו נתמכת רק בכללים ברמת הסשן.

  • topDomains

    string[] אופציונלי

    ‫Chrome מגרסה 145 ואילך ‫browser.* ‎ מ-Chrome מגרסה 148

    הכלל יתאים לבקשות לאחזור מהרשת רק כשהדומיין של המסגרת המשויכת ברמה העליונה תואם לאחד מהדומיינים ברשימה של topDomains. אם הרשימה מושמטת, הכלל חל על בקשות שמשויכות לכל הדומיינים של המסגרות ברמה העליונה. אסור להשתמש ברשימה ריקה.

    הערות:

    • אפשר גם להשתמש בתת-דומיינים כמו "a.example.com".
    • הערכים חייבים להכיל רק תווי ASCII.
    • בדומיינים בינלאומיים, צריך להשתמש בקידוד Punycode.
    • גם תת-דומיינים של הדומיינים שברשימה נכללים בהתאמה.
    • בבקשות שאין להן מסגרת ברמה העליונה (למשל, בקשות שנשלחות על ידי ServiceWorker), המערכת מתייחסת לדומיין של יוזם הבקשה.
  • urlFilter

    מחרוזת אופציונלי

    התבנית שמושוות לכתובת ה-URL של הבקשה לאחזור מהרשת. מבנים נתמכים:

    '*' : תו כללי לחיפוש: תואם לכל מספר של תווים.

    '|' : עוגן שמאלי/ימני: אם משתמשים בו באחד מקצוות התבנית, הוא מציין את ההתחלה/הסוף של כתובת ה-URL בהתאמה.

    '||' : עוגן של שם דומיין: אם משתמשים בו בתחילת התבנית, הוא מציין את ההתחלה של דומיין (או תת-דומיין) של כתובת ה-URL.

    ‫'^' : תו מפריד: התו הזה תואם לכל דבר חוץ מאות, ספרה או אחד מהתווים הבאים: _,‏ -,‏ . או %. הביטוי הזה תואם גם לסוף של כתובת ה-URL.

    לכן, urlFilter מורכב מהחלקים הבאים: (עוגן אופציונלי של שם דומיין/שמאל) + תבנית + (עוגן אופציונלי של ימין).

    אם משמיטים את המאפיין, כל כתובות ה-URL יותאמו. אי אפשר להשתמש במחרוזת ריקה.

    אסור להשתמש בתבנית שמתחילה ב-||*. במקום זאת, אתם צריכים להשתמש ב-*.

    הערה: אפשר לציין רק את urlFilter או את regexFilter.

    הערה: הערך של urlFilter יכול להכיל רק תווים מסוג ASCII. התבנית הזו מושווית לכתובת URL שבה המארח מקודד בפורמט punycode (במקרה של דומיינים בינלאומיים) וכל תו אחר שאינו ASCII מקודד ב-URL ב-utf-8. לדוגמה, כשכתובת ה-URL של הבקשה היא http://abc.рф?q=ф, הערך של urlFilter יושווה לכתובת ה-URL‏ http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

‫Chrome מגרסה 145 ואילך ‫browser.* ‎ מ-Chrome מגרסה 148

טיפוסים בני מנייה (enum)

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

מאפיינים

  • פעיל

    בוליאני

    אם קבוצת הכללים מופעלת כברירת מחדל.

  • id [מזהה]

    מחרוזת

    מחרוזת לא ריקה שמזהה באופן ייחודי את קבוצת הכללים. מזהים שמתחילים ב-'_' שמורים לשימוש פנימי.

  • נתיב

    מחרוזת

    הנתיב של קבוצת הכללים ב-JSON ביחס לספריית התוספים.

RulesMatchedDetails

מאפיינים

  • rulesMatchedInfo

    MatchedRuleInfo[]

    כללים שתואמים למסנן שצוין.

TabActionCountUpdate

‫Chrome 89 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

  • הוסף

    number

    הערך שבו מספר הפעולות בכרטיסייה יגדל. ערכים שליליים יקטינו את הספירה.

  • tabId

    number

    הכרטיסייה שבה רוצים לעדכן את מספר הפעולות.

TestMatchOutcomeResult

‫Chrome 103 ואילך ‫browser.* ‎ מגרסה Chrome 148

מאפיינים

  • matchedRules

    MatchedRule[]

    הכללים (אם יש כאלה) שתואמים לבקשה ההיפותטית.

TestMatchRequestDetails

‫Chrome 103 ואילך ‫browser.* ‎ מגרסה Chrome 148

מאפיינים

  • הגורם היוזם

    מחרוזת אופציונלי

    כתובת ה-URL של הגורם המפעיל (אם יש כזה) של הבקשה ההיפותטית.

  • method

    ‫RequestMethod אופציונלי

    שיטת HTTP סטנדרטית של הבקשה ההיפותטית. אם לא מגדירים את הפרמטר, ברירת המחדל היא "get" לבקשות HTTP, והוא לא רלוונטי לבקשות שהן לא HTTP.

  • responseHeaders

    object optional

    ‫Chrome 129 ואילך ‫‎browser.* ‎ מ-Chrome 148

    הכותרות שסופקו על ידי תגובה היפותטית אם הבקשה לא נחסמת או מופנית מחדש לפני שהיא נשלחת. מיוצג כאובייקט שממפה שם של כותרת לרשימה של ערכי מחרוזת. אם לא מציינים כותרות, התגובה ההיפותטית תחזיר כותרות תגובה ריקות, שיכולות להתאים לכללים שמתאימים למצב שבו אין כותרות. לדוגמה: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    מספר אופציונלי

    מזהה הכרטיסייה שבה מתרחשת הבקשה ההיפותטית. לא צריך להתאים למזהה כרטיסייה אמיתי. ערך ברירת המחדל הוא ‎-1, כלומר הבקשה לא קשורה לכרטיסייה.

  • topUrl

    מחרוזת אופציונלי

    ‫Chrome מגרסה 145 ואילך ‫browser.* ‎ מ-Chrome מגרסה 148

    כתובת ה-URL של המסגרת ברמה העליונה שמשויכת לבקשה (אם יש כזו).

  • סוג

    ResourceType

    סוג המשאב של הבקשה ההיפותטית.

  • url

    מחרוזת

    כתובת ה-URL של הבקשה ההיפותטית.

UnsupportedRegexReason

‫Chrome 87 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

מתאר את הסיבה לכך שביטוי רגולרי מסוים לא נתמך.

טיפוסים בני מנייה (enum)

"syntaxError"
הביטוי הרגולרי לא תקין מבחינה תחבירית, או שהוא משתמש בתכונות שלא זמינות בתחביר RE2.

"memoryLimitExceeded"
הביטוי הרגולרי חורג ממגבלת הזיכרון.

UpdateRuleOptions

‫Chrome 87 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

מאפיינים

  • addRules

    Rule[] אופציונלי

    כללים להוספה.

  • removeRuleIds

    number[] אופציונלי

    המזהים של הכללים שרוצים להסיר. המערכת תתעלם ממזהים לא תקינים.

UpdateRulesetOptions

‫Chrome 87 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

מאפיינים

  • disableRulesetIds

    string[] אופציונלי

    קבוצת המזהים שתואמים ל-Ruleset סטטי שצריך להשבית.

  • enableRulesetIds

    string[] אופציונלי

    קבוצת המזהים שתואמת ל-Ruleset סטטי שצריך להפעיל.

UpdateStaticRulesOptions

‫Chrome 111 ואילך browser.* ‎ מ-Chrome 148

מאפיינים

  • disableRuleIds

    number[] אופציונלי

    קבוצת מזהים שתואמים לכללים ב-Ruleset שצריך להשבית.

  • enableRuleIds

    number[] אופציונלי

    קבוצת מזהים שתואמים לכללים ב-Ruleset שצריך להפעיל.

  • rulesetId

    מחרוזת

    המזהה שתואם ל-Ruleset סטטי.

URLTransform

מאפיינים

  • מקטע (fragment)

    מחרוזת אופציונלי

    הקטע החדש של הבקשה. השדה צריך להיות ריק, ובמקרה כזה המקטע הקיים נמחק, או להתחיל בתו "#".

  • מארח

    מחרוזת אופציונלי

    המארח החדש של הבקשה.

  • סיסמה

    מחרוזת אופציונלי

    הסיסמה החדשה לבקשה.

  • נתיב

    מחרוזת אופציונלי

    הנתיב החדש של הבקשה. אם השדה ריק, הנתיב הקיים נמחק.

  • יציאה

    מחרוזת אופציונלי

    היציאה החדשה לבקשה. אם השדה ריק, היציאה הקיימת נמחקת.

  • שאילתה

    מחרוזת אופציונלי

    השאילתה החדשה לבקשה. השדה צריך להיות ריק, ובמקרה כזה השאילתה הקיימת נמחקת, או להתחיל בסימן "?".

  • queryTransform

    ‫QueryTransform אופציונלי

    להוסיף, להסיר או להחליף צמדי מפתח/ערך של שאילתות.

  • סכמה

    מחרוזת אופציונלי

    הסכימה החדשה של הבקשה. הערכים המותרים הם "http",‏ "https",‏ "ftp" ו-"chrome-extension".

  • שם משתמש

    מחרוזת אופציונלי

    שם המשתמש החדש לבקשה.

מאפיינים

DYNAMIC_RULESET_ID

מזהה קבוצת הכללים של הכללים הדינמיים שהתוסף הוסיף.

ערך

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

מרווח הזמן שבו אפשר לבצע MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules שיחות, בדקות. קריאות נוספות ייכשלו באופן מיידי ויוגדר runtime.lastError. הערה: קריאות ל-getMatchedRules שמשויכות לתנועה של המשתמש פטורות מהמכסה.

ערך

10

GUARANTEED_MINIMUM_STATIC_RULES

‫Chrome 89 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

המספר המינימלי של כללים סטטיים שמובטחים לתוסף בכל קבוצות הכללים הסטטיים המופעלות שלו. כל הכללים מעבר למגבלה הזו ייספרו כחלק מהמגבלה הגלובלית על כללים סטטיים.

ערך

30,000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

מספר הפעמים שאפשר להתקשר אל getMatchedRules בפרק זמן של GETMATCHEDRULES_QUOTA_INTERVAL.

ערך

20

MAX_NUMBER_OF_DYNAMIC_RULES

המספר המקסימלי של כללים דינמיים שתוסף יכול להוסיף.

ערך

30,000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

‫Chrome 94 ואילך ‫browser.* ‎ החל מ-Chrome 148

המספר המקסימלי של Rulesets סטטיים שתוסף יכול להפעיל בכל זמן נתון.

ערך

50

MAX_NUMBER_OF_REGEX_RULES

המספר המקסימלי של כללי ביטויים רגולריים שתוסף יכול להוסיף. המגבלה הזו נבדקת בנפרד לגבי קבוצת הכללים הדינמיים ולגבי הכללים שצוינו בקובץ המשאבים של הכללים.

ערך

1,000

MAX_NUMBER_OF_SESSION_RULES

‫Chrome מגרסה 120 ואילך ‫browser.* ‎ מ-Chrome 148

המספר המקסימלי של כללים ברמת הסשן שתוסף יכול להוסיף.

ערך

5,000

MAX_NUMBER_OF_STATIC_RULESETS

המספר המקסימלי של Rulesets סטטיים שתוסף יכול לציין כחלק ממפתח המניפסט "rule_resources".

ערך

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

‫Chrome מגרסה 120 ואילך ‫browser.* ‎ מ-Chrome 148

המספר המקסימלי של כללים דינמיים "לא בטוחים" שתוסף יכול להוסיף.

ערך

5,000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

‫Chrome מגרסה 120 ואילך ‫browser.* ‎ מ-Chrome 148

המספר המקסימלי של כללים "לא בטוחים" ברמת הסשן שתוסף יכול להוסיף.

ערך

5,000

SESSION_RULESET_ID

‫Chrome 90 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מזהה קבוצת הכללים של הכללים ברמת הסשן שהתוסף הוסיף.

ערך

"_session"

Methods

getAvailableStaticRuleCount()

‫Chrome 89 ואילך ‫browser.* ‎ מגרסה 148 של Chrome 
browser.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

הפונקציה מחזירה את מספר הכללים הסטטיים שתוסף יכול להפעיל לפני שמגיעים למגבלת הכללים הסטטיים הגלובלית.

החזרות

  • Promise<number>

    ‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

getDisabledRuleIds()

‫Chrome 111 ואילך browser.* ‎ מ-Chrome 148 
browser.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

הפונקציה מחזירה את רשימת הכללים הסטטיים ב-Ruleset הנתון שמושבתים כרגע.

פרמטרים

החזרות

  • Promise<number[]>

    הבטחה שמתקבלת עם רשימה של מזהים שתואמים לכללים המושבתים בקבוצת הכללים הזו.

getDynamicRules()

browser.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

הפונקציה מחזירה את קבוצת הכללים הדינמיים הנוכחית של התוסף. אפשר גם לסנן את רשימת הכללים שנשלפו על ידי ציון filter.

פרמטרים

  • סינון

    GetRulesFilter אופציונלי

    ‫Chrome 111 ואילך browser.* ‎ מ-Chrome 148

    אובייקט לסינון רשימת הכללים שאוחזרו.

החזרות

  • Promise<Rule[]>

    ‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    Promise שמתקבלת עם קבוצת הכללים הדינמיים. יכול להיות שה-Promise יידחה במקרה של שגיאות פנימיות זמניות.

getEnabledRulesets()

browser.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

הפונקציה מחזירה את המזהים של קבוצת כללי הסינון הסטטיים שמופעלים כרגע.

החזרות

  • Promise<string[]>

    ‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    הבטחה (Promise) שמובילה לרשימה של מזהים, שבה כל מזהה תואם ל-Ruleset סטטי מופעל.

getMatchedRules()

browser.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
): Promise<RulesMatchedDetails>

הפונקציה מחזירה את כל הכללים שתואמים לתוסף. המתקשרים יכולים לסנן את רשימת הכללים התואמים על ידי ציון filter. השיטה הזו זמינה רק לתוספים עם ההרשאה "declarativeNetRequestFeedback" או עם ההרשאה "activeTab" שניתנה ל-tabId שצוין ב-filter. הערה: כללים שלא משויכים למסמך פעיל שהותאמו לפני יותר מחמש דקות לא יוחזרו.

פרמטרים

  • סינון

    ‫MatchedRulesFilter אופציונלי

    אובייקט לסינון רשימת הכללים התואמים.

החזרות

  • ‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    הבטחה שמתקיימת אחרי שאוחזרה רשימת הכללים התואמים. אם תהיה שגיאה, ה-Promise יידחה. יכולות להיות לכך כמה סיבות, כמו הרשאות לא מספיקות או חריגה מהמכסה.

getSessionRules()

‫Chrome 90 ואילך ‫browser.* ‎ מגרסה 148 של Chrome 
browser.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

הפונקציה מחזירה את קבוצת הכללים הנוכחית ברמת הסשן של התוסף. אפשר גם לסנן את רשימת הכללים שנשלפו על ידי ציון filter.

פרמטרים

  • סינון

    GetRulesFilter אופציונלי

    ‫Chrome 111 ואילך browser.* ‎ מ-Chrome 148

    אובייקט לסינון רשימת הכללים שאוחזרו.

החזרות

  • Promise<Rule[]>

    ‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    הבטחה (Promise) שמתקיימת עם קבוצת הכללים ברמת הסשן.

isRegexSupported()

‫Chrome 87 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome 
browser.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

בודק אם הביטוי הרגולרי הנתון ייתמך כתנאי לכלל regexFilter.

פרמטרים

  • regexOptions

    RegexOptions

    הביטוי הרגולרי שרוצים לבדוק.

החזרות

  • ‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    הבטחה שמתקיימת עם פרטים שכוללים את המידע אם הביטוי הרגולרי נתמך, ואם לא, את הסיבה לכך.

setExtensionActionOptions()

‫Chrome 88 ואילך ‫browser.* ‎ מגרסה 148 של Chrome 
browser.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

ההגדרה קובעת אם מספר הפעולות בכרטיסיות יוצג כטקסט התג של פעולת התוסף, ומספקת דרך להגדיל את מספר הפעולות.

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

testMatchOutcome()

‫Chrome 103 ואילך ‫browser.* ‎ מגרסה Chrome 148 
browser.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

הפונקציה בודקת אם אחד מהכללים של declarativeNetRequest של התוסף תואם לבקשה היפותטית. הערה: האפשרות הזו זמינה רק לתוספים לא ארוזים, כי היא מיועדת לשימוש רק במהלך פיתוח התוסף.

פרמטרים

החזרות

  • הבטחה (Promise) שמתקבלת עם הפרטים של הכללים התואמים.

updateDynamicRules()

browser.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise<void>

משנה את קבוצת הכללים הדינמיים הנוכחית של התוסף. הכללים עם המזהים שמופיעים ב-options.removeRuleIds יוסרו קודם, ואז יתווספו הכללים שמופיעים ב-options.addRules. הערות:

  • העדכון הזה מתבצע כפעולה אטומית אחת: או שכל הכללים שצוינו נוספים ומוסרים, או שמוחזרת שגיאה.
  • הכללים האלה נשמרים בסשנים של הדפדפן ובעדכונים של התוספים.
  • אי אפשר להסיר כללים סטטיים שצוינו כחלק מחבילת התוסף באמצעות הפונקציה הזו.
  • ‫MAX_NUMBER_OF_DYNAMIC_RULES הוא המספר המקסימלי של כללים דינמיים שתוסף יכול להוסיף. מספר הכללים הלא בטוחים לא יכול להיות גדול מ-MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

פרמטרים

  • אפשרויות

    UpdateRuleOptions

    ‫Chrome 87 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

החזרות

  • Promise<void>

    ‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    הבטחה שמתקיימת כשהעדכון מסתיים. אם תהיה שגיאה, ההבטחה תידחה ולא יבוצע שינוי בקבוצת הכללים. זה יכול לקרות מכמה סיבות, כמו פורמט כלל לא חוקי, מזהה כלל כפול, חריגה ממגבלת מספר הכללים, שגיאות פנימיות ועוד.

updateEnabledRulesets()

browser.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise<void>

מעדכן את קבוצת כללי הסטטיים שמופעלים בתוסף. קודם כל, קבוצות הכללים עם המזהים שמופיעים ב-options.disableRulesetIds יוסרו, ואז יתווספו קבוצות הכללים שמופיעות ב-options.enableRulesetIds. חשוב לזכור שהקבוצה של קובצי הכללים הסטטיים שמופעלים נשמרת בין סשנים, אבל לא בין עדכוני תוספים. כלומר, מפתח המניפסט rule_resources יקבע את הקבוצה של קובצי הכללים הסטטיים שמופעלים בכל עדכון של תוסף.

פרמטרים

  • אפשרויות

    UpdateRulesetOptions

    ‫Chrome 87 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

החזרות

  • Promise<void>

    ‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    הבטחה שמתקיימת כשהעדכון מסתיים. אם תהיה שגיאה, ההבטחה תידחה ולא יבוצע שינוי בקבוצת כללי הסינון שהופעלו. זה יכול לקרות מכמה סיבות, כמו מזהים לא חוקיים של קבוצות כללים, חריגה ממגבלת מספר הכללים או שגיאות פנימיות.

updateSessionRules()

‫Chrome 90 ואילך ‫browser.* ‎ מגרסה 148 של Chrome 
browser.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

שינוי קבוצת הכללים הנוכחית ברמת הסשן של התוסף. הכללים עם המזהים שמופיעים ב-options.removeRuleIds יוסרו קודם, ואז יתווספו הכללים שמופיעים ב-options.addRules. הערות:

  • העדכון הזה מתבצע כפעולה אטומית אחת: או שכל הכללים שצוינו נוספים ומוסרים, או שמוחזרת שגיאה.
  • הכללים האלה לא נשמרים בין סשנים, אלא נשמרים בזיכרון.
  • ‫MAX_NUMBER_OF_SESSION_RULES הוא המספר המקסימלי של כללי סשן שתוסף יכול להוסיף.

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    הבטחה שמתקיימת כשהעדכון מסתיים. אם תהיה שגיאה, ההבטחה תידחה ולא יבוצע שינוי בקבוצת הכללים. יכולות להיות לכך כמה סיבות, כמו פורמט כלל לא חוקי, מזהה כלל כפול, חריגה ממגבלת מספר הכללים ועוד.

updateStaticRules()

‫Chrome 111 ואילך browser.* ‎ מ-Chrome 148 
browser.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

משבית ומפעיל כללים סטטיים ספציפיים ב-Ruleset. שינויים בכללים ששייכים לRuleset מושבת ייכנסו לתוקף בפעם הבאה שהוא יופעל.

פרמטרים

החזרות

  • Promise<void>

    הבטחה שמתקיימת כשהעדכון מסתיים. אם תהיה שגיאה, ה-promise יידחה ולא יבוצע שינוי בכללים הסטטיים המופעלים.

אירועים

onRuleMatchedDebug

browser.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

מופעל כשכלל תואם לבקשה. האפשרות הזו זמינה רק לתוספים לא ארוזים עם ההרשאה "declarativeNetRequestFeedback", כי היא מיועדת למטרות ניפוי באגים בלבד.

פרמטרים