החלפת פונקציות ה-listener של בקשות אינטרנט חוסמות

ב-Manifest V3 יש שינויים באופן שבו התוספים מטפלים בשינוי של בקשות רשת. במקום ליירט בקשות לרשת ולשנות אותן בזמן ריצה באמצעות browser.webRequest, התוסף מציין כללים שמתארים פעולות שיש לבצע כשמתקיימת קבוצה נתונה של תנאים. אפשר לעשות זאת באמצעות Declarative Net Request API.

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

אם התוסף מותקן באמצעות מדיניות, לא צריך לבצע את השינויים האלה. בתוספים שהותקנו לפי הגדרת האדמין, ההרשאה webRequestBlocking עדיין זמינה ב-Manifest V3.

זהו הקטע השני מתוך שלושה שמתארים את השינויים שצריך לבצע בקוד שלא שייך ל-service worker של התוסף. במאמר מוסבר איך להמיר בקשות אינטרנט חוסמות, שמשמשות ב-Manifest V2, לבקשות רשת הצהרתיות, שמשמשות ב-Manifest V3. שני החלקים האחרים עוסקים בעדכון הקוד שנדרש למעבר ל-Manifest V3 ובשיפור האבטחה.

מבוא

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

עדכון ההרשאות

מבצעים את השינויים הבאים בשדה "permissions" ב-manifest.json.

• מסירים את ההרשאה "webRequest" אם כבר לא צריך לצפות בבקשות לרשת.
• העברת דפוסי התאמה מ-"permissions" אל "host_permissions".

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

יצירת כללים דקלרטיביים של בקשות רשת

כדי ליצור כללים הצהרתיים של בקשות רשת, צריך להוסיף אובייקט "declarative_net_request" ל-manifest.json. הבלוק "declarative_net_request" מכיל מערך של אובייקטים מסוג "rule_resource" שמפנים לקובץ כללים. קובץ הכללים מכיל מערך של אובייקטים שמציינים פעולה ואת התנאים שבהם הפעולות האלה מופעלות.

תרחישים נפוצים לדוגמה

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

חסימה של כתובת URL יחידה

תרחיש נפוץ לשימוש ב-Manifest V2 היה חסימה של בקשות אינטרנט באמצעות האירוע onBeforeRequest בסקריפט הרקע.

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

ב-Manifest V3, יוצרים declarativeNetRequest כלל חדש באמצעות סוג הפעולה "block". שימו לב לאובייקט "condition" בכלל לדוגמה. הערך "urlFilter" מחליף את האפשרות urls שמועברת למאזין webRequest. מערך "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 כדי להפנות מחדש בקשות אינטרנט.

browser.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" action type. כמו קודם, "urlFilter" מחליף את האפשרות url שמועברת למאזין webRequest. שימו לב שבדוגמה הזו, אובייקט "action" בקובץ הכללים מכיל שדה "redirect" עם כתובת ה-URL שיוחזרה במקום כתובת ה-URL שמסוננת.

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

חסימת קובצי Cookie

ב-Manifest V2, חסימת קובצי Cookie מחייבת יירוט של כותרות בקשות האינטרנט לפני שהן נשלחות והסרה של כותרת ספציפית.

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