Formato do arquivo de manifesto

Cada extensão precisa ter um arquivo manifest.json no diretório raiz que liste informações importantes sobre a estrutura e o comportamento dela. Nesta página, explicamos a estrutura dos manifestos de extensão e os recursos que eles podem incluir.

Exemplos

Os exemplos de manifesto a seguir mostram a estrutura básica e alguns recursos usados com frequência como ponto de partida para criar seu próprio manifesto:

{
  "manifest_version": 3,
  "name": "Minimal Manifest",
  "version": "1.0.0",
  "description": "A basic example extension with only required keys",
  "icons": {
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  }
}

{
  "manifest_version": 3,
  "name": "Run script automatically",
  "description": "Runs a script on www.example.com automatically when user installs the extension",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "content_scripts": [
    {
      "js": [
        "content-script.js"
      ],
      "matches": [
        "http://*.example.com//"
      ]
    }
  ]
}

{
  "manifest_version": 3,
  "name": "Click to run",
  "description": "Runs a script when the user clicks the action toolbar icon.",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "background": {
    "service_worker": "service-worker.js"
  },
  "action": {
    "default_icon": {
      "16": "images/icon-16.png",
      "32": "images/icon-32.png",
      "48": "images/icon-48.png",
      "128": "images/icon-128.png"
    }
  },
  "permissions": ["scripting", "activeTab"]
}

{
  "manifest_version": 3,
  "name": "Popup extension that requests permissions",
  "description": "Extension that includes a popup and requests host permissions and storage permissions.",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "action": {
    "default_popup": "popup.html"
  },
  "host_permissions": [
    "https://*.example.com/"
  ],
  "permissions": [
    "storage"
  ]
}

{
  "manifest_version": 3,
  "name": "Side panel extension",
  "version": "1.0",
  "description": "Extension with a default side panel.",
  "icons": {
    "16": "images/icon-16.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "side_panel": {
    "default_path": "sidepanel.html"
  },
  "permissions": ["sidePanel"]
}

Chaves de manifesto

Confira abaixo uma lista de todas as chaves de manifesto compatíveis.

Chaves necessárias para a plataforma Extensions

"manifest_version"

Um número inteiro que especifica a versão do formato do arquivo de manifesto usado pela extensão. O único valor compatível é 3.

"name"

Uma string que identifica a extensão na Chrome Web Store, na caixa de diálogo de instalação e na página "Extensões do Chrome" do usuário (chrome://extensions). O comprimento máximo é de 75 caracteres. Para informações sobre como usar nomes específicos da localidade, consulte Internacionalização.

"version"

Uma string que identifica o número da versão da extensão. Para informações sobre formatação de número de versão, consulte Versão.

Chaves necessárias para a Chrome Web Store

"description"

Uma string que descreve a extensão na Chrome Web Store e na página de gerenciamento de extensões do usuário. O tamanho máximo é de 132 caracteres. Para informações sobre como localizar descrições, consulte Internacionalização.

"icons"

Um ou mais ícones que representam sua extensão. Para informações sobre as práticas recomendadas, consulte Icons.

Chaves opcionais

"action"

Define a aparência e o comportamento do ícone da extensão na barra de ferramentas do Google. Para ver mais informações, consulte chrome.action.

"background"

Especifica o arquivo JavaScript que contém o service worker da extensão, que atua como um manipulador de eventos. Para mais informações, consulte Sobre service workers de extensões.

"chrome_settings_overrides"

Define substituições para as configurações selecionadas do Chrome. Para mais informações, consulte Substituir as configurações do Chrome.

"chrome_url_overrides"

Define substituições para páginas padrão do Chrome. Para mais informações, consulte Substituir páginas do Chrome.

"commands"

Define atalhos de teclado na extensão. Para mais informações, consulte chrome.commands.

"content_scripts"

Especifica arquivos JavaScript ou CSS a serem usados quando o usuário abre determinadas páginas da Web. Para mais informações, consulte Scripts de conteúdo.

"content_security_policy"

Define restrições nos scripts, estilos e outros recursos que uma extensão pode usar. Para mais informações, consulte Política de segurança de conteúdo.

"cross_origin_embedder_policy"

Especifica um valor para o cabeçalho HTTP Cross-Origin-Embedder-Policy, que configura a incorporação de recursos entre origens em uma página de extensão.

"cross_origin_opener_policy"

Especifica um valor para o cabeçalho HTTP Cross-Origin-Opener-Policy, que permite garantir que uma página de extensão de nível superior não compartilhe um grupo de contexto de navegação com documentos de origem cruzada.

"declarative_net_request"

Define regras estáticas para a API declarativeNetRequest que permite bloquear e modificar solicitações de rede.

"default_locale"

Uma string que define o idioma padrão de uma extensão compatível com várias localidades. Por exemplo, "en" e "pt_BR". Essa chave é obrigatória em extensões localizadas e não pode ser usada em extensões que não são localizadas. Para mais informações, consulte Internacionalização.

"devtools_page"

Define páginas que usam as APIs DevTools.

"export"

Permite que os recursos sejam exportados da extensão. Para mais informações, consulte Exportar.

"externally_connectable"

Especifica a quais outras páginas e extensões suas extensões podem se conectar. Para mais informações, consulte "externally_connectable".

"homepage_url"

Uma string que especifica um URL para a página inicial da extensão. Se não estiver definido, a página inicial será a página da extensão na Chrome Web Store. Esse campo é especialmente útil se você hospedar a extensão no seu próprio site.

"host_permissions"

Lista as páginas da Web com que sua extensão pode interagir, definidas usando padrões de correspondência de URL. A permissão do usuário para esses sites é solicitada no momento da instalação. Para mais informações, consulte Permissões de host.

"import"

Permite que os recursos sejam importados para a extensão. Para mais informações, consulte Importar.

"incognito"

Define como a extensão se comporta no modo de navegação anônima. Os valores aceitos são "spanning", "split" e "not_allowed". Para mais informações, consulte Navegação anônima.

"key"

Especifica o ID da extensão para vários casos de uso de desenvolvimento. Para mais informações, consulte Chave.

"minimum_chrome_version"

Define a versão mais antiga do Chrome que pode instalar sua extensão. O valor precisa ser uma substring de uma string de versão do navegador Chrome, como "107" ou "107.0.5304.87". Os usuários com versões do Chrome mais antigas que a mínima recebem um aviso de "Não compatível" na Chrome Web Store e não conseguem instalar sua extensão. Se você adicionar isso a uma extensão atual, os usuários com uma versão mais antiga do Chrome não vão receber atualizações automáticas da extensão. Isso inclui usuários comerciais no modo temporário.

"oauth2"

Permite o uso de um ID de segurança do OAuth 2.0. O valor dessa chave precisa ser um objeto com propriedades "client_id" e "scopes". Para mais detalhes, consulte o tutorial do OAuth 2.0.

"omnibox"

Permite que a extensão registre uma palavra-chave na barra de endereço do Chrome. Para mais informações, consulte Omnibox.

"optional_host_permissions"

Declara permissões de host opcionais para sua extensão.

"optional_permissions"

Declara permissões opcionais para sua extensão.

"options_page"

Especifica um caminho para um arquivo options.html que a extensão vai usar como uma página de opções. Para mais informações, consulte Oferecer opções aos usuários.

"options_ui"

Especifica um caminho para um arquivo HTML que permite que um usuário mude as opções de extensão na página "Extensões do Chrome". Para mais informações, consulte Opções incorporadas.

"permissions"

Permite o uso de APIs de extensão específicas. Consulte Permissões para uma explicação geral. As páginas de referência para APIs individuais listam as permissões necessárias.

"requirements"

Lista as tecnologias necessárias para usar a extensão. Para uma lista de requisitos compatíveis, consulte Requisitos.

"sandbox"

Define um conjunto de páginas de extensão que não têm acesso às APIs de extensão ou acesso direto a páginas não isoladas em sandbox. Para mais informações, consulte Sandbox.

"short_name"

Uma string que contém uma versão abreviada do nome da extensão a ser usada quando o espaço de caracteres é limitado. O tamanho máximo é de 12 caracteres. Se for indefinido, uma versão truncada da chave "name" será exibida.

"side_panel"

Identifica um arquivo HTML para mostrar em um sidePanel.

"storage"

Declara um esquema JSON para a área de armazenamento gerenciado. Para mais informações, consulte Manifesto para áreas de armazenamento.

"tts_engine"

Registra a extensão como um mecanismo de conversão de texto em voz. Para mais informações, consulte a API ttsEngine.

"update_url"

Uma string que contém o URL da página de atualizações da extensão. Use essa chave se você estiver hospedando sua extensão fora da Chrome Web Store.

"version_name"

Uma string que descreve a versão da extensão. Por exemplo, "1.0 beta" e "build rc2". Se não for especificado, o valor "version" vai aparecer na página de gerenciamento de extensões.

"web_accessible_resources"

Define os arquivos na extensão que podem ser acessados por páginas da Web ou outras extensões. Para mais informações, consulte Recursos acessíveis pela Web.

Teclas opcionais do ChromeOS

"file_browser_handlers"

Fornece acesso à API fileBrowserHandler que permite que as extensões acessem o navegador de arquivos do ChromeOS.

"file_handlers"

Especifica os tipos de arquivos que as extensões do ChromeOS podem processar. Para mais informações, confira file_handlers.

"file_system_provider_capabilities"

Permite o acesso à API fileSystemProvider que permite que as extensões criem sistemas de arquivos que o ChromeOS pode usar.

"input_components"

Permite o uso da API Editor de método de entrada. Para mais informações, consulte input_components.