A versão 1 do manifesto foi descontinuada no Chrome 18, e o suporte será descontinuado de acordo com a programação de suporte da versão 1 do manifesto. As mudanças da versão 1 para a 2 se enquadram em duas categorias gerais: mudanças de API e de segurança.
Este documento apresenta listas de verificação para migrar as extensões do Chrome da versão 1 para a versão 2 do manifesto, seguidas de resumos mais detalhados do que essas mudanças significam e por que elas foram feitas.
Lista de verificação de mudanças na API
Você está usando a propriedade
browser_actions
ou a APIchrome.browserActions
?Substitua
browser_actions
pela propriedadebrowser_action
.Substitua
chrome.browserActions
porchrome.browserAction
.Substitua a propriedade
icons
pordefault_icon
.Substitua a propriedade
name
pordefault_title
.Substitua a propriedade
popup
pordefault_popup
, que agora precisa ser uma string.Você está usando a propriedade
page_actions
ou a APIchrome.pageActions
?Substitua
page_actions
porpage_action
.Substitua
chrome.pageActions
porchrome.pageAction
.Substitua a propriedade
icons
pordefault_icon
.Substitua a propriedade
name
pordefault_title
.Substitua a propriedade
popup
pordefault_popup
, que agora precisa ser uma string.Você está usando a propriedade
chrome.self
?Substitua por
chrome.extension
.Você está usando a propriedade
Port.tab
?Substitua por
Port.sender
.Você está usando as APIs
chrome.extension.getTabContentses()
ouchrome.extension.getExtensionTabs()
?Substitua por
chrome.extension.getViews( { "type" : "tab" } )
.Sua extensão usa uma página em segundo plano?
Substitua a propriedade
background_page
por uma propriedadebackground
.Adicione uma propriedade
scripts
oupage
que contenha o código da página.Adicione uma propriedade
persistent
e defina-a comofalse
para converter sua página de plano de fundo em uma página de eventos.
Lista de verificação das mudanças de segurança
Você está usando blocos de script in-line em páginas HTML?
Remova o código JS contido nas tags
<script>
e coloque-o em um arquivo JS externo.Você está usando manipuladores de eventos inline (como onClick etc)?
Remova-os do código HTML, mova-os para um arquivo JS externo e use
addEventListener()
.Sua extensão injeta scripts de conteúdo em páginas da Web que precisam acessar recursos (como imagens e scripts) contidos no pacote da extensão?
Defina a propriedade web_accessible_resources e liste os recursos (e, opcionalmente, uma Política de Segurança de Conteúdo separada para esses recursos).
Sua extensão incorpora páginas da Web externas?
Defina a propriedade sandbox.
Seu código ou biblioteca está usando
eval()
, novoFunction()
,innerHTML
,setTimeout()
ou transmitindo strings de código JS que são avaliadas dinamicamente?Use
JSON.parse()
ao analisar o código JSON em um objeto.Use uma biblioteca compatível com CSP, por exemplo, AngularJS.
Crie uma entrada do sandbox no manifesto e execute o código afetado no sandbox usando
postMessage()
para se comunicar com a página no modo sandbox.Você está carregando código externo, como jQuery ou Google Analytics?
Considere fazer o download da biblioteca e empacotá-la na extensão e, em seguida, carregá-la do pacote local.
Autorize o domínio HTTPS que exibe o recurso na parte "content_security_policy" do seu manifesto.
Resumo das mudanças na API
A versão 2 do manifesto introduz algumas mudanças nas APIs de ações do navegador e de página e substitui algumas APIs antigas por outras mais recentes.
Mudanças nas ações do navegador
A API de ações do navegador traz algumas mudanças na nomenclatura:
- As propriedades
browser_actions
echrome.browserActions
foram substituídas pelas equivalentesbrowser_action
echrome.browserAction
. Na antiga propriedade
browser_actions
, haviaicons
,name
epopup
. Eles foram substituídos por:default_icon
do ícone de selo de ação do navegador.default_name
para o texto que aparece na dica quando você passa o cursor sobre o selo.default_popup
para a página HTML que representa a IU para a ação do navegador (agora precisa ser uma string, e não um objeto).
Mudanças nas ações da página
Assim como nas ações do navegador, a API de ações da página também mudou:
- As propriedades
page_actions
echrome.pageActions
foram substituídas pelas contrapartes únicaspage_action
echrome.pageAction
. Na antiga propriedade
page_actions
, haviaicons
,name
epopup
. Eles foram substituídos por:default_icon
para o ícone de selo de ação da página.default_name
para o texto que aparece na dica quando você passa o cursor sobre o selo.default_popup
para a página HTML que representa a interface da ação da página (agora precisa ser uma string, e não um objeto).
APIs removidas e alteradas
Algumas APIs de extensão foram removidas e substituídas por novas contrapartes:
- A propriedade
background_page
foi substituída por background. - A propriedade
chrome.self
foi removida. Usechrome.extension
. - A propriedade
Port.tab
foi substituída porPort.sender
- As APIs
chrome.extension.getTabContentses()
echrome.extension.getExtensionTabs()
foram substituídas porchrome.extension.getViews( { "type" : "tab" } )
Resumo das mudanças na segurança
Há várias mudanças relacionadas à segurança que acompanham a mudança da versão 1 do manifesto para a versão 2. Muitas dessas mudanças são resultado da adoção da Política de Segurança de Conteúdo pelo Chrome. Leia mais sobre essa política para entender as implicações.
Scripts in-line e manipuladores de eventos não permitidos
Devido ao uso da Política de Segurança de Conteúdo, não é mais possível usar tags <script>
inline
com o conteúdo HTML. Eles precisam ser movidos para arquivos JS externos. Além disso, não há compatibilidade com manipuladores de eventos inline. Por exemplo, suponha que você tenha o seguinte código em sua extensão:
<html>
<head>
<script>
function myFunc() { ... }
</script>
</head>
</html>
Esse código causaria um erro durante a execução. Para corrigir isso, mova o conteúdo da tag <script>
para arquivos externos
e faça referência a eles com um atributo src='path_to_file.js'
.
Da mesma forma, os manipuladores de eventos inline, que são um recurso comum de ocorrência e conveniência usados por muitos desenvolvedores da Web, não serão executados. Por exemplo, considere instâncias comuns, como:
<body onload="initialize()">
<button onclick="handleClick()" id="button1">
Eles não vão funcionar nas extensões do Manifest V2. Remova os manipuladores de eventos inline, coloque-os no
arquivo JS externo e use addEventListener()
para registrar manipuladores de eventos para eles. Por exemplo, no seu código JS, use:
window.addEventListener("load", initialize);
...
document.getElementById("button1").addEventListener("click",handleClick);
Essa é uma maneira muito mais simples de separar o comportamento da extensão da marcação da interface do usuário.
Incorporação de conteúdo
Existem alguns cenários em que sua extensão pode incorporar conteúdo que pode ser usado externamente ou vir de uma fonte externa.
Conteúdo de extensão em páginas da Web: se a extensão incorporar recursos (como imagens, script, estilos CSS etc.) que são usados em scripts de conteúdo injetados em páginas da Web, você precisará usar a propriedade web_accessible_resources para autorizar esses recursos a fim de que as páginas da Web externas possam usá-los:
{
...
"web_accessible_resources": [
"images/image1.png",
"script/myscript.js"
],
...
}
Incorporar conteúdo externo: a Política de Segurança de Conteúdo permite apenas o carregamento de scripts e objetos locais do pacote, o que impede que invasores externos introduzam código desconhecido na extensão. No entanto, há momentos em que você quer carregar recursos veiculados externamente, como jQuery ou código do Google Analytics. Há duas maneiras de fazer isso:
- Faça o download da biblioteca relevante localmente (como jQuery) e empacote-a com sua extensão.
Você pode relaxar a CSP de maneira limitada, colocando origens HTTPS na lista de permissões na seção "content_security_policy" do manifesto. Para incluir uma biblioteca como o Google Analytics, esta é a abordagem a ser adotada:
{ ..., "content_security_policy": "script-src 'self' https://ssl.google-analytics.com; object-src 'self'", ... }
Como usar a avaliação de script dinâmico
Talvez uma das maiores mudanças no novo esquema do manifesto v2 seja que as extensões não podem mais usar técnicas de avaliação de script dinâmico, como eval()
ou o novo Function()
, ou transmitir strings de código JS para funções que farão com que um eval()
seja usado, como setTimeout()
. Além disso, algumas bibliotecas JavaScript comumente usadas, como o Google Maps e algumas bibliotecas de modelos, usam algumas dessas técnicas.
O Chrome oferece um sandbox para que as páginas sejam executadas na própria origem, que não têm acesso ao Chrome.*
APIs Para usar eval()
e conteúdo semelhante na nova Política de Segurança de Conteúdo:
- Crie uma entrada de sandbox no arquivo de manifesto.
- Na entrada do sandbox, liste as páginas que você quer executar nele.
- Usar a transmissão de mensagens via
postMessage()
para se comunicar com a página no modo sandbox.
Para mais detalhes sobre como fazer isso, consulte a documentação Avaliação de sandbox.
Leia mais
As mudanças na versão 2 do manifesto foram projetadas para orientar os desenvolvedores a criar extensões e apps mais seguros e com arquitetura robusta. Para conferir uma lista completa das mudanças da versão 1 para a versão 2, consulte a documentação do arquivo de manifesto. Para mais informações sobre como usar o sandbox para isolar o código não seguro, leia o artigo Avaliação de sandbox. Para saber mais sobre a Política de Segurança de Conteúdo, acesse nosso tutorial relacionado a extensões e confira uma boa introdução ao HTML5Rocks.