ב-Manifest V3, התוספים מטפלים בשינוי של בקשות רשת בצורה שונה. במקום ליירט בקשות רשת ולשנות אותן בזמן ריצה באמצעות chrome.webRequest, התוסף מציין כללים שמתארים פעולות לביצוע כשמתקיימת קבוצה נתונה של תנאים. אפשר לעשות את זה באמצעות Declarative Net Request API.
יש הבדלים משמעותיים בין Web Request API לבין Declarative Net Request API. במקום להחליף קריאה לפונקציה אחת בקריאה לפונקציה אחרת, צריך לכתוב מחדש את הקוד בהתאם לתרחישי השימוש. בקטע הזה נסביר איך עושים את זה.
אם התוסף מותקן באמצעות מדיניות, לא צריך לבצע את השינויים האלה. לגבי תוספים שהותקנו באמצעות מדיניות, ההרשאה webRequestBlocking עדיין זמינה ב-Manifest V3.
זהו הקטע השני מתוך שלושה שמתארים את השינויים שצריך לבצע בקוד שלא שייך ל-service worker של התוסף. במאמר הזה מוסבר איך להמיר חסימה של בקשות אינטרנט, שמשמשת במניפסט V2, לבקשות רשת הצהרתיות, שמשמשות במניפסט V3. שני הסעיפים האחרים עוסקים בעדכון הקוד שנדרש למעבר ל-Manifest V3 ובשיפור האבטחה.
מבוא
ב-Manifest V2, חסימה של בקשות אינטרנט עלולה לפגוע באופן משמעותי בביצועים של התוספים וגם בביצועים של הדפים שהם פועלים בהם. מרחב השמות webRequest תומך בתשעה אירועים שעלולים לחסום, וכל אחד מהם מקבל מספר בלתי מוגבל של handlers של אירועים. מה שגרוע יותר, כל דף אינטרנט עלול להיחסם על ידי כמה תוספים, וההרשאות שנדרשות לכך פולשניות. מניפסט V3 מגן מפני הבעיה הזו על ידי החלפת קריאות חוזרות (callback) בכללים הצהרתיים.
עדכון ההרשאות
מבצעים את השינויים הבאים בשדה "permissions" ב-manifest.json.
- מסירים את ההרשאה
"webRequest"אם כבר לא צריך לצפות בבקשות לרשת. - העברת דפוסי התאמה מ-
"permissions"אל"host_permissions".
תצטרכו להוסיף הרשאות אחרות, בהתאם לתרחיש השימוש. ההרשאות האלה מתוארות לפי תרחיש השימוש שהן תומכות בו.
יצירת כללים דקלרטיביים של בקשות רשת
כדי ליצור כללים הצהרתיים לבקשות רשת, צריך להוסיף אובייקט "declarative_net_request" ל-manifest.json. הבלוק "declarative_net_request" מכיל מערך של אובייקטים מסוג "rule_resource" שמפנים לקובץ כללים. קובץ הכללים מכיל מערך של אובייקטים שמציינים פעולה ואת התנאים שבהם הפעולות האלה מופעלות.
תרחישים נפוצים לדוגמה
בקטעים הבאים מתוארים תרחישי שימוש נפוצים בבקשות רשת הצהרתיות. ההוראות שבהמשך הן רק תמצית. מידע נוסף על כל הפרטים שמופיעים כאן מפורט בהפניה ל-API בקטע chrome.declarativeNetRequest
חסימה של כתובת URL יחידה
תרחיש נפוץ לשימוש במניפסט V2 היה חסימה של בקשות אינטרנט באמצעות האירוע onBeforeRequest בסקריפט הרקע.
chrome.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
תרחיש נפוץ נוסף במניפסט 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" 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 צריך ליירט את כותרות בקשות האינטרנט לפני שהן נשלחות ולהסיר קובץ Cookie ספציפי.
chrome.webRequest.onBeforeSendHeaders.addListener( function(details) { removeHeader(details.requestHeaders, 'cookie'); return {requestHeaders: details.requestHeaders}; }, // filters {urls: ['https://*/*', 'http://*/*']}, // extraInfoSpec ['blocking', 'requestHeaders', 'extraHeaders']);
במניפסט מגרסה 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": [ "" ]