Samouczek: przenoszenie do platformy Manifest V2

Wersja 1 pliku manifestu została wycofana w Chrome 18. Jej obsługa będzie stopniowo wycofywana zgodnie z harmonogramem obsługi w wersji 1 pliku manifestu. Zmiany między wersją 1 a 2 należą do 2 ogólnych kategorii: zmian w interfejsach API i zmian w zabezpieczeniach.

Ten dokument zawiera listy kontrolne umożliwiające przeniesienie rozszerzeń do Chrome z wersji 1 manifestu do wersji 2 oraz bardziej szczegółowe podsumowania znaczenia tych zmian i przyczyn ich wprowadzenia.

Lista kontrolna zmian interfejsu API

  • Czy używasz właściwości browser_actions czy interfejsu API chrome.browserActions?

  • Zastąp browser_actions pojedynczą właściwością browser_action.

  • Zamień chrome.browserActions na chrome.browserAction.

  • Zastąp właściwość icons wartością default_icon.

  • Zastąp właściwość name wartością default_title.

  • Zastąp właściwość popup wartością default_popup (która teraz musi być ciągiem znaków).

  • Czy używasz właściwości page_actions czy interfejsu API chrome.pageActions?

  • Zamień page_actions na page_action.

  • Zamień chrome.pageActions na chrome.pageAction.

  • Zastąp właściwość icons wartością default_icon.

  • Zastąp właściwość name wartością default_title.

  • Zastąp właściwość popup wartością default_popup (która teraz musi być ciągiem znaków).

  • Czy używasz właściwości chrome.self?

  • Zamień na chrome.extension.

  • Czy używasz właściwości Port.tab?

  • Zamień na Port.sender.

  • Czy używasz interfejsów API chrome.extension.getTabContentses() czy chrome.extension.getExtensionTabs()?

  • Zamień na chrome.extension.getViews( { "type" : "tab" } ).

  • Czy Twoje rozszerzenie korzysta ze strony w tle?

  • Zastąp właściwość background_page właściwością background.

  • Dodaj właściwość scripts lub page zawierającą kod strony.

  • Dodaj właściwość persistent i ustaw jej wartość na false, aby przekonwertować stronę w tle na stronę wydarzenia.

Lista kontrolna zmian zabezpieczeń

  • Czy używasz bloków wbudowanych skryptów na stronach HTML?

  • Usuń kod JS zawarty w tagach <script> i umieść go w zewnętrznym pliku JS.

  • Czy używasz wbudowanych modułów obsługi zdarzeń (np. onclick itp.)?

  • Usuń je z kodu HTML, przenieś do zewnętrznego pliku JS i użyj elementu addEventListener().

  • Czy rozszerzenie wstawia skrypty zawartości na stronach internetowych, które wymagają dostępu do zasobów (takich jak obrazy i skrypty), które znajdują się w pakiecie rozszerzenia?

  • Zdefiniuj właściwość web_accessible_resources i wyświetl listę zasobów (możesz też utworzyć dla nich oddzielną zasadę Content Security Policy).

  • Czy Twoje rozszerzenie zawiera zewnętrzne strony internetowe?

  • Zdefiniuj właściwość sandbox.

  • Czy w Twoim kodzie lub bibliotece jest używany eval(), nowy Function(), innerHTML, setTimeout() lub inne przekazywane ciągi kodu JS, które są oceniane dynamicznie?

  • Użyj JSON.parse(), jeśli analizujesz kod JSON na obiekt.

  • Używaj biblioteki przyjaznej dla CSP, np. AngularJS.

  • Utwórz w pliku manifestu wpis piaskownicy i uruchom w niej kod, którego dotyczy problem, używając polecenia postMessage() do komunikowania się ze stroną piaskownicy.

  • Czy wczytujesz kod zewnętrzny, taki jak jQuery lub Google Analytics?

  • Rozważ pobranie biblioteki i spakowanie jej w rozszerzeniu, a następnie wczytanie z pakietu lokalnego.

  • Umieść na liście dozwolonych domenę HTTPS, która udostępnia zasób w części „content_security_policy” pliku manifestu.

Podsumowanie zmian w interfejsie API

Wersja 2 pliku manifestu wprowadza kilka zmian w interfejsach API działań przeglądarki i działań na stronie oraz zastępuje kilka starych interfejsów API nowszymi.

Zmiany w działaniach przeglądarki

W interfejsie API działań w przeglądarce wprowadziliśmy kilka zmian w nazwach:

  • Właściwości browser_actions i chrome.browserActions zostały zastąpione liczbami pojedynczymi browser_action i chrome.browserAction.

  • W poprzedniej usłudze browser_actions znajdują się usługi icons, name i popup. Zostały one zastąpione przez:

  • default_icon w przypadku ikony plakietki działania w przeglądarce

  • default_name: tekst, który pojawia się w etykietce, gdy najedziesz kursorem na plakietkę

  • default_popup dla strony HTML, która reprezentuje interfejs użytkownika działania przeglądarki (musi to być ciąg znaków, a nie obiekt)

Zmiany w działaniach na stronie

Podobnie jak w przypadku działań w przeglądarce, zmienił się też interfejs API działań na stronie:

  • Właściwości page_actions i chrome.pageActions zostały zastąpione liczbami pojedynczymi page_action i chrome.pageAction.

  • W poprzedniej usłudze page_actions znajdują się usługi icons, name i popup. Zostały one zastąpione przez:

  • Oznaczenie default_icon ikony plakietki działania na stronie

  • default_name: tekst, który pojawia się w etykietce, gdy najedziesz kursorem na plakietkę

  • default_popup dla strony HTML, która reprezentuje interfejs użytkownika działania na stronie (teraz musi to być ciąg znaków, a nie obiekt)

Usunięte i zmienione interfejsy API

Kilka interfejsów API rozszerzeń zostało usuniętych i zastąpione nowymi odpowiednikami:

  • Właściwość background_page została zastąpiona przez właściwość background.
  • Właściwość chrome.self została usunięta. Użyj tego pola: chrome.extension.
  • Właściwość Port.tab została zastąpiona przez Port.sender.
  • Interfejsy API chrome.extension.getTabContentses() i chrome.extension.getExtensionTabs() zostały zastąpione przez chrome.extension.getViews( { "type" : "tab" } ).

Podsumowanie zmian w zabezpieczeniach

Przejście z pliku manifestu w wersji 1 na wersję 2 wiąże się z kilkoma zmianami związanymi z bezpieczeństwem. Wiele z tych zmian wynika z przyjęcia przez Chrome polityki bezpieczeństwa treści. Aby dowiedzieć się więcej o jej konsekwencjach, przeczytaj więcej o tej zasadzie.

Skrypty wbudowane i moduły obsługi zdarzeń są niedozwolone

Ze względu na stosowanie Content Security Policy nie możesz już używać tagów <script>, które są wbudowane w treści HTML. Należy je przenieść do zewnętrznych plików JS. Wbudowane moduły obsługi zdarzeń również nie są obsługiwane. Załóżmy na przykład, że rozszerzenie zawiera taki kod:

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

Ten kod spowodowałby błąd w trakcie działania. Aby rozwiązać ten problem, przenieś zawartość tagu <script> do plików zewnętrznych i odwołaj się do nich za pomocą atrybutu src='path_to_file.js'.

Z kolei wbudowane moduły obsługi zdarzeń, które są częstym zjawiskiem i funkcją wygodną, nie będą uruchamiane. Rozważmy na przykład typowe przypadki, takie jak:

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

Nie będą one działać z rozszerzeniami platformy Manifest V2. Usuń wbudowane moduły obsługi zdarzeń, umieść je w zewnętrznym pliku JS i użyj polecenia addEventListener(), aby je zarejestrować. Na przykład w kodzie JS użyj:

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

Dzięki temu łatwiej oddzielić działanie rozszerzenia od znaczników interfejsu.

Umieszczanie treści

W niektórych przypadkach rozszerzenie może umieszczać treści, które mogą być używane zewnętrznie lub pochodzić z zewnętrznych źródeł.

Zawartość rozszerzeń na stronach internetowych: jeśli rozszerzenie umieszcza w rozszerzeniu zasoby (takie jak obrazy, skrypty czy style CSS itp.) używane w skryptach wstrzykiwanych na strony internetowe, musisz użyć właściwości web_accessible_resources i umożliwić korzystanie z nich zewnętrznych stron internetowych:

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

Umieszczanie treści zewnętrznych: zasady bezpieczeństwa treści dopuszczają ładowanie z pakietu tylko skryptów lokalnych i obiektów. Blokuje to osobom przeprowadzającym atak z zewnątrz możliwość wprowadzenia nieznanego kodu do rozszerzenia. Może się jednak zdarzyć, że chcesz wczytać zasoby udostępniane zewnętrznie, takie jak kod jQuery czy Google Analytics. Można to zrobić na dwa sposoby:

  1. Pobierz odpowiednią bibliotekę lokalnie (np. jQuery) i spakuj ją z rozszerzeniem.

  2. Możesz ograniczyć zakres CSP, dodając źródła HTTPS do listy dozwolonych w sekcji „content_security_policy” pliku manifestu. Aby uwzględnić bibliotekę, np. Google Analytics, wykonaj następujące czynności:

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

Korzystanie z dynamicznej oceny skryptów

Prawdopodobnie jedną z najważniejszych zmian w nowym schemacie pliku manifestu w wersji 2 jest to, że rozszerzenia nie mogą już korzystać z technik dynamicznej oceny skryptów, takich jak eval() czy nowy Function(), ani przekazywać ciągów kodu JavaScript do funkcji, które będą powodować użycie eval(), np. setTimeout(). Ponadto niektóre z powszechnie używanych bibliotek JavaScript, takie jak Mapy Google i niektóre biblioteki szablonów, korzystają z niektórych z tych technik.

Chrome udostępnia piaskownicę, w której strony uruchamiają się w ich własnym źródle i nie mają dostępu do Chrome*. Interfejsy API. Aby korzystać z eval() itp. w ramach nowej polityki bezpieczeństwa treści:

  1. Utwórz wpis piaskownicy w pliku manifestu.
  2. We wpisie piaskownicy podaj strony, które mają być w niej uruchamiane.
  3. Używaj komunikatów przekazywanych przez postMessage() do komunikowania się ze stroną w trybie piaskownicy.

Więcej informacji na ten temat znajdziesz w dokumentacji Sandboxing Eval.

Więcej informacji

Zmiany w pliku manifestu w wersji 2 mają pomóc programistom w tworzeniu bezpieczniejszych i skuteczniejszych rozszerzeń i aplikacji. Pełną listę zmian z wersji 1 na 2 znajdziesz w dokumentacji pliku manifestu. Więcej informacji na temat korzystania z piaskownicy do izolowania niebezpiecznego kodu znajdziesz w artykule o ocenie piaskownicy. Więcej informacji o Polityce bezpieczeństwa treści znajdziesz w naszym samouczku dotyczącym rozszerzeń i dobrym wprowadzeniu do HTML5Rocks.