Deep link em app React Native: Expo, push e navegacao sem rota quebrada

Deep link parece detalhe ate o dia em que o usuario toca na notificacao, cai na tela errada, abre o app sem contexto ou para em login sem retornar ao que realmente precisava fazer. Em app corporativo, isso custa mais do que uma irritacao visual. O link costuma carregar uma tarefa: aprovar item, revisar pendencia, abrir documento, continuar atendimento, ver ocorrencia, responder alerta operacional.

Quando esse caminho falha, o suporte escuta frases vagas como "a notificacao nao abriu", "o app abriu mas nao foi para a tela", "o link do e-mail caiu na home", "depois do login eu perdi a tarefa". O problema raramente esta em um botao isolado. Ele nasce na combinacao entre esquema de URL, configuracao nativa, navegacao, sessao, push e expectativa de fallback quando o app nem esta instalado.

Este guia organiza uma implementacao pratica de deep links em React Native com Expo e React Navigation, pensando em app corporativo real: notificacao push, rota protegida, contexto de API, site de apoio e comportamento previsivel em Android e iOS.

1. Deep link e sobre tarefa, nao sobre URL bonita

O primeiro passo e decidir quais fluxos realmente merecem link direto. Nem toda tela precisa ser aberta por fora. Em geral, deep link vale quando reduz atrito em uma tarefa concreta:

• abrir uma aprovacao pendente;
• entrar em um chamado especifico;
• continuar upload ou sincronizacao interrompida;
• abrir detalhe enviado por e-mail ou WhatsApp;
• voltar para um item citado em notificacao.

Se o app ainda nao definiu esses fluxos, o time corre o risco de abrir links para telas genericas e obrigar o usuario a procurar o resto manualmente. O artigo arquitetura inicial do app corporativo ajuda a escolher tarefas mobile com mais criterio antes de publicar rotas externas.

2. Entenda os tipos de link que entram no jogo

A documentacao oficial da Expo diferencia tres estrategias: links do seu dominio web que podem abrir o app, links com esquema customizado que abrem o app a partir de outros apps ou sites, e links que saem do app para outro destino. Para o caso de entrada no aplicativo, a distincao principal e esta:

• custom URL scheme: algo como rmportotech://aprovacoes/123;
• universal links no iOS e app links no Android: links HTTP(S) do seu dominio, como https://app.exemplo.com/aprovacoes/123.

Os links HTTP(S) costumam ser mais fortes para app corporativo porque, se o app nao estiver instalado, o usuario ainda pode cair no site correspondente. A propria Expo recomenda universal linking para links baseados em HTTP(S), enquanto esquemas customizados continuam uteis em integracoes internas, testes ou fluxos controlados.

3. Defina um contrato simples entre URL e rota

Antes de escrever configuracao, vale desenhar um mapa claro entre URL externa e rota interna. Exemplo:

• /aprovacoes/:id abre a tela de detalhe de aprovacao;
• /ocorrencias/:id abre a ocorrencia correta;
• /meus-alertas abre a lista com filtro aplicado;
• /recuperar-sessao volta ao fluxo apos autenticacao.

Boas praticas:

• usar caminhos curtos e semanticamente estaveis;
• evitar depender de parametro que so existe em memoria local;
• tratar ids, filtros e origem de forma previsivel;
• garantir que a tela saiba buscar dados novamente se o app foi aberto do zero.

O deep link nao deve assumir que todo contexto ja esta carregado. Quando o app abre frio, ele precisa restaurar sessao, montar navegacao e so depois resolver a rota.

4. Expo e React Navigation pedem configuracao certa de prefixo

A documentacao do React Navigation orienta configurar um esquema para o app e usar Linking.createURL quando o projeto usa Expo. O motivo e pratico: o esquema muda entre Expo Dev Client e app standalone, entao essa funcao abstrai a diferenca para que o mesmo codigo funcione nos ambientes de desenvolvimento e publicacao.

Na pratica, o objeto de linking costuma reunir:

• prefixo do app criado por Linking.createURL;
• dominio HTTP(S) do produto quando houver universal link ou app link;
• mapeamento entre caminhos externos e rotas internas.

Esse ponto conversa diretamente com o artigo Expo, development build e EAS Build, porque deep link real raramente deve ser validado apenas em Expo Go. A propria Expo avisa que o suporte a incoming links no Expo Go e limitado e recomenda development builds para testar linking de forma mais fiel.

5. O app precisa tratar dois cenarios: abrir fechado e receber link aberto

A documentacao do React Navigation deixa isso bem direto: para links de entrada, existem pelo menos dois cenarios que precisam funcionar. Se o app estava fechado, o deep link deve definir o estado inicial. Se o app ja estava aberto, o link precisa atualizar o estado para refletir a nova rota.

O React Native oferece a API Linking para isso. A documentacao oficial mostra que getInitialURL() devolve a URL usada para abrir o app quando ela existe, enquanto eventos posteriores podem ser recebidos via listener. Em outras palavras: abrir e receber depois nao sao a mesma coisa.

Isso evita dois erros comuns:

• funcionar so quando o app ja esta aberto;
• funcionar so no cold start e falhar quando a pessoa toca em um segundo link depois.

O React Navigation ainda recomenda usar a configuracao de linking em vez de tentar resolver tudo manualmente por referencia de navegacao, porque o caminho manual costuma ficar mais propenso a erro.

6. Push notification tambem entra no contrato de deep link

A documentacao do React Navigation mostra um exemplo oficial de integracao com expo-notifications sobrescrevendo getInitialURL e subscribe. A ideia e boa para app corporativo: primeiro verificar se a abertura veio de um link real; se nao veio, olhar a ultima resposta de notificacao; depois, assinar tanto eventos de URL quanto eventos de toque na notificacao.

Na pratica, isso significa que a notificacao precisa carregar uma URL ou algum dado capaz de virar rota consistente. Em vez de depender de um if espalhado por cada tela, o app trata notificacao e deep link como duas portas para o mesmo destino.

Esse desenho fica mais previsivel quando o payload do push ja nasce com um campo como url ou com dados suficientes para o app montar a rota final. O artigo notificacoes push em app corporativo cobre a camada de entrega; aqui o foco e garantir que o toque na notificacao realmente leve para o lugar certo.

7. Rota protegida precisa sobreviver ao login sem perder contexto

Esse e um dos pontos que mais quebram experiencia. O usuario toca na notificacao, o app percebe que a sessao expirou, manda para login e depois esquece a tarefa original. Em ambiente corporativo, isso faz a pessoa repetir passos e reduz confianca no fluxo.

Uma estrategia saudavel costuma incluir:

• guardar temporariamente a rota desejada enquanto a sessao e restaurada;
• mandar para login apenas se realmente necessario;
• depois da autenticacao, retomar a rota pendente em vez de jogar o usuario na home;
• tratar link invalido, item removido ou permissao insuficiente com mensagem clara.

Isso se conecta ao artigo autenticacao mobile com token e refresh. Deep link sem fluxo de sessao bem resolvido costuma parecer problema de navegacao, mas a raiz esta no bootstrap de autenticacao.

8. Universal link e app link ajudam a nao perder o usuario quando o app nao esta instalado

A documentacao da Expo explica que universal links no iOS e app links no Android usam HTTP(S) e permitem abrir o app quando ele esta instalado, mas levam o usuario para o site associado quando ele nao esta. Isso e especialmente util para empresas que tem portal web e app convivendo juntos.

Na pratica, o dominio precisa servir dois papeis:

• verificar a associacao da plataforma com o app;
• entregar um fallback web util quando o aplicativo nao existe no aparelho.

Para a RM Porto Tech, esse raciocinio e valioso porque o site ja funciona como base editorial. O mesmo principio serve para apps corporativos conectados a portais, areas de cliente ou paginas de suporte.

9. Deferred deep linking e outro problema, e ele nao vem gratis

O React Navigation deixa claro que links padrao so funcionam se o app ja estiver instalado. Se a pessoa instala depois do clique, o contexto original normalmente se perde. Para manter parametros atraves da instalacao, entra o tema de deferred deep linking, que depende de logica adicional ou fornecedor especifico.

Isso significa que o time nao deve prometer esse comportamento sem desenho proprio. Para muitos apps corporativos pequenos, um fallback web bem pensado ja resolve a maior parte do problema. Quando a necessidade for atribuicao de campanha, onboarding por convite ou fluxo comercial mais complexo, ai sim vale avaliar solucao dedicada.

10. Teste deep link no ambiente certo

Linking costuma enganar em teste superficial. O fluxo passa em dev, falha em build real, ou funciona com esquema customizado e quebra com link do dominio. Vale validar pelo menos:

• abertura com app fechado;
• abertura com app em foreground;
• abertura com app em background;
• toque em notificacao com sessao valida;
• toque em notificacao com sessao expirada;
• link invalido ou item sem permissao;
• fallback web quando o app nao esta instalado.

Se o projeto usa Expo, development build ajuda muito a reproduzir comportamento mais proximo do real. E quando o app depende de atualizacao OTA, convem testar a rota tambem na combinacao de build e update que realmente vai a campo.

11. Deep link observavel reduz muito o custo de suporte

Quando esse fluxo falha, vale registrar alguns sinais tecnicos:

• URL recebida;
• origem: navegador, e-mail, notificacao;
• rota resolvida internamente;
• estado da sessao no momento;
• resultado final: abriu, redirecionou para login, falhou, item nao encontrado;
• versao do app e plataforma.

O artigo observabilidade em app React Native em producao ajuda a fechar esse circuito. Sem esses sinais, o time volta para o relato subjetivo do usuario. Com eles, fica possivel separar falha de link, permissao, sessao, push ou dado removido.

12. Erros comuns

• configurar so esquema customizado e esquecer o dominio HTTP(S);
• testar apenas com app aberto e ignorar cold start;
• deixar a notificacao abrir a home em vez da rota real;
• perder a rota original depois do login;
• acoplar deep link a estado que nao existe quando o app abre do zero;
• nao prever fallback web quando o app nao esta instalado;
• misturar deep link, push e navegacao com logica espalhada em varias telas;
• nao registrar a URL recebida quando o fluxo falha.

13. Checklist rapido para app corporativo

1. Escolher quais tarefas realmente precisam de deep link.
2. Definir contrato estavel entre URL externa e rota interna.
3. Configurar esquema do app e prefixos do dominio.
4. Tratar app fechado e app aberto como cenarios diferentes.
5. Integrar notificacao push ao mesmo pipeline de linking.
6. Guardar rota pendente durante login ou restauracao de sessao.
7. Ter fallback web para links HTTP(S) quando o app nao existir.
8. Testar em development build e em aparelho real.
9. Registrar sinais tecnicos para suporte.
10. Revisar comportamento quando o item nao existe mais ou o usuario nao tem permissao.

14. Quando procurar ajuda tecnica

Se o app ja tem push, login, API e portal web, mas tocar no link ainda gera comportamento imprevisivel, o problema pode estar menos em uma tela e mais na costura entre plataformas. Nessa hora, um diagnostico tecnico ajuda a revisar contrato de rota, sessao, payload de notificacao, fallback web e observabilidade, sem transformar cada falha em remendo isolado.

Deep link bem feito faz o app parecer mais simples para quem usa, mesmo quando a arquitetura por tras e mais sofisticada. E isso combina exatamente com o objetivo de um app corporativo confiavel: menos passos desnecessarios, menos ruptura de contexto e mais previsibilidade do clique ate a tarefa final.

Referencias editoriais: Expo Linking Overview, React Navigation Deep Linking, React Native Linking e Expo Notifications.