Tutorial: migrazione a Manifest V2

La versione 1 del manifest è stata ritirata in Chrome 18 e il supporto verrà gradualmente eliminato in base al programma di supporto della versione 1 del 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 Chrome dalla versione 1 del manifest alla versione 2, seguiti da riepiloghi più dettagliati di cosa significano queste modifiche e perché sono state apportate.

Elenco di controllo delle modifiche alle API

  • Stai utilizzando la proprietà browser_actions o l'API chrome.browserActions?

  • Sostituisci browser_actions con la proprietà singolare 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.

  • Stai utilizzando 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 che contenga 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 incorporati nelle pagine HTML?

  • Rimuovi il codice JS contenuto nei tag <script> e inseriscilo 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 addEventListener() invece.

  • La tua estensione inserisce script di contenuti nelle pagine web che devono accedere a risorse (come immagini e script) contenute nel pacchetto dell'estensione?

  • Definisci la proprietà web_accessible_resources ed elenca le risorse (e, facoltativamente, una Content Security Policy separata per queste risorse).

  • La tua estensione incorpora pagine web esterne?

  • Definisci la proprietà sandbox.

  • Il tuo codice o la tua libreria utilizza eval(), Function(), innerHTML, setTimeout() o passa in altro modo stringhe di codice JS che vengono valutate dinamicamente?

  • Utilizza JSON.parse() se analizzi il codice JSON in un oggetto.

  • Utilizza una libreria compatibile con CSP, ad esempio AngularJS.

  • Crea una voce sandbox nel manifest e esegui il codice interessato nella sandbox utilizzando postMessage() per comunicare con la pagina in sandbox.

  • Stai caricando codice esterno, ad esempio jQuery o Google Analytics?

  • Valuta la possibilità di scaricare la libreria e inserirla nel pacchetto dell'estensione, quindi caricarla dal pacchetto locale.

  • Aggiungi alla lista consentita il dominio HTTPS che gestisce la risorsa nella sezione "content_security_policy" del manifest.

Riepilogo delle modifiche alle API

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

Modifiche alle azioni del browser

L'API Azioni browser 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. Questi 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 la UI per l'azione del browser (e ora deve essere una stringa, non può essere un oggetto)

Modifiche alle azioni della pagina

Analogamente alle modifiche per le azioni del browser, è cambiata anche l'API Page Actions:

  • Le proprietà page_actions e chrome.pageActions sono state sostituite dalle rispettive 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 la UI per l'azione di pagina (e 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

Il passaggio dalla versione 1 alla versione 2 del manifest comporta una serie di modifiche relative alla sicurezza. Molte di queste modifiche derivano dall'adozione da parte di Chrome della Content Security Policy; ti consigliamo di leggere di più su queste norme per comprenderne le implicazioni.

Script e gestori di eventi incorporati non consentiti

A causa dell'utilizzo dei Content Security Policy, non puoi più utilizzare i tag <script> incorporati nei contenuti HTML. Questi devono essere spostati in file JS esterni. Inoltre, non sono supportati i gestori di eventi incorporati. Ad esempio, supponiamo che tu abbia il seguente codice nella tua estensione:

<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 file con un attributo src='path_to_file.js'.

Allo stesso modo, i gestori di eventi incorporati, che sono una funzionalità comune e pratica utilizzata da molti sviluppatori web, non verranno eseguiti. Ad esempio, prendi in considerazione istanze comuni come:

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

Questi non funzioneranno nelle estensioni Manifest V2. Rimuovi i gestori di eventi incorporati, 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);

Questo è un modo molto più pulito per separare il comportamento dell'estensione dal markup dell'interfaccia utente.

Incorporare contenuti

Esistono alcuni scenari in cui la tua estensione potrebbe incorporare contenuti che possono essere utilizzati esternamente o provenire da una fonte esterna.

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

Incorporamento di contenuti esterni:la Content Security Policy consente di caricare solo script e oggetti locali dal pacchetto, il che impedisce agli aggressori esterni di introdurre codice sconosciuto nell'estensione. Tuttavia, a volte vuoi caricare risorse pubblicate esternamente, come il codice jQuery o Google Analytics. Puoi utilizzare due metodi:

  1. Scarica la libreria pertinente localmente (ad esempio jQuery) e pacchettizzala con l'estensione.

  2. Puoi allentare CSP in modo limitato inserendo 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 uno dei cambiamenti più importanti nel nuovo schema Manifest v2 è che le estensioni non possono più utilizzare tecniche di valutazione dinamica degli script come eval() o Function() o passare stringhe di codice JS a funzioni che causeranno l'utilizzo di 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 le pagine da eseguire nella propria origine, a cui viene negato l'accesso a chrome.* API Per utilizzare eval() e simili ai sensi della nuova Content Security Policy:

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

Per maggiori dettagli su come farlo, consulta la documentazione relativa al sandboxing di Eval.

Per approfondire

Le modifiche alla versione 2 del manifest sono progettate per guidare gli sviluppatori verso la creazione di estensioni e app più sicure e con un'architettura solida. Per visualizzare un elenco completo delle modifiche dalla versione 1 del manifest alla versione 2, consulta la documentazione del file manifest. Per saperne di più sull'utilizzo del sandboxing per isolare il codice non sicuro, leggi l'articolo Valutazione del sandboxing. Per saperne di più sulla Content Security Policy, consulta il nostro tutorial relativo alle estensioni e una buona introduzione su HTML5Rocks.