App antigo e API nova: como manter compatibilidade em React Native com Expo

Uma verdade pouco glamourosa do mobile e esta: o usuario nao atualiza o app no mesmo minuto em que voce sobe uma versao nova para a loja. Enquanto o time ja esta pensando no proximo ajuste, parte da base continua em build antiga, outra parte recebe update OTA, outra ainda esta em TestFlight ou beta, e o backend precisa sobreviver a essa mistura sem transformar cada login, push ou chamada HTTP em loteria.

Em app corporativo, esse problema aparece cedo. O backend evolui para suportar uma nova tela, um novo status, um novo fluxo de aprovacao, upload, autenticacao ou offline. Se a API quebrar consumidores antigos sem transicao, o erro pode nao atingir todo mundo de uma vez, o que torna a investigacao ainda mais confusa. Um usuario diz que funciona. Outro diz que a mesma tarefa falha. E ambos podem estar certos.

Este guia organiza uma estrategia pratica para React Native com Expo: separar versao do app, build e runtimeVersion; planejar compatibilidade entre app e API; usar canais, staging e rollout com mais criterio; e definir quando uma versao antiga ainda e suportada ou precisa ser aposentada.

1. Mobile em producao sempre convive com versoes diferentes

A documentacao da Expo sobre deploy de updates lembra que isso e comum: quando ha multiplas versoes binarias em producao, o time precisa entender qual codigo esta rodando em qual grupo de usuarios. Em outras palavras, seu app nao e um site onde todo mundo recarrega a versao nova. Existem usuarios no binario da loja, usuarios em beta, usuarios com update OTA mais recente e usuarios que ainda nao atualizaram nada.

Antes de pensar em correcao, aceite a topologia real do problema:

• nem toda pessoa instala a nova versao no dia do release;
• nem toda mudanca JavaScript pode ir para qualquer binario;
• a API pode estar sendo chamada por clientes com comportamentos diferentes;
• o suporte precisa saber qual versao realmente esta no aparelho.

Esse pano de fundo conversa diretamente com o artigo publicar app Android e iOS: release mobile nao termina no upload para a loja.

2. Separe quatro coisas que muita equipe mistura

Quando o time fala apenas "versao 1.4", costuma misturar conceitos demais. A documentacao da Expo separa bem algumas camadas:

• app version: a versao funcional vista pelo usuario;
• build number no iOS e versionCode no Android: identificadores de binario usados para distribuicao e loja;
• runtimeVersion: identificador de compatibilidade entre o codigo nativo do build e um update OTA;
• channel: alvo logico para publicacao e promocao de updates.

Essa separacao ajuda a responder perguntas diferentes. Build number identifica o binario exato que foi instalado. Runtime version ajuda a saber se um OTA update pode rodar com seguranca naquele binario. Channel ajuda a decidir para qual ambiente ou publico o update sera enviado.

O artigo Expo, development build e EAS Build ja prepara essa base; aqui o foco e operar em producao sem quebrar quem ficou para tras.

3. Runtime version nao e etiqueta decorativa

A documentacao oficial da Expo afirma que runtime versions existem para garantir compatibilidade entre o codigo nativo do build e um update. O raciocinio e simples: se o binario instalado nao contem determinada mudanca nativa, ele nao pode receber um pacote OTA que depende dela. Caso contrario, o update pode falhar e o sistema tentar voltar para a versao anterior funcional.

Isso leva a uma regra muito pratica: toda vez que voce muda algo que afeta runtime nativo, precisa pensar em novo build e em nova compatibilidade. Nao e so uma questao de JavaScript.

Estruturas que costumam exigir mais cuidado:

• nova biblioteca nativa;
• mudanca em permissao de Android ou iOS;
• troca de SDK Expo com impacto nativo;
• alteracao em configuracao que muda o binario.

Se a equipe trata runtimeVersion como detalhe que "depois a gente ajusta", aumenta a chance de enviar update para build que nao consegue suportar o novo pacote.

4. App version e um bom eixo para compatibilidade simples

No guia de deploy de updates, a Expo recomenda por padrao usar a politica appVersion para runtimeVersion em muitos projetos. A ideia e manter cada release nativo com uma runtime unica e facil de entender. Isso reduz carga conceitual para times pequenos, desde que o time mantenha a disciplina de incrementar a app version quando a compatibilidade nativa muda.

Esse modelo funciona bem quando a equipe quer responder com clareza:

• quais updates servem para a versao 1.4.0;
• quais hotfixes precisam atingir apenas a 1.3.2;
• quais builds ainda podem receber update sem novo binario;
• quando uma mudanca exige subida completa para loja.

Se o projeto ficar mais sofisticado depois, e possivel evoluir. Mas um fluxo simples e compreendido costuma ser mais valioso do que uma estrategia poderosa e mal operada.

5. API precisa evoluir como contrato que convive com clientes antigos

Boa parte dos incidentes atribuídos ao mobile nasce na API. Um campo some da resposta, um enum ganha valor novo sem fallback, um endpoint antigo muda significado, uma validacao nova rejeita payload que a versao antiga ainda envia. O app nao precisa estar tecnicamente quebrado para o fluxo falhar; basta o contrato mudar sem transicao.

Praticas que ajudam muito:

• preferir mudancas aditivas antes de mudancas quebradoras;
• nao remover campo consumido por versoes antigas sem janela clara;
• tratar valor desconhecido com fallback razoavel na interface;
• versionar comportamento quando a regra realmente mudou;
• medir quais versoes do app ainda usam cada contrato antigo.

O artigo validacao e erros em API REST ajuda a desenhar respostas mais previsiveis. Em mobile, previsibilidade de API e parte da experiencia do produto.

6. Envie a versao do app para o backend e use isso a seu favor

O backend nao precisa adivinhar qual cliente o chamou. Vale enviar, de forma segura e documentada, sinais como versao funcional do app, build number, plataforma e eventualmente runtimeVersion quando isso ajudar suporte e rollout.

Com isso, o time pode:

• correlacionar erros a uma faixa de builds;
• descobrir se um bug afeta so Android ou so iOS;
• identificar clientes muito desatualizados;
• decidir se precisa manter rota antiga por mais tempo;
• ligar incidente mobile com logs da API.

Esse desenho conversa com logs e correlacao de requisicao no Spring Boot e com observabilidade em app React Native em producao. Sem esses sinais, compatibilidade vira palpite.

7. Nem toda diferenca de versao precisa virar endpoint novo

Times pequenos as vezes caem em dois extremos: ou quebram o contrato antigo sem aviso, ou criam uma API paralela para qualquer detalhe. O caminho maduro costuma estar no meio.

Estratégias proporcionais incluem:

• campos novos opcionais com fallback claro;
• feature flag para liberar comportamento novo sem afetar todos os clientes;
• resposta compatível com clientes antigos por um periodo definido;
• recurso novo escondido ate que a versao minima esteja difundida;
• endpoints novos so quando a mudanca de fluxo realmente justifica.

A questao nao e deixar tudo para sempre. E dar tempo para a base migrar sem transformar release em corte brusco.

8. Use channel, staging e preview para testar a convivencia real

No guia de deploy, a Expo mostra um fluxo simples: builds apontam para canais como preview, staging e production, enquanto runtimeVersion determina quais updates cada build pode receber. Isso e valioso porque permite testar update com a mesma runtime da producao antes de promovê-lo para toda a base.

Na pratica:

• builds de preview ajudam a validar mudancas em distribuicao interna;
• staging permite testar o mesmo runtime em um grupo menor antes da producao;
• production recebe apenas o que ja foi observado com mais calma.

Esse tipo de rotina reduz o risco de um hotfix aparentemente simples quebrar usuarios com binario antigo ou configuracao diferente.

9. Rollout gradual e melhor do que descobrir tudo de uma vez

A documentacao da Expo tambem recomenda rollout gradual quando ha duvida sobre impacto. Em vez de soltar um update de uma vez para 100% da base, o time pode começar com uma fração menor e observar sinais de erro. Se algo piora, o rollout pode ser interrompido ou revertido antes de atingir todos.

Para app corporativo, isso ajuda em casos como:

• ajuste de login;
• mudanca na navegacao depois de push;
• nova estrategia de sincronizacao offline;
• correcao em upload ou anexos;
• mudanca de contrato com a API que parece compativel, mas precisa de prova.

Rollout gradual nao substitui teste. Ele reduz blast radius quando o teste nao capturou tudo.

10. Defina versao minima suportada antes que o problema faca isso por voce

Em algum momento, manter compatibilidade eterna fica caro. O time precisa decidir quando uma versao muito antiga deixara de ser suportada, seja por seguranca, por mudanca grande de contrato ou por custo operacional.

Boas perguntas:

• quantos usuarios ainda estao na versao antiga?
• o backend esta carregando regra demais so para manter esse grupo?
• a versao antiga expoe risco de seguranca ou dado incorreto?
• ha comunicacao clara antes de exigir update?
• o app mostra mensagem humana quando a versao minima e ultrapassada?

Versao minima suportada nao deve surgir no susto. Ela precisa ser planejada, medida e comunicada.

11. Compatibilidade tambem passa por push, deep link e sessao

Mesmo que a API esteja aceitavel, uma combinacao ruim entre push, link e sessao pode quebrar fluxos so em certas builds. Exemplo: a notificacao nova envia uma URL que a versao antiga nao sabe resolver. Ou o app antigo nao trata um novo tipo de origem depois do login.

Por isso, vale cruzar este tema com deep links, push e navegacao. A compatibilidade real de um release nao mora apenas no endpoint; ela tambem mora na rota que o app consegue abrir, no estado que ele restaura e no que acontece se o usuario vier de uma notificacao velha para uma tela nova.

12. O que observar por versao

Alguns sinais valem ouro quando o time opera multiplas versoes:

• falhas de login por app version;
• erros de API por build ou plataforma;
• tempo de resposta por faixa de versao;
• crashes depois de determinado update;
• percentual da base ainda em versao antiga;
• uso residual de endpoint legado;
• falha de push ou deep link concentrada em uma release.

A pagina de indicadores tecnicos e o artigo sobre observabilidade ajudam a transformar isso em rotina, nao apenas em resposta a incidente.

13. Checklist rapido de compatibilidade

1. Separar app version, build number/versionCode, runtimeVersion e channel.
2. Decidir politica simples de runtimeVersion e aplica-la com disciplina.
3. Tratar API como contrato que convive com clientes antigos.
4. Enviar versao do app para o backend quando isso ajudar suporte e diagnostico.
5. Testar updates em preview ou staging com runtime igual a producao.
6. Usar rollout gradual em mudancas mais sensiveis.
7. Observar erros por versao, nao so no agregado.
8. Definir versao minima suportada antes do colapso operacional.
9. Revisar push, deep link e sessao nas combinacoes antigas e novas.
10. Documentar quando uma compatibilidade temporaria sera removida.

14. Erros comuns

• falar apenas "versao 1.4" sem saber se isso significa app version, build ou runtime;
• enviar OTA compativel em JavaScript, mas incompativel com binario nativo;
• mudar API quebrando consumidor antigo sem medir quem ainda o usa;
• nao registrar versao do app nos logs do backend;
• promover update para producao sem validar a mesma runtime em staging;
• forcar endpoint novo quando um fallback curto resolveria a transicao;
• aposentar versao antiga sem mensagem, prazo ou evidencia.

15. Quando procurar ajuda tecnica

Se cada release mobile vira mistura de hotfix, API ajustada correndo, usuarios antigos quebrando e time sem clareza sobre quem recebeu o que, o problema ja nao e uma tela ou endpoint isolado. E um problema de gestao de compatibilidade entre app, runtime, update e backend. Nessa hora, um diagnostico tecnico ajuda a montar uma trilha de estabilizacao sem reinventar tudo de uma vez.

Compatibilidade boa em mobile nao significa nunca mudar. Significa conseguir evoluir com criterio: saber o que cada versao suporta, como testar antes de espalhar, como observar depois e quando encerrar suporte sem improviso. E isso torna o app mais confiavel para o usuario e menos caotico para quem mantem.

Referencias editoriais: Expo Runtime versions and updates, Expo Deploy updates, Expo app config e Expo Rollouts.