Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Gerenciamento de versões

Magdalena Skarbińska

Demián Renzulli

Os Apps Isolados da Web (IWAs) oferecem um ambiente de execução de alta confiança, seguro e com versões discretas na plataforma da Web. Em ambientes de produção, principalmente em empresas gerenciadas, 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 downgrade 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 de se a IWA é gerenciada por um administrador ou instalada diretamente por um usuário:

AIWs gerenciados:os recursos administrativos (incluindo fixação e downgrades baseados em 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 canais) estão disponíveis a partir do Chrome 150.

Compatibilidade de 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)
Ambientes dedicados do modo quiosque

Atualizar canais

Ao usar canais de atualização, os desenvolvedores podem segmentar builds de aplicativos específicos para públicos-alvo de implantação e teste distintos. 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 fixas da plataforma (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 hífens ou sublinhados, mas não espaços). Se uma entrada de versão omitir completamente o campo "channels", o Chrome vai definir implicitamente a disponibilidade para o canal "default". O nome do canal designado na política administrativa precisa corresponder exatamente à string definida no manifesto. Erros tipográficos ou configurações incompatíveis impedem a 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 fallback padrão:se uma entrada de versão omitir o campo channels por completo, o Chrome vai presumir que a versão pertence exclusivamente ao canal default.
Correspondência exata de strings:os nomes de 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 atualização do manifesto

O exemplo a seguir mostra um manifesto de atualização que oferece suporte a 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:

default: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 oferece suporte à segmentação de canais de lançamento específicos procurando 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. Com a fixação de versão, os administradores podem bloquear 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) em um build de lançamento específico, os administradores corporativos podem configurar a propriedade pinned_version na política IsolatedWebAppInstallForceList. Essa capacidade é gerenciada principalmente pelos controles interativos da interface do usuário no Google Admin Console, no painel de detalhes do aplicativo, seguindo o fluxo de trabalho padrão de instalação da IWA. No entanto, os administradores também têm a flexibilidade de implantar esses valores de política diretamente usando configurações JSON brutas. Depois que uma string de versão válida é direcionada pelo administrador, o Chrome extrai esse pacote explícito e bloqueia todas as atualizações automáticas futuras.

Comportamentos e restrições especiais

Retomada de atualizações (remoção da fixação): 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.
Nenhum downgrade por padrão:definir pinned_version para uma versão anterior à versão instalada no momento 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 faltando no 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 no momento e bloquear outras atualizações.
Implantações novas:se um AIW ainda não estiver instalado em um dispositivo gerenciado e a pinned_version especificada não puder ser recuperada ou estiver faltando no manifesto de atualização, a instalação do AIW vai falhar.

Downgrade da versão

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 inferior, um recurso que antes não estava disponível na plataforma quando apenas atualizações diretas eram permitidas.

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

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

Como funcionam os downgrades

Mecanismo de acionamento:os rollbacks são processados 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 trocar o canal segmentado de um app por 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, um rollback vai ocorrer (e os dados locais do usuário 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

Sem mudanças:se o canal recém-selecionado apontar para um número de versão igual ao instalado no momento, o Chrome não fará nenhuma modificação no pacote instalado.
Princípio de identidade byte a byte:os desenvolvedores precisam garantir que números de versão idênticos em diferentes canais contenham assinaturas de código idênticas que correspondam byte a byte. Implantar diferentes bases de código na mesma string de versão em vários canais pode resultar em estados de aplicativo inesperados e erráticos.

Configuração de políticas administrativas

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 da 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 de 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 vai avaliar o canal "default".
pinned_version (string, opcional): bloqueia explicitamente o dispositivo para a 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 pareado com um pinned_version válido e mais antigo, o Chrome vai acionar uma reinstalação de downgrade. Aviso:definir esse parâmetro como "true" vai bloquear todas as atualizações padrão de encaminhamento, mesmo que o campo pinned_version seja omitido.

IWAs não gerenciados (instalados pelo usuário) (a partir de 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 ──► O usuário seleciona o canal ──► Verificações automáticas no canal selecionado

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

Para que as IWAs instaladas 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 fará verificações em segundo plano, e o aplicativo permanecerá permanentemente congelado na versão de instalação inicial.

Seleção manual de canais

Durante a instalação inicial de uma IWA não gerenciada, o navegador verifica o manifesto de atualização e mostra as opções de canais 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

Origem da primeira instalação:independente do canal selecionado pelo usuário na instalação, a instalação inicial sempre implanta os arquivos empacotados no pacote de instalação fornecido.
Atualizações subsequentes:depois de instalado, 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 no canal de destino.
Troca de canais:para mudar para um canal de atualização diferente após a instalação, o usuário precisa desinstalar e reinstalar a IWA, 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:

Acesse o painel Detalhes do app nas configurações da organização.
Aplique propriedades de configuração para testar a fixação e os destinos de canais. Como esses controles são totalmente compatíveis com sessões de usuário padrão, sessões de convidados gerenciadas (MGS) e quiosques, é possível verificar comportamentos em todos os ambientes de implantação de destino.
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 e manter 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 e metas operacionais rigorosos.

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 toques personalizados) permitem coletar telemetria e feedback de forma progressiva. Isso garante que as atualizações principais passem por uma verificação rigorosa antes de chegar à população geral no canal padrão.
Fixar para estabilidade:em ambientes empresariais altamente estruturados ou orientados à conformidade, bloqueie endpoints críticos em uma pinned_version exata e verificada para proteger as operações contra falhas inesperadas ou interrupções no fluxo de trabalho.
Reserve os downgrades para emergências:reconheça que o downgrade de versão é uma válvula de segurança corretiva e poderosa que antes era impossível. No entanto, como um rollback aciona uma reinstalação completa e exclui todo o armazenamento local do cliente (IndexedDB, LocalStorage, cookies), ele deve ser reservado estritamente para correção de segurança crítica. Para patches comuns, a estratégia ideal é sempre implantar uma pequena atualização prospectiva.
Entenda as flags de política:fique atento às chaves administrativas. Ativar allow_downgrades interrompe todas as atualizações futuras, mesmo que um fixador não esteja definido ativamente.
Estabeleça a integridade byte a byte:garanta que números de versão idênticos implantados em diferentes canais sejam mapeados para pacotes idênticos e correspondentes byte a byte para evitar estados de aplicativo irregulares quando os clientes fazem 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 da Web isolados.