Gerenciamento de versões

Magdalena Skarbińska
Magdalena Skarbińska
Demián Renzulli
Demián Renzulli
X GitHub

Os Apps Isolados da Web (IWAs) oferecem um ambiente de execução de alta confiança, seguro e com controle de versão na plataforma da Web. Em ambientes de produção, principalmente em empresas gerenciadas, os administradores e desenvolvedores precisam de controle refinado sobre as implantações de software.

Para atender a esses requisitos, o Chrome oferece recursos abrangentes de gerenciamento de versões para IWAs, incluindo canais de atualização, fixação de versão e reversão de versão. Esses recursos permitem a previsibilidade da implantação e controles de recuperação rápida em toda a base de usuários.

Disponibilidade

O comportamento do gerenciamento de versões depende se o IWA é gerenciado por um administrador ou instalado diretamente por um usuário:

  • AIWs gerenciados: os recursos administrativos (incluindo fixação e downgrade orientados por políticas) estão disponíveis no Chrome 133.
  • IWAs não gerenciados (instalados pelo usuário): os recursos voltados ao usuário (como a seleção manual de canal) estão disponíveis no Chrome 150.

Compatibilidade do tipo de sessão

Todas as funcionalidades de gerenciamento de versões, incluindo canais de atualização e fixação de versões, são totalmente compatíveis com todos os tipos de sessão do ChromeOS. Isso inclui:

  • Sessões de usuário gerenciadas padrão
  • Sessões de visitante gerenciadas (MGS, na sigla em inglês)
  • Ambientes dedicados do Modo quiosque

Atualizar canais

Ao usar canais de atualização, os desenvolvedores podem segmentar builds de aplicativos específicos para diferentes públicos-alvo de implantação e teste. Para configurar canais, adicione um campo de matriz de canais opcional a cada entrada de versão no manifesto de atualização do aplicativo. Esses nomes de canais não são restritos a palavras-chave de plataforma fixas (como canary ou stable), mas são identificadores arbitrários, definidos pelo desenvolvedor, que precisam ser formatados como strings alfanuméricas ASCII em letras minúsculas (que podem incluir hifens ou sublinhados, mas não espaços). Se uma entrada de versão omitir totalmente o campo de canais, o Chrome vai definir implicitamente a disponibilidade como o canal "padrão". Por fim, o nome do canal designado na política administrativa precisa corresponder exatamente à string definida no manifesto. Qualquer erro tipográfico ou configuração incompatível resultará na não identificação de uma versão qualificada, interrompendo as atualizações para esses clientes.

Configuração do manifesto

Para configurar canais, adicione uma matriz channels opcional a cada entrada de versão no manifesto do app da Web. Confira algumas considerações:

  • Mapeamento de canais: se uma entrada de versão definir uma matriz channels, essa versão só poderá ser instalada nos canais especificados.
  • O substituto padrão: se uma entrada de versão omitir totalmente o campo channels, o Chrome vai presumir que a versão pertence exclusivamente ao canal default.
  • Correspondência exata de string: os nomes dos canais especificados nas configurações de política do lado do cliente precisam corresponder exatamente às strings definidas no manifesto de atualização (diferencia maiúsculas de minúsculas). Se nenhuma versão corresponder ao nome do canal segmentado, o app não vai encontrar atualizações qualificadas.

Exemplo de manifesto de atualização

O exemplo a seguir mostra um manifesto de atualização compatível com vários canais de lançamento:

{
  "versions": [
    {
      "version": "0.1.0",
      "src": "https://github.com/chromeos/iwa-sink/releases/download/v0.1.0/iwa-sink.swbn",
      "channels": ["delta"]
    },
    {
      "version": "0.2.0",
      "src": "https://github.com/chromeos/iwa-sink/releases/download/v0.2.0/iwa-sink.swbn",
      "channels": ["delta", "default"]
    },
    {
      "version": "0.3.0",
      "src": "https://github.com/chromeos/iwa-sink/releases/download/v0.3.0/iwa-sink.swbn",
      "channels": ["beta", "delta"]
    },
    {
      "version": "0.4.0",
      "src": "https://github.com/chromeos/iwa-sink/releases/download/v0.4.0/iwa-sink.swbn"
    }
  ]
}

Com base nesse manifesto, as seguintes versões estão disponíveis por canal segmentado:

  • padrão: 0.2.0,0.4.0 (que não tem um canal explícito e usa o padrão)
  • delta: 0.1.0, 0.2.0, 0.3.0
  • beta: 0.3.0

O mecanismo de atualização do AIW é compatível com a segmentação de canais de lançamento específicos ao procurar um campo de canais no manifesto de atualização do app.

Fixação de versão

Em ambientes corporativos de alta conformidade ou altamente estáveis, os administradores precisam garantir que os dispositivos executem versões exatas de softwares essenciais para os negócios. A fixação de versão permite que os administradores bloqueiem um AIW em uma versão específica, interrompendo todas as atualizações em segundo plano subsequentes. Isso oferece às empresas uma maneira altamente confiável de manter configurações estáveis e obedecer a regulamentações internas ou do setor rigorosas.

Para congelar um App Isolado da Web (IWA, na sigla em inglês) em um build de lançamento específico, os administradores empresariais podem configurar a propriedade pinned_version na política IsolatedWebAppInstallForceList. Esse recurso é gerenciado principalmente pelos controles de interface interativos no Google Admin Console, no painel de detalhes do aplicativo, seguindo o fluxo de trabalho de instalação padrão do IWA. No entanto, os administradores também podem implantar esses valores de política diretamente usando configurações JSON brutas. Depois que uma string de versão válida é segmentada pelo administrador, o Chrome extrai esse pacote explícito e bloqueia todas as atualizações automáticas subsequentes.

Comportamentos e restrições especiais

  • Retomar as atualizações (desfixar): para restaurar as atualizações automáticas, remova a propriedade pinned_version ou mude o valor dela para uma versão de destino mais recente.
  • Sem downgrade por padrão: definir pinned_version como uma versão anterior à instalada não vai acionar uma reversão, a menos que allow_downgrades esteja explicitamente ativado.
  • Destinos de fixação indisponíveis: se o pinned_version configurado estiver ausente do canal de atualização designado ou for mais antigo que a versão instalada (com downgrades desativados), o Chrome vai manter a versão instalada e bloquear outras atualizações.
  • Novas implantações: se um AIW ainda não estiver instalado em um dispositivo gerenciado e a pinned_version especificada não puder ser recuperada ou estiver ausente do manifesto de atualização, o AIW não será instalado.

Versão em downgrade

Se uma atualização recém-implantada introduzir um bug ou uma vulnerabilidade crítica, os administradores talvez precisem reverter os dispositivos para um estado estável anterior. O Chrome permite fazer downgrade de IWAs gerenciados já instalados para uma versão anterior, um recurso que antes não estava disponível na plataforma, quando apenas atualizações eram permitidas.

O downgrade só será possível se ambas as condições de política a seguir forem atendidas:

  1. pinned_version está definido como uma versão válida e mais antiga.
  2. allow_downgrades está explicitamente definido como verdadeiro.

Como funcionam os downgrades

  • Mecanismo de acionamento: as reversões são processadas durante o ciclo regular de verificação de atualizações, que é executado a cada 4 a 6 horas.
  • Nos bastidores: o Chrome faz uma reinstalação completa do IWA usando o pacote da Web mais antigo (.swbn) especificado no manifesto de atualização.

Lógica de transição de canal

Ao mudar o canal de destino de um app com uma política, o mecanismo de atualização segue comportamentos específicos:

Cenário A: mudar para um canal com versões anteriores

  • Se o downgrade for permitido: se pinned_version corresponder a uma versão mais antiga no canal de destino e allow_downgrades for verdadeiro, uma reversão vai ocorrer (e os dados do usuário local serão apagados).
  • Se o downgrade não for permitido: nenhum downgrade vai ocorrer. O dispositivo vai permanecer na versão mais recente instalada e só será atualizado quando uma versão mais recente estiver disponível no canal recém-selecionado.

Cenário B: mudar para um canal com uma versão idêntica

  • Nenhuma mudança: se o canal recém-selecionado apontar para um número de versão igual ao instalado, o Chrome não fará modificações no pacote instalado.
  • Princípio de identidade byte a byte: os desenvolvedores precisam garantir que números de versão idênticos em canais diferentes contenham assinaturas de código idênticas e correspondentes em bytes. Implantar bases de código diferentes com a mesma string de versão em vários canais pode resultar em estados de aplicativo inesperados e instáveis.

Configuração da política administrativa

Os controles de versão corporativos são aplicados com a plataforma centralizada do Google Admin Console usando o esquema de política IsolatedWebAppInstallForceList. Essas configurações podem ser gerenciadas diretamente pelos controles de interface no Admin Console ou implantadas usando configurações de política JSON brutas.
O exemplo de configuração de política administrativa a seguir demonstra canais de atualização, fixação de versão e downgrades:

Representação do valor da política

[
  {
    "update_manifest_url": "https://awesome-kitchen-sink.glitch.me/update.json",
    "web_bundle_id": "aiv4bxauvcu3zvbu6r5yynoh4atkzqqaoeof5mwz54b4zfywcrjuoaacai",
    "channel": "beta",
    "pinned_version": "0.7.0",
    "allow_downgrades": true
  }
]

Explicações dos parâmetros do esquema

  • channel (string, opcional): instrui o Chrome a avaliar apenas as versões atribuídas a esse canal no manifesto de atualização. Se omitido, o Chrome avalia o canal "padrão".
  • pinned_version (string, opcional): bloqueia explicitamente o dispositivo na string de versão especificada. As atualizações automáticas em segundo plano subsequentes são bloqueadas.
  • allow_downgrades (booleano, opcional): ativa a capacidade de reversão. Se for verdadeiro e estiver pareado com um pinned_version mais antigo e válido, o Chrome vai acionar uma reinstalação de downgrade. Aviso: definir esse parâmetro como verdadeiro vai bloquear todas as atualizações de encaminhamento padrão, mesmo que o campo pinned_version seja omitido.

IWAs não gerenciados (instalados pelo usuário) (a partir da versão 150)

Para Apps Isolados da Web não gerenciados e instalados pelo usuário, o controle de versões funciona com interações manuais do usuário:

Pacote de instalação ──► Usuário seleciona o canal ──► Verificações automáticas no canal selecionado

Pré-requisito do manifesto para atualizações automáticas

Para que os IWAs instalados pelo usuário verifiquem e recebam atualizações periódicas automáticas em segundo plano, o manifesto do app da Web local (os metadados empacotados dentro do pacote em /.well-known/manifest.webmanifest) precisa conter um campo update_manifest_url válido.

Se esse URL for omitido do arquivo de manifesto local do aplicativo, o mecanismo de atualização não gerenciado nunca vai realizar verificações em segundo plano, e o aplicativo vai permanecer permanentemente congelado na versão de instalação inicial.

Seleção manual de canais

Durante a instalação inicial de um IWA não gerenciado, o navegador verifica o manifesto de atualização e mostra as opções de canal disponíveis (por exemplo, "Estável", "Beta") diretamente ao usuário se o desenvolvedor tiver configurado vários canais.

Regras de ciclo de vida das chaves

  1. Origem da primeira instalação: independentemente do canal selecionado pelo usuário na instalação, a instalação inicial sempre implanta os arquivos empacotados no pacote de instalação fornecido.
  2. Atualizações subsequentes: depois de instaladas, as atualizações futuras são consultadas exclusivamente no canal escolhido. O app só será atualizado quando uma versão mais recente do que a instalada for publicada nesse canal segmentado.
  3. Troca de canais: para mudar para um canal de atualização diferente após a instalação, o usuário precisa desinstalar o AIW e reinstalá-lo, escolhendo o canal selecionado durante o fluxo de instalação.

Como testar implantações gerenciadas

Para administradores que gerenciam dispositivos pelo Admin Console do Chrome Enterprise ou configuram políticas diretamente:

  1. Acesse o painel Detalhes do app nas configurações da organização.
  2. Aplique propriedades de configuração para testar a fixação e as segmentações de canais. Como esses controles são totalmente compatíveis com sessões de usuário padrão, sessões de visitante gerenciadas (MGS, na sigla em inglês) e quiosques, é possível verificar comportamentos em todos os ambientes de implantação de destino.
  3. Para inspecionar as verificações de atualização localmente, acesse chrome://web-app-internals em um cliente de teste para forçar manualmente as verificações de atualização e analisar os pacotes de manifesto recebidos.

Conclusão

A arquitetura de segurança dos Apps Isolados da Web foi projetada para capacitar os desenvolvedores, mantendo a previsibilidade e o controle rígidos sobre os comportamentos do ciclo de vida do aplicativo. Ao aproveitar os recursos de gerenciamento de versões do Chrome, desenvolvedores e administradores de TI podem criar pipelines de implantação robustos que se alinham a padrões de compliance rigorosos e metas operacionais.

Ao projetar e gerenciar a estratégia de atualização do aplicativo, lembre-se destes princípios básicos:

  • Use canais progressivos: os canais de atualização (como beta, dev ou anéis personalizados) permitem que você colete telemetria e feedback de forma progressiva. Isso garante que as atualizações importantes passem por uma verificação rigorosa antes de serem disponibilizadas para a população geral no canal padrão.
  • Fixação para estabilidade: em ambientes corporativos altamente estruturados ou orientados para conformidade, bloqueie endpoints críticos para uma pinned_version exata e verificada para proteger as operações contra falhas inesperadas ou interrupções no fluxo de trabalho.
  • Reserve downgrades para emergências: o downgrade de versão é uma válvula de segurança corretiva poderosa que antes era impossível. No entanto, como uma reversão aciona uma reinstalação completa e limpa todo o armazenamento do cliente local (IndexedDB, LocalStorage, cookies), ela precisa ser reservada estritamente para correções de segurança críticas. Para patches comuns, implantar uma pequena atualização prospectiva é sempre a estratégia ideal.
  • Entenda as sinalizações de política: tenha cuidado com as chaves administrativas. Ativar allow_downgrades vai interromper todas as atualizações futuras, mesmo que uma fixação não esteja definida ativamente.
  • Estabeleça a integridade byte a byte: garanta que os números de versão idênticos implantados em diferentes canais sejam mapeados para pacotes idênticos com correspondência de bytes para evitar estados de aplicativo irregulares quando os clientes fizerem a transição entre canais.

Ao integrar esses recursos diretamente ao manifesto de atualização e ao esquema de política empresarial, você garante um fluxo de atualização confiável, auditável e seguro que preserva as garantias de alta confiança do ecossistema de apps isolados da Web.