מדריך: העברה למניפסט מגרסה V2

הוצאנו משימוש את Manifest version 1 ב-Chrome 18, והתמיכה בו תופסק בהדרגה בהתאם ללוח הזמנים של התמיכה ב-Manifest version 1. השינויים מגרסה 1 לגרסה 2 נחלקים לשתי קטגוריות רחבות: שינויים ב-API ושינויים באבטחה.

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

רשימת משימות לבדיקת שינויים ב-API

• האם אתם משתמשים בנכס browser_actions או ב-API של chrome.browserActions?

• מחליפים את browser_actions בנכס browser_action ביחיד.

• מחליפים את chrome.browserActions ב-chrome.browserAction.

• מחליפים את המאפיין icons במאפיין default_icon.

• מחליפים את המאפיין name במאפיין default_title.

• מחליפים את המאפיין popup במאפיין default_popup (ועכשיו הוא חייב להיות מחרוזת).

• האם אתם משתמשים בנכס page_actions או ב-API של chrome.pageActions?

• מחליפים את page_actions ב-page_action.

• מחליפים את chrome.pageActions ב-chrome.pageAction.

• מחליפים את המאפיין icons במאפיין default_icon.

• מחליפים את המאפיין name במאפיין default_title.

• מחליפים את המאפיין popup במאפיין default_popup (ועכשיו הוא חייב להיות מחרוזת).

• האם השתמשת במאפיין chrome.self?

• החלפה ב-chrome.extension.

• האם השתמשת במאפיין Port.tab?

• החלפה ב-Port.sender.

• האם נעשה שימוש ב-chrome.extension.getTabContentses() API או ב-chrome.extension.getExtensionTabs() API?

• החלפה ב-chrome.extension.getViews( { "type" : "tab" } ).

• האם התוסף משתמש בדף רקע?

• החלפת הנכס background_page בנכס background.

• מוסיפים מאפיין scripts או page שמכיל את הקוד של הדף.

• מוסיפים מאפיין persistent ומגדירים אותו לערך false כדי להמיר את דף הרקע לדף אירוע

רשימת משימות לשינויים באבטחה

• האם אתם משתמשים בבלוקים של סקריפטים מוטבעים בדפי HTML?

• מסירים קוד JS שנמצא בתוך תגי <script> ומציבים אותו בקובץ JS חיצוני.

• האם אתם משתמשים ב-event handlers מוטבעים (כמו onclick וכו')?

• מסירים אותם מקוד ה-HTML, מעבירים אותם לקובץ JS חיצוני ומשתמשים ב-addEventListener() במקום זאת.

• האם התוסף שלכם מזריק סקריפטים של תוכן לדפי אינטרנט שצריכים לגשת למשאבים (כמו תמונות וסקריפטים) שנכללים בחבילת התוסף?

• מגדירים את המאפיין web_accessible_resources ומפרטים את המשאבים (ואפשר גם להגדיר Content Security Policy נפרדת למשאבים האלה).

• האם התוסף מטמיע דפי אינטרנט חיצוניים?

• מגדירים את מאפיין ארגז החול.

• האם הקוד או הספרייה שלך משתמשים ב-eval(), ב-Function(), ב-innerHTML, ב-setTimeout() או בשיטה אחרת להעברת מחרוזות של קוד JavaScript שמוערכות באופן דינמי?

• משתמשים ב-JSON.parse() אם מנתחים קוד JSON לאובייקט.

• משתמשים בספרייה שמתאימה ל-CSP, למשל AngularJS.

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

• האם אתם טוענים קוד חיצוני, כמו jQuery או Google Analytics?

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

• מוסיפים לרשימת ההיתרים את דומיין ה-HTTPS שמציג את המשאב בחלק content_security_policy של קובץ המניפסט.

סיכום השינויים ב-API

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

שינויים בפעולות בדפדפן

ב-API של פעולות בדפדפן יש כמה שינויים בשמות:

• המאפיינים browser_actions ו-chrome.browserActions הוחלפו במקבילים שלהם בצורת היחיד, browser_action ו-chrome.browserAction.

• בנכס הישן browser_actions היו נכסים מסוג icons, name ו-popup. הם הוחלפו ב:

• ‫default_icon לסמל התג של פעולת הדפדפן

• default_name לטקסט שמופיע בתיבת ההסבר כשמעבירים את העכבר מעל התג

• ‫default_popup לדף ה-HTML שמייצג את ממשק המשתמש של פעולת הדפדפן (ועכשיו זה חייב להיות מחרוזת, ולא יכול להיות אובייקט)

שינויים בפעולות בדף

בדומה לשינויים שבוצעו ב-API של פעולות הדפדפן, גם ה-API של פעולות הדף השתנה:

• המאפיינים page_actions ו-chrome.pageActions הוחלפו במקבילים שלהם בצורת היחיד page_action ו-chrome.pageAction.

• בנכס הישן page_actions היו נכסים מסוג icons, name ו-popup. הם הוחלפו ב:

• ‫default_icon לסמל התג של פעולת הדף

• default_name לטקסט שמופיע בתיבת ההסבר כשמעבירים את העכבר מעל התג

• ‫default_popup עבור דף ה-HTML שמייצג את ממשק המשתמש של פעולת הדף (הערך הזה חייב להיות מחרוזת, ולא יכול להיות אובייקט)

ממשקי API שהוסרו או השתנו

כמה ממשקי API של תוספים הוסרו והוחלפו בממשקי API חדשים:

• המאפיין background_page הוחלף במאפיין background.
• המאפיין chrome.self הוסר, צריך להשתמש במאפיין chrome.extension.
• המאפיין Port.tab הוחלף במאפיין Port.sender.
• ממשקי ה-API‏ chrome.extension.getTabContentses() ו-chrome.extension.getExtensionTabs() הוחלפו ב-chrome.extension.getViews( { "type" : "tab" } ).

סיכום השינויים באבטחה

יש מספר שינויים שקשורים לאבטחה שמגיעים עם המעבר מגרסה 1 של מניפסט לגרסה 2. רבים מהשינויים האלה נובעים מההטמעה של מדיניות אבטחת התוכן ב-Chrome. מומלץ לקרוא מידע נוסף על המדיניות הזו כדי להבין את ההשלכות שלה.

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

בגלל השימוש בContent Security Policy, אי אפשר יותר להשתמש בתגי <script> שמוטמעים בתוכן ה-HTML. צריך להעביר אותם לקובצי JS חיצוניים. בנוסף, אין תמיכה ב-inline event handlers. לדוגמה, נניח שהקוד הבא מופיע בתוסף:

<html>
<head>
  <script>
    function myFunc() { ... }
  </script>
</head>
</html>

הקוד הזה יגרום לשגיאה בזמן הריצה. כדי לפתור את הבעיה, מעבירים את התוכן של תג <script> לקבצים חיצוניים ומפנים אליהם באמצעות מאפיין src='path_to_file.js'.

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

<body onload="initialize()">
<button onclick="handleClick()" id="button1">

הם לא יפעלו בתוספי Manifest V2. מסירים את הגורמים המטפלים באירועים בשורה, מציבים אותם בקובץ ה-JS החיצוני ומשתמשים ב-addEventListener() כדי לרשום במקומם גורמים מטפלים באירועים. לדוגמה, בקוד ה-JS, משתמשים ב:

window.addEventListener("load", initialize);
...
document.getElementById("button1").addEventListener("click",handleClick);

זו דרך נקייה יותר להפריד בין אופן הפעולה של התוסף לבין סימון ממשק המשתמש שלו.

הטמעת תוכן

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

תוכן של תוספים בדפי אינטרנט: אם התוסף מטמיע משאבים (כמו תמונות, סקריפטים, סגנונות CSS וכו') שמשמשים בסקריפטים של תוכן שמוזרקים לדפי אינטרנט, צריך להשתמש במאפיין web_accessible_resources כדי להוסיף את המשאבים האלה לרשימת ההיתרים, כך שדפי אינטרנט חיצוניים יוכלו להשתמש בהם:

{
...
  "web_accessible_resources": [
    "images/image1.png",
    "script/myscript.js"
  ],
...
}

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

1. מורידים את הספרייה הרלוונטית באופן מקומי (למשל jQuery) ואורזים אותה עם התוסף.

2. אפשר להגמיש את ה-CSP באופן מוגבל על ידי הוספת מקורות HTTPS לרשימת ההיתרים בקטע content_security_policy במניפסט. כדי לכלול ספריה כמו Google Analytics, צריך לפעול לפי השלבים הבאים:

   {
     ...,
     "content_security_policy": "script-src 'self'
     https://ssl.google-analytics.com; object-src 'self'",
     ...
   }
   

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

אחד השינויים המשמעותיים ביותר בסכמת Manifest v2 החדשה הוא שתוספים כבר לא יכולים להשתמש בטכניקות דינמיות להערכת סקריפטים כמו eval() או Function() חדש, או להעביר מחרוזות של קוד JS לפונקציות שיגרמו לשימוש ב-eval(), כמו setTimeout(). בנוסף, ידוע שספריות JavaScript מסוימות שנמצאות בשימוש נפוץ, כמו מפות Google וספריות מסוימות של תבניות, משתמשות בחלק מהטכניקות האלה.

‫Chrome מספק ארגז חול לדפים כדי להפעיל אותם במקור שלהם, ומונע מהם גישה ל-chrome.* ממשקי API. כדי להשתמש ב-eval() וכדומה במסגרת מדיניות אבטחת התוכן החדשה:

1. יוצרים רשומה של ארגז חול בקובץ המניפסט.
2. בכניסה לארגז החול, מפרטים את הדפים שרוצים להפעיל בארגז החול.
3. משתמשים בהעברת הודעות דרך postMessage() כדי לתקשר עם הדף בארגז החול.

מידע נוסף על אופן הביצוע מופיע במאמר בנושא Sandboxing Eval.

קריאה נוספת

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