Melhores Práticas de Deep Linking
Um resumo condensado de 25 essenciais de deep linking para aplicativos Expo SDK 57 - rotas idempotentes, fallbacks seguros para URLs inválidas e higiene de verificação extraída de todas as páginas desta seção.
//
Busque em todas as páginas da documentação
Um resumo condensado de 25 essenciais de deep linking para aplicativos Expo SDK 57 - rotas idempotentes, fallbacks seguros para URLs inválidas e higiene de verificação extraída de todas as páginas desta seção.
Declare scheme em app.config.ts antes de enviar qualquer deep link: Esquemas personalizados são o caminho de desenvolvimento mais rápido e a espinha dorsal do redirecionamento OAuth - sem um esquema registrado, createURL e binários de loja não podem reivindicar URLs de entrada.
Prefira links HTTPS verificados para marketing ao consumidor: Universal Links e App Links abrem sem folhas de disambiguação - esquemas personalizados são aceitáveis para desenvolvimento e OAuth, mas frustram campanhas de e-mail quando outro aplicativo registra o mesmo esquema.
Reconstrua binários nativos após alterações de esquema ou domínio: Entitlements e filtros de intenção são compilados no prebuild - atualizações OTA não podem adicionar associatedDomains ou filtros de intenção autoVerify.
Use Linking.createURL para links de saída - nunca codifique myapp://: Flavors, prefixos e peculiaridades do Android com barra tripla são tratados centralmente - strings codificadas quebram entre staging e produção.
Deixe o Expo Router mapear caminhos de arquivo para URLs ao usar roteamento baseado em arquivos: app/orders/[id].tsx já lida com /orders/:id - parsers manuais duplicados se desviam dos arquivos de rota e rotas tipadas.
Centralize o tratamento de URLs de entrada em um único hook raiz: Cold start (getInitialURL), warm start (addEventListener), toques de push e primeira abertura adiada devem convergir em uma única função de navegação validada - dispersão causa pushes duplicados.
Controle a navegação de deep link com base em authReady e conclusão do onboarding: Telas protegidas que montam antes da restauração da sessão exibem dados e perdem URLs de retorno - enfileire a intenção até que o bootstrap termine.
Valide parâmetros de rota com Zod na fronteira de vinculação: Deep links são entradas não confiáveis - valores de id malformados devem router.replace("/") ou uma tela de erro dedicada, não lançar durante a renderização.
Trate parâmetros de consulta como públicos - nunca coloque segredos em URLs: Chaves de consulta token, email e code aparecem em análises, logs e cabeçalhos de referenciador - troque códigos de uso único no lado do servidor após a navegação.
Trate cold start e warm start explicitamente: getInitialURL sozinho perde toques em segundo plano; configurações apenas com listener perdem lançamentos em estado de encerramento - implemente ambos com limpeza e guardas de duplicação.
Use router.replace para magic links e redefinições de senha: Os usuários não devem navegar de volta para pilhas pré-autenticação - transações únicas substituem; conteúdo navegável é empurrado.
Torne as rotas idempotentes: Tocar no mesmo link orders/42 duas vezes não deve corromper a profundidade da pilha - router.push para a mesma tela pode duplicar; considere router.navigate ou deduplique por referência de caminho.
Hospede apple-app-site-association sem redirecionamentos e com application/json: O iOS rejeita AASA redirecionado ou embrulhado em HTML - sirva 200 nos caminhos de ápice e /.well-known/ com TLS válido.
Hospede assetlinks.json com impressões digitais SHA-256 do Play App Signing: Impressões digitais de chave de upload sozinhas falham na verificação em builds distribuídos pelo Play - copie o certificado do Play Console → Integridade do App.
Restrinja pathPrefix e paths do AASA - não reivindique /: Caminhos excessivamente amplos sequestram URLs de blog e admin para o aplicativo - use prefixos explícitos e exclusões NOT.
Execute adb shell pm get-app-links em builds de QA do Android: O status de verificação é determinístico - legacy_failure antes do toque no dispositivo economiza horas de adivinhação.
Teste universal links no TestFlight e em faixas internas - não apenas em simuladores: O iOS armazena em cache o AASA no dispositivo; a passagem no simulador + o fallback do Safari no dispositivo é um falso positivo comum.
Encerre o aplicativo entre os casos de teste de cold-start: QA apenas de warm-start perde o maior segmento de falhas - stopApp: true do Maestro e o encerramento manual antes do toque são obrigatórios.
Coloque dados de roteamento no payload data do push - não apenas título/corpo: Manipuladores de toque de notificação leem content.data - analise tipos discriminados e valide antes de router.push.
Emparelhe o cold start de push com getLastNotificationResponseAsync: Mesmo padrão de getInitialURL - o tratamento de push apenas com listener falha quando o aplicativo foi encerrado.
Planeje deep links adiados sem assumir o referenciador de instalação do iOS: O Android Install Referrer mais IDs de clique do lado do servidor são o padrão de durabilidade de privacidade - SDKs de MMP exigem ATT e divulgações de privacidade ao rastrear entre aplicativos.
Ofereça um fallback da web e um CTA de continuação manual quando o correspondência adiada falhar: 30–50% de falhas de atribuição adiada - aterrissar em um padrão sensato com "Continuar sua oferta?" em vez de uma tela inicial em branco.
Verifique em CI o AASA hospedado e assetlinks.json em cada implantação da web: A hospedagem de JSON falha silenciosamente quando o marketing altera as regras do CDN - crie um script fetch + JSON.parse antes do lançamento nativo.
Teste de contrato de análise de URL no Jest - Maestro não pode cobrir todas as entradas malformadas: Testes unitários para Linking.parse → mapeamento de rota são baratos e bloqueiam %20, ids vazios e tentativas de injeção.
Documente esquemas, domínios e matriz de teste no runbook de lançamento: Deep links tocam em app.config.ts, CDN, payloads de push e autenticação - vincule linhas da matriz P0 a proprietários da lista de verificação de lançamento para que a vinculação não seja uma reflexão tardia no dia da submissão.
expo-linking para createURL, openURL e pré-navegação personalizada.scheme.Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (
expo~57.0.4).
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026