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 APIchrome.browserActions
?Zastąp
browser_actions
pojedynczą właściwościąbrowser_action
.Zamień
chrome.browserActions
nachrome.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 APIchrome.pageActions
?Zamień
page_actions
napage_action
.Zamień
chrome.pageActions
nachrome.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()
czychrome.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
lubpage
zawierającą kod strony.Dodaj właściwość
persistent
i ustaw jej wartość nafalse
, 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()
, nowyFunction()
,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
ichrome.browserActions
zostały zastąpione liczbami pojedynczymibrowser_action
ichrome.browserAction
. W poprzedniej usłudze
browser_actions
znajdują się usługiicons
,name
ipopup
. Zostały one zastąpione przez:default_icon
w przypadku ikony plakietki działania w przeglądarcedefault_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
ichrome.pageActions
zostały zastąpione liczbami pojedynczymipage_action
ichrome.pageAction
. W poprzedniej usłudze
page_actions
znajdują się usługiicons
,name
ipopup
. Zostały one zastąpione przez:Oznaczenie
default_icon
ikony plakietki działania na stroniedefault_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 przezPort.sender
. - Interfejsy API
chrome.extension.getTabContentses()
ichrome.extension.getExtensionTabs()
zostały zastąpione przezchrome.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:
- Pobierz odpowiednią bibliotekę lokalnie (np. jQuery) i spakuj ją z rozszerzeniem.
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:
- Utwórz wpis piaskownicy w pliku manifestu.
- We wpisie piaskownicy podaj strony, które mają być w niej uruchamiane.
- 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.