מדריך: העברה למניפסט מגרסה 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 חיצוני.

  • האם אתם משתמשים במטפלי אירועים מוטבעים (למשל, clickclick וכו')?

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

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

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

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

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

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

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

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

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

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

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

  • יש להוסיף לרשימת ההיתרים את דומיין ה-HTTPS שמשמש את המשאב בקטע "content_security_policy" במניפסט.

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

גרסה 2 של המניפסט כוללת כמה שינויים בממשקי ה-API של פעולת הדפדפן ופעולת הדפים, ומחליפה כמה ממשקי 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 הוחלף ברקע.
  • המאפיין 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 חיצוניים. בנוסף, אין תמיכה בגורמים מטפלים באירועים מוטבעים. לדוגמה, נניח שהתוסף שלך כלל את הקוד הבא:

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

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

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

<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"
  ],
...
}

הטמעת תוכן חיצוני: ה-Content Security Policy מאפשר רק לטעון אובייקטים וסקריפטים מקומיים מהחבילה, וכך מונעים מתוקפים חיצוניים להכניס קוד לא מוכר לתוסף. עם זאת, לפעמים רוצים לטעון משאבים שמוצגים מחוץ לארגון, כמו 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'",
  ...
}

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

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

Chrome מספק ארגז חול לדפים שאפשר להריץ במקור משלהם, והגישה ל-Chrome חסומה.* ממשקי API. כדי להשתמש ב-eval() ובמאפיינים דומים במסגרת ה-Content Security Policy החדש:

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

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

קריאה נוספת

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