Esta página foi traduzida pela API Cloud Translation.

Tutorial: migrar para o Manifest V2

A versão 1 do manifest foi descontinuada no Chrome 18, e o suporte será desativado de acordo com a programação de suporte da versão 1 do manifest. As mudanças da versão 1 para a versão 2 se enquadram em duas categorias amplas: mudanças na API e mudanças na segurança.

Este documento oferece listas de verificação para migrar suas extensões do Chrome da versão 1 do manifesto para a versão 2, seguidas de resumos mais detalhados sobre o que essas mudanças significam e por que foram feitas.

Lista de verificação de mudanças na API

Você está usando a propriedade browser_actions ou a API chrome.browserActions?
Substitua browser_actions pela propriedade browser_action singular.
Substitua chrome.browserActions por chrome.browserAction.
Substitua a propriedade icons por default_icon.
Substitua a propriedade name por default_title.
Substitua a propriedade popup por default_popup (e agora ela precisa ser uma string).
Você está usando a propriedade page_actions ou a API chrome.pageActions?
Substitua page_actions por page_action.
Substitua chrome.pageActions por chrome.pageAction.
Substitua a propriedade icons por default_icon.
Substitua a propriedade name por default_title.
Substitua a propriedade popup por default_popup (e agora ela 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() ou chrome.extension.getExtensionTabs()?
Substitua por chrome.extension.getViews( { "type" : "tab" } ).
Sua extensão usa uma página de segundo plano?
Substitua a propriedade background_page por uma propriedade background.
Adicione uma propriedade scripts ou page que contenha o código da página.
Adicione uma propriedade persistent e defina-a como false para converter a página de plano de fundo em uma página de eventos.

Lista de verificação de mudanças de segurança

Você está usando blocos de script inline 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(), Function(), innerHTML, setTimeout() ou transmitindo strings de código JS que são avaliadas dinamicamente?
Use JSON.parse() se você estiver analisando o código JSON em um objeto.
Use uma biblioteca compatível com CSP, por exemplo, AngularJS.
Crie uma entrada de sandbox no manifesto e execute o código afetado no sandbox usando postMessage() para se comunicar com a página em sandbox.
Você está carregando um código externo, como o jQuery ou o Google Analytics?
Faça o download da biblioteca, empacote-a na sua extensão e carregue-a do pacote local.
Adicione à lista de permissões o domínio HTTPS que serve o recurso na parte "content_security_policy" do manifesto.

Resumo das mudanças na API

A versão 2 do manifesto introduz algumas mudanças nas APIs de ação da página e de ação do navegador e substitui algumas APIs antigas por versões mais recentes.

Mudanças nas ações do navegador

A API Browser Actions apresenta algumas mudanças de nomenclatura:

As propriedades browser_actions e chrome.browserActions foram substituídas pelas contrapartes singulares browser_action e chrome.browserAction.
Na antiga propriedade browser_actions, havia as propriedades icons, name e popup. Eles foram substituídos por:
default_icon para o ícone do 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 interface da ação do navegador. Agora, ela precisa ser uma string, não um objeto.

Mudanças nas ações da página

Assim como nas ações do navegador, a API Page Actions também mudou:

As propriedades page_actions e chrome.pageActions foram substituídas pelas correspondentes page_action e chrome.pageAction.
Na antiga propriedade page_actions, havia as propriedades icons, name e popup. Elas foram substituídas por:
default_icon para o ícone do 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, ela precisa ser uma string, não um objeto.

APIs removidas e modificadas

Algumas APIs de extensão foram removidas e substituídas por novas:

A propriedade background_page foi substituída por background.
A propriedade chrome.self foi removida. Use chrome.extension.
A propriedade Port.tab foi substituída por Port.sender.
As APIs chrome.extension.getTabContentses() e chrome.extension.getExtensionTabs() foram substituídas por chrome.extension.getViews( { "type" : "tab" } ).

Resumo das mudanças de 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 decorrentes 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 dela.

Scripts inline 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á suporte para processadores de eventos inline. Por exemplo, suponha que você tenha o seguinte código na sua extensão:

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

Esse código causaria um erro no momento da 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 uma ocorrência comum e um recurso de conveniência usado 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">

Elas 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 os manipuladores de eventos. Por exemplo, no código JS, use:

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

Essa é uma maneira muito mais limpa de separar o comportamento da extensão do markup da interface do usuário.

Incorporar conteúdo

Há alguns cenários em que a extensão pode incorporar conteúdo que pode ser usado externamente ou vir de uma fonte externa.

Conteúdo da extensão em páginas da Web:se a extensão incorporar recursos (como imagens, scripts, estilos CSS etc.) usados em scripts de conteúdo injetados em páginas da Web, use a propriedade web_accessible_resources para permitir que esses recursos sejam usados por páginas da Web externas:

{
...
  "web_accessible_resources": [
    "images/image1.png",
    "script/myscript.js"
  ],
...
}

Inserção de conteúdo externo:a política de segurança de conteúdo só permite que scripts e objetos locais sejam carregados do pacote, o que impede que invasores externos introduzam códigos desconhecidos na extensão. No entanto, há momentos em que você quer carregar recursos veiculados externamente, como o código do jQuery ou do Google Analytics. Há duas maneiras de fazer isso:

Faça o download da biblioteca relevante localmente (como o jQuery) e empacote-a com sua extensão.
É possível relaxar a CSP de forma limitada adicionando as origens HTTPS à lista de permissões na seção "content_security_policy" do manifesto. Para incluir uma biblioteca como o Google Analytics, siga esta abordagem:
```
{
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}
```

Como usar a avaliação dinâmica de script

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 vão fazer com que um eval() seja usado, como setTimeout(). Além disso, algumas bibliotecas JavaScript usadas com frequência, como o Google Maps e algumas bibliotecas de modelos, são conhecidas por usar 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 outros recursos semelhantes 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 no sandbox.
Use a transmissão de mensagens por postMessage() para se comunicar com a página em modo sandbox.

Para mais detalhes, consulte a documentação Sandboxing Eval.

Leitura adicional

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 de mudanças da versão 1 para a versão 2 do manifesto, consulte a documentação do arquivo de manifesto. Para mais informações sobre como usar o sandbox para isolar códigos não seguros, 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 uma boa introdução no HTML5Rocks.