La versione 1 del file manifest è stata deprecata in Chrome 18 e il supporto verrà gradualmente eliminato in base alla pianificazione dell'assistenza per la versione 1. Le modifiche dalla versione 1 alla versione 2 rientrano in due categorie generiche: modifiche all'API e modifiche alla sicurezza.
Questo documento fornisce elenchi di controllo per la migrazione delle estensioni di Chrome dalla versione 1 alla versione 2 del file manifest, seguiti da riepiloghi più dettagliati sul significato di queste modifiche e sul motivo per cui sono state apportate.
Elenco di controllo delle modifiche all'API
Stai utilizzando la proprietà
browser_actions
o l'APIchrome.browserActions
?Sostituisci
browser_actions
con la proprietàbrowser_action
singola.Sostituisci
chrome.browserActions
conchrome.browserAction
.Sostituisci la proprietà
icons
condefault_icon
.Sostituisci la proprietà
name
condefault_title
.Sostituisci la proprietà
popup
condefault_popup
(e ora deve essere una stringa).Stai utilizzando la proprietà
page_actions
o l'APIchrome.pageActions
?Sostituisci
page_actions
conpage_action
.Sostituisci
chrome.pageActions
conchrome.pageAction
.Sostituisci la proprietà
icons
condefault_icon
.Sostituisci la proprietà
name
condefault_title
.Sostituisci la proprietà
popup
condefault_popup
(e ora deve essere una stringa).Stai utilizzando la proprietà
chrome.self
?Sostituisci con
chrome.extension
.Stai utilizzando la proprietà
Port.tab
?Sostituisci con
Port.sender
.Utilizzi le API
chrome.extension.getTabContentses()
ochrome.extension.getExtensionTabs()
?Sostituisci con
chrome.extension.getViews( { "type" : "tab" } )
.L'estensione utilizza una pagina in background?
Sostituisci la proprietà
background_page
con una proprietàbackground
.Aggiungi una proprietà
scripts
opage
contenente il codice della pagina.Aggiungi una proprietà
persistent
e impostala sufalse
per convertire la tua pagina di sfondo in una pagina evento
Elenco di controllo delle modifiche di sicurezza
Utilizzi blocchi di script incorporati nelle pagine HTML?
Rimuovi il codice JS contenuto all'interno dei tag
<script>
e posizionalo in un file JS esterno.Utilizzi gestori di eventi incorporati (come onclick e così via)?
Rimuovili dal codice HTML, spostali in un file JS esterno e utilizza invece
addEventListener()
.L'estensione inserisce script di contenuti nelle pagine web che devono accedere alle risorse (come immagini e script) contenute nel pacchetto dell'estensione?
Definisci la proprietà web_accessible_resources ed elenca le risorse (e, facoltativamente, un criterio di sicurezza del contenuto separato per queste risorse).
L'estensione incorpora pagine web esterne?
Definisci la proprietà sandbox.
Il tuo codice o la tua libreria utilizza
eval()
, il nuovoFunction()
,innerHTML
,setTimeout()
o altrimenti passa stringhe di codice JS valutate dinamicamente?Utilizza
JSON.parse()
se analizziamo il codice JSON in un oggetto.Utilizza una libreria compatibile con CSP, ad esempio AngularJS.
Crea una voce sandbox nel manifest ed esegui il codice interessato nella sandbox, utilizzando
postMessage()
per comunicare con la pagina con sandbox.Stai caricando un codice esterno, ad esempio jQuery o Google Analytics?
Potresti scaricare la libreria e pacchettizzarla nell'estensione, quindi caricarla dal pacchetto locale.
Inserisci il dominio HTTPS che gestisce la risorsa nella lista consentita nella parte "content_security_policy" del file manifest.
Riepilogo delle modifiche all'API
La versione 2 del file manifest introduce alcune modifiche alle API di azione e di azione sulle pagine del browser e sostituisce alcune API precedenti con altre più recenti.
Modifiche alle azioni del browser
L'API delle azioni del browser introduce alcune modifiche ai nomi:
- Le proprietà
browser_actions
echrome.browserActions
sono state sostituite con le rispettive controparti singolaribrowser_action
echrome.browserAction
. Nella precedente proprietà
browser_actions
, erano presentiicons
,name
epopup
proprietà. Questi campi sono stati sostituiti con:default_icon
per l'icona del badge di azione del browserdefault_name
per il testo che compare nella descrizione comando quando passi il mouse sopra il badge.default_popup
per la pagina HTML che rappresenta l'interfaccia utente per l'azione del browser (che ora deve essere una stringa, non può essere un oggetto)
Modifiche alle azioni nelle pagine
Analogamente alle modifiche relative alle azioni del browser, anche l'API Page actions è cambiata:
- Le proprietà
page_actions
echrome.pageActions
sono state sostituite dalle rispettive controparti singolaripage_action
echrome.pageAction
. Nella precedente proprietà
page_actions
, erano presentiicons
,name
epopup
proprietà. Questi campi sono stati sostituiti con:default_icon
per l'icona del badge di azione sulla paginadefault_name
per il testo che compare nella descrizione comando quando passi il mouse sopra il badge.default_popup
per la pagina HTML che rappresenta l'interfaccia utente per l'azione pagina (che ora deve essere una stringa, non può essere un oggetto)
API rimosse e modificate
Alcune API di estensione sono state rimosse e sostituite con nuove controparti:
- La proprietà
background_page
è stata sostituita da background. - La proprietà
chrome.self
è stata rimossa. Utilizzachrome.extension
. - La proprietà
Port.tab
è stata sostituita conPort.sender
. - Le API
chrome.extension.getTabContentses()
echrome.extension.getExtensionTabs()
sono state sostituite dachrome.extension.getViews( { "type" : "tab" } )
.
Riepilogo delle modifiche alla sicurezza
Sono state apportate diverse modifiche relative alla sicurezza al passaggio dalla versione 1 del file manifest alla versione 2. Molte di queste modifiche derivano dall'adozione da parte di Chrome dei Criteri di sicurezza del contenuto; ti consigliamo di consultare ulteriori informazioni su questo criterio per comprenderne le implicazioni.
Script in linea e gestori di eventi non consentiti
Per via dell'uso dei criteri di sicurezza del contenuto, non è più possibile utilizzare i tag <script>
incorporati nei contenuti HTML. Questi file devono essere spostati in file JS esterni. Inoltre, non sono supportati nemmeno i gestori
di eventi incorporati. Ad esempio, supponiamo che l'estensione contenga il seguente codice:
<html>
<head>
<script>
function myFunc() { ... }
</script>
</head>
</html>
Questo codice causerebbe un errore in fase di runtime. Per risolvere il problema, sposta i contenuti del tag <script>
in file esterni e fai riferimento a questi contenuti con un attributo src='path_to_file.js'
.
Analogamente, non vengono eseguiti i gestori di eventi incorporati, che sono una funzionalità comune a scopo di occorrenza e convenienza usata da molti sviluppatori web. Ad esempio, considera istanze comuni come:
<body onload="initialize()">
<button onclick="handleClick()" id="button1">
Non funzionano nelle estensioni Manifest V2. Rimuovi i gestori di eventi incorporati, posizionali nel tuo
file JS esterno e utilizza addEventListener()
per registrare i gestori di eventi. Ad esempio, nel codice JS utilizza:
window.addEventListener("load", initialize);
...
document.getElementById("button1").addEventListener("click",handleClick);
Si tratta di un modo molto più chiaro per separare il comportamento dell'estensione dal markup dell'interfaccia utente.
Incorporamento dei contenuti
Ci sono alcuni scenari in cui l'estensione potrebbe incorporare contenuti che possono essere utilizzati esternamente o provenienti da una fonte esterna.
Contenuti delle estensioni nelle pagine web: se l'estensione incorpora risorse (ad esempio immagini, script, stili CSS e così via) utilizzate in script di contenuti inseriti in pagine web, devi utilizzare la proprietà web_accessible_resources per inserire queste risorse nella lista consentita in modo che le pagine web esterne possano utilizzarle:
{
...
"web_accessible_resources": [
"images/image1.png",
"script/myscript.js"
],
...
}
Incorporamento di contenuti esterni: i criteri di sicurezza del contenuto consentono di caricare dal tuo pacchetto solo script e oggetti locali; ciò impedisce a utenti malintenzionati esterni di introdurre codice sconosciuto nella tua estensione. Tuttavia, in alcuni casi vuoi caricare risorse pubblicate esternamente, ad esempio jQuery o codice di Google Analytics. Esistono due metodi per effettuare questa operazione:
- Scaricare la libreria pertinente in locale (come jQuery) e pacchettizzarla con la tua estensione.
Puoi allentare il CSP in modo limitato inserendo le origini HTTPS nella sezione "content_security_policy" del tuo manifest. Per includere una libreria come Google Analytics, puoi adottare questo approccio:
{ ..., "content_security_policy": "script-src 'self' https://ssl.google-analytics.com; object-src 'self'", ... }
Utilizzo della valutazione dinamica degli script
Forse una delle principali modifiche nel nuovo schema manifest v2 è che le estensioni non possono più usare tecniche di valutazione degli script dinamici come eval()
o il nuovo Function()
, né passare stringhe di codice JS a funzioni che faranno usare un eval()
, come setTimeout()
. Inoltre, è noto che alcune librerie JavaScript comunemente utilizzate, come Google Maps e alcune librerie di modelli, utilizzano alcune di queste tecniche.
Chrome fornisce una sandbox per le pagine da eseguire nella propria origine, a cui viene negato l'accesso a Chrome.*
API Per utilizzare eval()
e simili ai sensi dei nuovi criteri di sicurezza del contenuto:
- Crea una voce sandbox nel file manifest.
- Nella voce della sandbox, elenca le pagine che vuoi eseguire.
- Utilizza la trasmissione dei messaggi tramite
postMessage()
per comunicare con la pagina con sandbox.
Per ulteriori dettagli su come eseguire questa operazione, consulta la documentazione relativa a Sandboxing Eval.
Per approfondire
Le modifiche alla versione 2 del file manifest sono progettate per guidare gli sviluppatori verso la creazione di app e estensioni più sicure e con un'architettura più solida. Per visualizzare un elenco completo delle modifiche dalla versione 1 del file manifest alla versione 2, consulta la documentazione relativa al file manifest. Per ulteriori informazioni sull'utilizzo della limitazione tramite sandbox per isolare il codice non sicuro, leggi l'articolo sulla valutazione del sandboxing. Puoi ottenere ulteriori informazioni sui criteri di sicurezza dei contenuti visitando il nostro tutorial relativo alle estensioni e un'ottima introduzione a HTML5Rocks.