Учебное пособие: переход на манифест версии 2

Манифест версии 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 и перечислите ресурсы (и, при необходимости, отдельную политику безопасности контента для этих ресурсов).

  • Встраивает ли ваше расширение внешние веб-страницы?

  • Определите свойство песочницы .

  • Использует ли ваш код или библиотека eval() , new 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">

Они не будут работать в расширениях манифеста 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'",
  ...
}

Использование динамической оценки сценария

Возможно, одно из самых больших изменений в новой схеме манифеста v2 заключается в том, что расширения больше не могут использовать методы динамической оценки сценариев, такие как eval() или new Function() , или передавать строки кода JS функциям, которые вызывают вызов eval() используется, например, setTimeout() . Кроме того, известно, что некоторые широко используемые библиотеки JavaScript, такие как Google Maps и некоторые библиотеки шаблонов, используют некоторые из этих методов.

Chrome предоставляет изолированную программную среду для запуска страниц в их собственном источнике, которым запрещен доступ к API chrome.*. Чтобы использовать eval() и тому подобное в соответствии с новой Политикой безопасности контента:

  1. Создайте запись песочницы в файле манифеста.
  2. В записи песочницы перечислите страницы, которые вы хотите запустить в песочнице.
  3. Используйте передачу сообщений через postMessage() для связи со страницей в песочнице.

Дополнительные сведения о том, как это сделать, см. в документации по тестированию песочницы .

Дальнейшее чтение

Изменения в манифесте версии 2 призваны помочь разработчикам создавать более безопасные и надежные расширения и приложения. Полный список изменений манифеста версии 1 и версии 2 см. в документации к файлу манифеста . Дополнительные сведения об использовании песочницы для изоляции небезопасного кода см. в статье об оценке песочницы . Вы можете узнать больше о Политике безопасности контента, посетив наше руководство по расширениям и хорошее введение в HTML5Rocks .