Como forçar atualização no React Native antes de um defeito grave.

Em 30 de outubro de 2026, durante uma triagem de monitoramento de erros do Garfim, encontrei um padrão que se repetia: defeitos em versões antigas continuavam em uso por semanas.

Quando um aplicativo é publicado no Google Play ou na App Store e não tem atualização pelo ar, uma versão lançada não pode ser retirada das lojas. Sem um mecanismo próprio para forçar a atualização, cada alteração futura no servidor é obrigada a manter compatibilidade com todas as versões já distribuídas.

Para resolver esse problema de raiz, criei um portão de versão mínima suportada. A principal lição dessa arquitetura é simples: a trava precisa ser desenvolvida e publicada antes que um defeito grave aconteça.

Uma versão publicada na loja nunca deixa de existir

As lojas oficiais de aplicativos não oferecem um botão de reversão instantânea. Se você publica uma versão com um bug sutil de sincronização ou uma incompatibilidade de banco de dados, quem instalou essa versão continuará com ela aberta até decidir atualizar por conta própria.

Sem atualizações pelo ar no projeto, a única forma de fazer o código novo chegar ao aparelho é pela loja. Se o aplicativo não possui uma rotina nativa para verificar se ainda tem autorização para operar, ele pode continuar chamando a API até a pessoa atualizar. Na prática, o desenvolvedor vira refém das próprias decisões passadas.

A consequência no servidor é pesada. Sem uma forma de aposentar versões, cada mudança da API precisa considerar as versões já distribuídas.

A API publica a versão mínima e o app bloqueia a navegação

A solução adotada no Garfim funciona em duas pontas coordenadas. No servidor, a API publica variáveis de ambiente que definem a menor compilação aceita para cada sistema operacional: uma para iOS e outra para Android.

No aplicativo em React Native, o número da compilação instalada é lido diretamente do sistema nativo. A comparação utiliza os identificadores numéricos que crescem a cada geração do build, evitando ambiguidades entre nomes comerciais de versão. Essa consulta à API é pública, permitindo que a checagem ocorra logo na inicialização, antes mesmo do login do usuário ou do preenchimento de cadastros iniciais.

Quando o aplicativo detecta que a compilação atual está abaixo do limite mínimo publicado, o layout raiz entra em ação. Ele intercepta a navegação e substitui todas as rotas internas por uma tela única e intransponível de aviso. Nessa tela, uma mensagem objetiva explica a necessidade de atualizar e exibe um link direto para a respectiva loja de aplicativos.

O suporte a falhas e modo offline impede bloqueios acidentais

Um portão de atualização mal planejado pode criar um problema pior do que o bug que pretende evitar. Se a verificação depender estritamente de uma resposta rápida da rede a cada clique, qualquer oscilação de sinal impedirá o usuário de abrir o aplicativo.

Para contornar essa fragilidade, o Garfim adota regras estritas de resiliência:

• Se a resposta da API trouxer versão desconhecida ou a variável estiver vazia, o app nunca bloqueia.
• A verificação não atrasa as telas, permitindo abrir a interface sem esperar a rede.
• A última resposta válida fica salva localmente. Uma compilação já bloqueada continua barrada se abrir sem internet.
• A cada abertura e retorno ao primeiro plano com conexão ativa, uma nova checagem é feita. Reduzir o mínimo libera o app na hora.

Hoje, nenhuma versão está bloqueada no ambiente de produção. O portão está armado e pronto para agir apenas se uma emergência real exigir a retirada de uma compilação do ar.

A trava só pode ser exigida depois da distribuição total na loja

Subir o número da versão mínima no servidor é uma decisão operacional delicada, pois pode bloquear o acesso de quem ainda usa uma versão abaixo do mínimo. Por essa razão, essa alteração não é feita por cliques improvisados em painéis: ela passa por revisão de código e é publicada por meio de esteira de integração contínua.

Existe uma regra de ouro para elevar esse patamar: a versão substituta precisa estar cem por cento disponível para todos os usuários na loja correspondente. Se o Google Play estiver executando um lançamento gradual, ou se a versão da App Store ainda não tiver sido liberada, subir o mínimo na API deixará pessoas barradas diante de uma loja que ainda não oferece o botão de atualizar.

Na Apple, a liberação gradual distribui as atualizações automáticas; uma versão já lançada fica disponível para atualização manual. O portão de versão mínima só deve alcançar compilações que já tenham uma alternativa pública e acessível para a base inteira.

O portão de versão precisa nascer antes do primeiro incidente

A maior armadilha desse mecanismo é a ilusão de que ele pode ser construído quando o problema aparecer. O portão só protege as versões que já trazem o código da checagem compilado dentro de si.

Se uma compilação antiga não foi programada para consultar a API e substituir a navegação, nenhuma instrução remota fará aquela tela de bloqueio surgir. O servidor até poderia recusar as requisições com erros genéricos, mas a pessoa no celular veria apenas mensagens confusas de falha de conexão, sem entender que precisa abrir a loja e baixar a atualização.

Por isso a trava entrou na versão 0.1.2 do Garfim, enviada às duas lojas em 31 de outubro de 2026. As compilações anteriores ainda dependem de cuidados no servidor, mas as versões que incluem a trava obedecem à regra. Criar a trava antes do defeito dá tranquilidade para evoluir o sistema. Para ver os passos anteriores da preparação do aplicativo, confira o relato sobre conseguir testadores e esperar 14 dias.