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

שינוי של בקשות רשת ב-Manifest V3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

סקריפט רקע של מניפסט מגרסה V2
chrome.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

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

קובץ כלל של Manifest 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", בנוסף להרשאת המארח.

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

מניפסט מגרסה V2
  "permissions": [
    "webRequestBlocking",
    "https://developer.chrome.com/docs/extensions/*",
    "https://developer.chrome.com/docs/extensions/reference"
  ]
מניפסט V3
  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]

חסימת קובצי cookie

כדי לחסום קובצי cookie ב-Manifest 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". הוא תומך באותם ערכים כמו בדוגמאות הקודמות.

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

קובץ Manifest 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://*/*"
  ],
מניפסט V3
  "permissions": [
    "declarativeNetRequest",
  ],
  "host_permissions": [
    ""
  ]