Questa pagina è stata tradotta dall'API Cloud Translation.

Tutorial: migrazione a Manifest V2

La versione 1 di Manifest è stata ritirata in Chrome 18 e il supporto verrà eliminato gradualmente in base al programma di ritiro del supporto della versione 1 di Manifest. Le modifiche dalla versione 1 alla versione 2 rientrano in due categorie generali: modifiche all'API e modifiche alla sicurezza.

Questo documento fornisce elenchi di controllo per la migrazione delle estensioni di Chrome dalla versione 1 del manifest alla versione 2, 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'API chrome.browserActions?
Sostituisci browser_actions con la proprietà singola browser_action.
Sostituisci chrome.browserActions con chrome.browserAction.
Sostituisci la proprietà icons con default_icon.
Sostituisci la proprietà name con default_title.
Sostituisci la proprietà popup con default_popup (che ora deve essere una stringa).
Stai utilizzando la proprietà page_actions o l'API chrome.pageActions?
Sostituisci page_actions con page_action.
Sostituisci chrome.pageActions con chrome.pageAction.
Sostituisci la proprietà icons con default_icon.
Sostituisci la proprietà name con default_title.
Sostituisci la proprietà popup con default_popup (che ora deve essere una stringa).
Utilizzi la proprietà chrome.self?
Sostituisci con chrome.extension.
Utilizzi la proprietà Port.tab?
Sostituisci con Port.sender.
Utilizzi le API chrome.extension.getTabContentses() o chrome.extension.getExtensionTabs()?
Sostituisci con chrome.extension.getViews( { "type" : "tab" } ).
La tua estensione utilizza una pagina di sfondo?
Sostituisci la proprietà background_page con una proprietà background.
Aggiungi una proprietà scripts o page contenente il codice della pagina.
Aggiungi una proprietà persistent e impostala su false per convertire la pagina di sfondo in una pagina evento

Elenco di controllo delle modifiche alla sicurezza

Utilizzi blocchi di script in linea nelle pagine HTML?
Rimuovi il codice JS contenuto nei tag <script> e inseriscilo in un file JS esterno.
Utilizzi gestori di eventi in linea (come onclick e così via)?
Rimuovili dal codice HTML, spostali in un file JS esterno e utilizza addEventListener() in alternativa.
La tua estensione inietta 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 Content Security separato per queste risorse).
La tua estensione incorpora pagine web esterne?
Definisci la proprietà sandbox.
Il tuo codice o la tua libreria utilizzano eval(), new Function(), innerHTML, setTimeout() o in altro modo passano stringhe di codice JS che vengono valutate dinamicamente?
Utilizza JSON.parse() se stai analizzando il codice JSON in un oggetto.
Utilizza una libreria compatibile con CSP, ad esempio AngularJS.
Crea una voce della sandbox nel manifest ed esegui il codice interessato nella sandbox, utilizzando postMessage() per comunicare con la pagina in sandbox.
Carichi codice esterno, ad esempio jQuery o Google Analytics?
Valuta la possibilità di scaricare la libreria e impacchettarla nell'estensione, quindi caricarla dal pacchetto locale.
Aggiungi alla lista consentita il dominio HTTPS che serve la risorsa nella parte "content_security_policy" del manifest.

Riepilogo delle modifiche all'API

La versione 2 del manifest introduce alcune modifiche alle API di azioni del browser e di azioni della pagina e sostituisce alcune API precedenti con quelle più recenti.

Modifiche alle azioni del browser

L'API Browser Actions introduce alcune modifiche ai nomi:

Le proprietà browser_actions e chrome.browserActions sono state sostituite con le loro controparti singolari browser_action e chrome.browserAction.
Nella vecchia proprietà browser_actions erano presenti le proprietà icons, name e popup. che sono stati sostituiti da:
default_icon per l'icona del badge dell'azione del browser
default_name per il testo visualizzato 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 (ora deve essere una stringa, non un oggetto)

Modifiche alle azioni della pagina

Analogamente alle modifiche apportate alle azioni del browser, è cambiata anche l'API di azioni di pagina:

Le proprietà page_actions e chrome.pageActions sono state sostituite con le loro controparti singolari page_action e chrome.pageAction.
Nella vecchia proprietà page_actions erano presenti le proprietà icons, name e popup. Questi sono stati sostituiti da:
default_icon per l'icona del badge dell'azione della pagina
default_name per il testo visualizzato nella descrizione comando quando passi il mouse sopra il badge
default_popup per la pagina HTML che rappresenta l'interfaccia utente per l'azione della pagina (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, utilizza chrome.extension.
La proprietà Port.tab è stata sostituita con Port.sender.
Le API chrome.extension.getTabContentses() e chrome.extension.getExtensionTabs() sono state sostituite da chrome.extension.getViews( { "type" : "tab" } ).

Riepilogo delle modifiche alla sicurezza

Esistono diverse modifiche relative alla sicurezza che accompagnano il passaggio dalla versione 1 del file manifest alla versione 2. Molte di queste modifiche derivano dall'adozione da parte di Chrome delle norme Content Security. Ti consigliamo di leggere di più su queste norme per comprenderne le implicazioni.

Script in linea e gestori di eventi non consentiti

A causa dell'utilizzo dei criteri di sicurezza del contenuto, non puoi più utilizzare i tag <script> in linea con i contenuti HTML. Questi devono essere spostati in file JS esterni. Inoltre, non sono supportati nemmeno i gestori di eventi in linea. Ad esempio, supponiamo che la tua estensione contenga il seguente codice:

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

Questo codice causerebbe un errore in fase di esecuzione. Per risolvere il problema, sposta i contenuti del tag <script> in file esterni e fai riferimento a questi file con un attributo src='path_to_file.js'.

Analogamente, non verranno eseguiti i gestori di eventi in linea, che sono un'occurrence comune e una funzionalità di praticità utilizzata da molti sviluppatori web. Ad esempio, prendi in considerazione istanze comuni come:

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

Questi valori non funzioneranno nelle estensioni manifest V2. Rimuovi i gestori di eventi in linea, inseriscili nel file JS esterno e utilizza addEventListener() per registrarli. Ad esempio, nel codice JS, utilizza:

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

Si tratta di un modo molto più pulito per separare il comportamento dell'estensione dal markup dell'interfaccia utente.

Incorporare contenuti

In alcuni casi, l'estensione potrebbe incorporare contenuti che possono essere utilizzati esternamente o provenire da una fonte esterna.

Contenuti dell'estensione nelle pagine web: se l'estensione incorpora risorse (come immagini, script, stili CSS e così via) utilizzate negli script dei contenuti iniettati nelle 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"
  ],
...
}

Incorporazione di contenuti esterni:i criteri di sicurezza dei contenuti consentono di caricare solo script e oggetti locali dal pacchetto, il che impedisce ad aggressori esterni di introdurre codice sconosciuto nell'estensione. Tuttavia, a volte potresti voler caricare risorse pubblicate esternamente, come il codice jQuery o Google Analytics. Puoi utilizzare due metodi:

Scarica localmente la libreria pertinente (ad esempio jQuery) e impacchettala con l'estensione.
Puoi allentare il CSP in modo limitato inserendo nella lista consentita le origini HTTPS nella sezione "content_security_policy" del manifest. Per includere una libreria come Google Analytics, segui 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 modifiche più importanti nel nuovo schema manifest v2 è che le estensioni non possono più utilizzare tecniche di valutazione dinamica dello script come eval() o il nuovo Function() oppure passare stringhe di codice JS a funzioni che causeranno l'utilizzo di un eval(), come setTimeout(). Inoltre, è noto che alcune librerie JavaScript di uso comune, come Google Maps e alcune librerie di modelli, utilizzano alcune di queste tecniche.

Chrome fornisce una sandbox per l'esecuzione delle pagine nella loro origine, a cui viene negato l'accesso a Chrome.* API Per utilizzare eval() e simili ai sensi delle nuove norme sulla sicurezza dei contenuti:

Crea una voce della sandbox nel file manifest.
Nella voce della sandbox, elenca le pagine che vuoi eseguire nella sandbox.
Utilizza la trasmissione di messaggi tramite postMessage() per comunicare con la pagina in sandbox.

Per ulteriori dettagli su come eseguire questa operazione, consulta la documentazione di Sandboxing Eval.

Per approfondire

Le modifiche alla versione 2 del file manifest sono progettate per aiutare gli sviluppatori a creare app ed estensioni più sicure e con un'architettura solida. Per visualizzare un elenco completo delle modifiche dalla versione 1 del file manifest alla versione 2, consulta la documentazione del file manifest. Per ulteriori informazioni sull'utilizzo della sandbox per isolare il codice non sicuro, leggi l'articolo sandboxing eval. Per scoprire di più sulle Norme sulla sicurezza dei contenuti, consulta il nostro tutorial sulle estensioni e una buona introduzione su HTML5Rocks.