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

גרסת המניפסט 1 הוצאה משימוש ב-Chrome 18, והתמיכה בה תופסק בהדרגה בהתאם ללוח הזמנים של התמיכה בגרסת המניפסט 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.

  • האם אתם משתמשים בממשקי ה-API של chrome.extension.getTabContentses() או של chrome.extension.getExtensionTabs()?

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

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

  • מחליפים את הנכס background_page בנכס background.

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

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

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

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

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

  • האם משתמשים בקוד של גורמים שמטפלים באירועים (כמו onclick וכו')?

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

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

  • מגדירים את המאפיין web_accessible_resources ומפרטים את המשאבים (ואם רוצים, גם מדיניות אבטחת תוכן נפרדת למשאבים האלה).

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

  • מגדירים את המאפיין sandbox.

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

  • משתמשים ב-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 של פעולות הדף השתנה:

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

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

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

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

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

ממשקי 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. מומלץ לקרוא מידע נוסף על המדיניות הזו כדי להבין את ההשלכות שלה.

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

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

<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() כדי לתקשר עם הדף ב-sandbox.

מידע נוסף על כך זמין במסמכי התיעוד של Sandboxing Eval.

קריאה נוספת

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