Migrar para o Manifesto V3

Um guia para converter extensões Manifest V2 em extensões Manifest V3.

Esta seção ajuda você a fazer upgrade de uma extensão do Manifest V2 para o Manifest V3, a versão mais recente da plataforma de extensões do Chrome. O trabalho de migração é amplamente dividido nas categorias abaixo. Para ajudar você a acompanhar seu trabalho, fornecemos uma lista de verificação que resume o conteúdo desses documentos. Acesse o conteúdo pela lista de verificação ou se aprofunde mais. Ambos os caminhos terminam com uma extensão atualizada.

  • Atualize o manifesto: o manifest.json precisa ser específico para a V3. As mudanças que podem ser feitas por conta própria são descritas nesta seção. As mudanças de manifesto relacionadas ao código são descritas com as mudanças de código que elas oferecem suporte.
  • Migrar para um service worker: um service worker substitui a página de evento ou o plano de fundo da extensão para garantir que o código em segundo plano permaneça fora da linha de execução principal, o que pode prejudicar o desempenho. Essa mudança também exige mover o DOM, a janela e determinadas chamadas de API de extensão para documentos fora da tela.
  • Atualizar chamadas de API: algumas chamadas de API precisam ser substituídas por outras mais modernas.
  • Substituir o bloqueio de listeners de solicitações da Web: bloquear ou modificar solicitações de rede no Manifest V2 pode prejudicar significativamente a performance e exigir acesso excessivo a dados sensíveis do usuário. A API Declarative Net Request permite que as extensões bloqueiem ou modifiquem o conteúdo da Web com menos permissões e sem prejudicar o desempenho.
  • Melhorar a segurança das extensões: o Manifest V3 melhora a segurança das extensões de várias maneiras. Além de uma política aprimorada de segurança de conteúdo, o suporte para código hospedado remotamente e execução de strings arbitrárias é removido.
  • Publicar sua extensão: esta seção descreve como realizar um lançamento gradual para garantir que sua extensão do Manifesto V3 funcione conforme o esperado testando-a primeiro com um público limitado.

Também temos um Conversor de manifesto de extensão. Ele não faz tudo, mas ajuda você a começar. O README do conversor descreve o que a ferramenta muda.

Manter o conjunto atual de recursos

Para reduzir as chances de problemas ou bugs inesperados, não adicione novas funcionalidades durante a migração. Por exemplo, adicionar um recurso que exige novas permissões pode acionar um aviso de permissão, o que desativará sua extensão até que o usuário aceite as novas permissões. Consulte Práticas recomendadas de avisos de permissão para conhecer outras maneiras de adicionar permissões sem exibir um aviso.

O Manifest V3 geralmente é compatível com o Chrome 88 ou versões mais recentes. Ao atualizar chamadas de API, é possível que os recursos de substituição não tenham sido instalados no Chrome até a versão 88. As páginas de referência da API contêm informações de suporte de membros individuais da API. Se você descobrir que precisa de um desses recursos, especifique uma versão mínima do Chrome no arquivo de manifesto.

Novos recursos da plataforma de extensões

Desde o lançamento do Manifest V3, continuamos a adicionar novos recursos, muitos dos quais podem ser usados tanto no Manifesto V2 quanto no Manifesto V3. Não é obrigatório usá-los na conversão. No entanto, quando eles substituem recursos mais antigos, você precisa dar preferência aos recursos que eles substituem e esperar que os recursos substituídos eventualmente sejam descontinuados e removidos.