O Linux é a única plataforma em que os usuários do Chrome podem instalar extensões hospedadas fora da
Chrome Web Store. Neste artigo, descrevemos como empacotar, hospedar e atualizar arquivos crx
de um servidor da Web de uso geral. Se você estiver distribuindo uma extensão ou um tema exclusivamente
pela Chrome Web Store, consulte Hospedagem e
atualização da Webstore.
Pacote
Extensões e temas são veiculados como arquivos .crx
. No upload pelo Painel de desenvolvedor do
Chrome, o painel cria o arquivo crx
automaticamente. Se publicado
em um servidor pessoal, o arquivo crx
precisará ser criado localmente ou transferido por download na Chrome
Web Store.
Fazer o download de um arquivo .crx da Chrome Web Store
Se uma extensão estiver hospedada na Chrome Web Store, o arquivo .crx
poderá ser transferido por download no
Painel do desenvolvedor. Localize a extensão em "Suas listagens" e clique em "Mais informações". Na
janela pop-up, clique no link azul main.crx
para fazer o download.
O arquivo transferido por download pode ser hospedado em um servidor pessoal. Essa é a maneira mais segura de hospedar uma extensão localmente, já que o conteúdo dela será assinado pela Chrome Web Store. Isso ajuda a detectar possíveis ataques e adulterações.
Criar um arquivo .crx localmente
Os diretórios de extensões são convertidos em arquivos .crx
na página de gerenciamento de extensões. Navegue até chrome://extensions/
na omnibox ou clique no menu do Google Chrome, mantenha o ponteiro sobre "Mais ferramentas" e selecione "Extensões".
Na página de gerenciamento de extensões, ative o modo de desenvolvedor clicando na chave ao lado de Modo de desenvolvedor. Em seguida, selecione o botão PACOTE DE EXTENSÃO.
Especifique o caminho para a pasta da extensão no campo do diretório raiz da extensão e clique no botão EXTENSÃO DE PACOTE. Ignore o campo Chave privada para novos pacotes.
O Chrome criará dois arquivos, um .crx
e um .pem
, que contêm a chave privada
da extensão.
Não perca a chave privada. Mantenha o arquivo .pem
em um local secreto e seguro. Ele será necessário para atualizar a extensão.
Atualizar um pacote .crx
Atualize o arquivo .crx
de uma extensão aumentando o número da versão em manifest.json
.
{
...
"version": "1.5",
...
}
}
{
...
"version": "1.6",
...
}
}
Volte para a Página de gerenciamento de extensões e clique no botão PAC EXTENSÃO. Especifique o caminho para o diretório de extensões e o local da chave privada.
A página fornecerá o caminho para a extensão empacotada atualizada.
Empacotar pela linha de comando
Extensões de pacote na linha de comando invocando chrome.exe
. Use a sinalização --pack-extension
para especificar o local da pasta da extensão e a sinalização --pack-extension-key
para especificar o local do arquivo de chave privada da extensão.
chrome.exe --pack-extension=C:\myext --pack-extension-key=C:\myext.pem
Host
Um servidor que hospeda arquivos .crx
precisa usar cabeçalhos HTTP apropriados para permitir que os usuários instalem a extensão clicando em um link.
O Google Chrome considera um arquivo instalável se uma das seguintes condições for verdadeira:
- O arquivo tem o tipo de conteúdo
application/x-chrome-extension
- O sufixo do arquivo é
.crx
, e os dois casos a seguir são verdadeiros:- O arquivo não é veiculado com o cabeçalho HTTP
X-Content-Type-Options: nosniff
. - O arquivo é exibido com um dos seguintes tipos de conteúdo:
- String vazia
"text/plain"
"application/octet-stream"
"unknown/unknown"
"application/unknown"
"\*/\*"
- O arquivo não é veiculado com o cabeçalho HTTP
O motivo mais comum para não reconhecer um arquivo instalável é que o servidor envia o
cabeçalho X-Content-Type-Options: nosniff
. O segundo motivo mais comum é que o servidor envia um
tipo de conteúdo desconhecido, que não está na lista anterior. Para corrigir um problema de cabeçalho HTTP, altere
a configuração do servidor ou tente hospedar o arquivo .crx
em outro servidor.
Atualizar
Em intervalos de algumas horas, o navegador verifica se há um URL de atualização nas extensões instaladas. Para cada um, ele faz uma solicitação ao URL procurando um arquivo XML de manifesto de atualização.
- O conteúdo retornado por uma verificação de atualização é um documento XML de manifesto de atualização que lista a versão mais recente de uma extensão.
Se o manifesto de atualização mencionar uma versão mais recente do que a instalada, o navegador
vai fazer o download e instalar a nova versão. Assim como acontece com as atualizações manuais, o novo arquivo .crx
precisa ser assinado
com a mesma chave privada da versão instalada atualmente.
Atualizar URL
As extensões hospedadas em servidores fora da Chrome Webstore precisam incluir o campo update_url
no
arquivo manifest.json
.
{
"name": "My extension",
...
"update_url": "https://myhost.com/mytestextension/updates.xml",
...
}
Atualizar o manifesto
O manifesto de atualização retornado pelo servidor precisa ser um documento XML.
<?xml version='1.0' encoding='UTF-8'?>
<gupdate xmlns='http://www.google.com/update2/response' protocol='2.0'>
<app appid='aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'>
<updatecheck codebase='https://myhost.com/mytestextension/mte_v2.crx' version='2.0' />
</app>
</gupdate>
Esse formato XML é emprestado do usado pela Omaha, a infraestrutura de atualização do Google. O
sistema de extensões usa os seguintes atributos para os elementos <app>
e <updatecheck>
do
manifesto de atualização:
- appid
- O ID da extensão é gerado com base em um hash da chave pública, conforme descrito em empacotamento. O ID de uma extensão é exibido na página de gerenciamento de extensões.
- codebase
- Um URL HTTPS para o arquivo
.crx
. - versão
- Usado pelo cliente para determinar se ele precisa fazer o download do arquivo
.crx
especificado porcodebase
. Ele precisa corresponder ao valor de "version" no arquivomanifest.json
do arquivo.crx
.
O arquivo XML do manifesto de atualização pode conter informações sobre várias extensões incluindo vários
elementos <app>
.
testes
A frequência padrão de verificação de atualização é de várias horas, mas uma atualização pode ser forçada usando o botão Atualizar extensões agora na página de gerenciamento de extensões.
Isso vai iniciar a verificação de todas as extensões instaladas.
Uso avançado: parâmetros de solicitação
O mecanismo básico de atualização automática foi projetado para tornar o trabalho do lado do servidor tão fácil quanto descartar um arquivo XML estático em qualquer servidor da Web simples, como o Apache, e atualizar esse arquivo XML à medida que novas versões de extensão são lançadas.
Os desenvolvedores que hospedam várias extensões podem verificar os parâmetros da solicitação, que indicam o ID da extensão e a versão na solicitação de atualização. A inclusão desses parâmetros permite que as extensões sejam atualizadas pelo mesmo URL que executa o código dinâmico do lado do servidor, em vez de um arquivo XML estático.
O formato dos parâmetros da solicitação é:
?x=EXTENSION_DATA
Em que EXTENSION_DATA
é uma string codificada pelo URL com o formato:
id=EXTENSION_ID&v=EXTENSION_VERSION
Por exemplo, duas extensões apontam para o mesmo URL de atualização (https://test.com/extension_updates.php
):
- Extensão 1
- Código: "aaaaaaaaaaaaaaaaaaaaaaaaaaaa"
- Versão: "1.1"
- Extensão 2
- Código: "bbbbbbbbbbbbbbbbbbbbbbbbbbbb"
- Versão: "0.4"
A solicitação para atualizar cada extensão seria:
https://test.com/extension_updates.php?x=id%3Daaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa%26v%3D1.1
e
https://test.com/extension_updates.php?x=id%3Dbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb%26v%3D0.4
Várias extensões podem ser listadas em uma única solicitação para cada URL de atualização exclusivo. No exemplo anterior, se um usuário tiver as duas extensões instaladas, as duas solicitações serão mescladas em uma única solicitação:
https://test.com/extension_updates.php?x=id%3Daaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa%26v%3D1.1&x=id%3Dbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb%26v%3D0.4
Se o número de extensões instaladas usando o mesmo URL de atualização for grande o suficiente para que um URL de solicitação GET seja muito longo (mais de 2.000 caracteres), a verificação de atualização emite outras solicitações GET conforme necessário.
Uso avançado: versão mínima do navegador
À medida que mais APIs são adicionadas ao sistema de extensões, pode ser lançada uma versão atualizada de uma extensão que funcionará apenas com versões mais recentes do navegador. Embora o Google Chrome seja atualizado automaticamente, pode levar alguns dias até que a maior parte da base de usuários seja atualizada para qualquer nova versão. Para
garantir que uma determinada atualização seja aplicada apenas às versões do Google Chrome iguais ou mais recentes que
uma versão específica, adicione o atributo "prodversionmin" ao elemento <app>
na resposta da atualização.
<?xml version='1.0' encoding='UTF-8'?>
<gupdate xmlns='http://www.google.com/update2/response' protocol='2.0'>
<app appid='aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'>
<updatecheck codebase='http://myhost.com/mytestextension/mte_v2.crx' version='2.0' prodversionmin='3.0.193.0'/>
</app>
</gupdate>
Isso garante que os usuários façam a atualização automática para a versão 2 somente se estiverem executando o Google Chrome 3.0.193.0 ou mais recente.