Noções Básicas de Deep Linking

10 exemplos para configurar esquemas personalizados, links universais e a configuração do Expo - a base que todo app SDK 57 precisa antes de direcionar usuários de e-mail, SMS, códigos QR ou notificações push para a tela correta.

Pré-requisitos

Crie um aplicativo Expo com roteamento baseado em arquivos e instale os primitivos de linking:

npx create-expo-app@latest DeepLinkBasics --template tabs
cd DeepLinkBasics
npx expo install expo-linking expo-router

Confirme o pin do SDK:

{
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0",
    "expo-router": "~6.0.0"
  }
}

Ferramentas: Estes exemplos visam Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3.

Exemplos Básicos

1. Esquema Personalizado vs Link HTTPS

Deep links móveis chegam em duas formas. Escolha com base se você precisa de roteamento HTTPS verificado ou um caminho rápido apenas para desenvolvimento.

┌──────────────────────────────────────────────────────────────────────────┐
│ Tipo              │ URL de Exemplo                 │ Abre sem prompt      │
├───────────────────┼────────────────────────────────┼──────────────────────┤
│ Esquema personalizado │ myapp://orders/42              │ Sim (se o app estiver instalado) │
│ Universal/App Link│ https://shop.example.com/o/42  │ Sim (quando verificado) │
│ Fallback da Web   │ https://shop.example.com/o/42  │ Navegador (sem app)  │
└──────────────────────────────────────────────────────────────────────────┘

• Esquemas personalizados são os mais rápidos para enviar - registre scheme em app.config.ts e manipule caminhos no código
• Links Universais/Links de Aplicativo exigem arquivos de verificação hospedados no servidor, mas parecem nativos - sem folha de desambiguação no iOS
• E-mails de marketing e posts sociais devem preferir links HTTPS com fallbacks da web para usuários sem o app
• Redirecionamentos OAuth e ferramentas de desenvolvimento geralmente usam esquemas personalizados - veja ../auth-session/expo-auth-session-and-oauth/expo-auth-session-and-oauth.md

Relacionado: Links Universais do iOS - configuração de apple-app-site-association | Links de Aplicativo do Android - verificação de assetlinks.json

2. Registrar um Esquema Personalizado em app.config.ts

A propriedade scheme informa ao iOS e Android qual prefixo de URL pertence ao seu aplicativo.

// app.config.ts
import type { ExpoConfig } from "expo/config";
 
const config: ExpoConfig = {
  name: "ShopApp",
  slug: "shop-app",
  scheme: "shopapp",
  ios: {
    bundleIdentifier: "com.example.shopapp",
  },
  android: {
    package: "com.example.shopapp",
  },
};
 
export default config;

• Um único esquema em minúsculas (shopapp) produz URLs como shopapp://orders/42
• Múltiplos esquemas usam um array: scheme: ["shopapp", "com.example.shopapp"]
• Reconstrua os binários nativos após alterar scheme - atualizações OTA não podem adicionar novos manipuladores de URL
• Combine strings de esquema em consoles OAuth, modelos de e-mail e códigos QR - erros de digitação causam falhas silenciosas

Relacionado: ../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - regras de esquema e domínio para revisão

3. Criar Links de Saída com createURL

expo-linking gera URLs que respeitam seu esquema configurado e um prefixo de caminho opcional.

import * as Linking from "expo-linking";
 
const orderUrl = Linking.createURL("orders/42", {
  queryParams: { ref: "email" },
});
 
// Dev client / production: shopapp://orders/42?ref=email

• createURL adiciona o esquema do app e normaliza barras - prefira-o à concatenação de strings
• Passe isTripleSlashed: true apenas ao integrar com filtros de intenção Android legados
• Compartilhe links de fluxos de "Convidar amigo" no app usando createURL para que dev e prod permaneçam consistentes
• Registre orderUrl em __DEV__ para copiar em fluxos do Maestro e planilhas de marketing

Relacionado: API do expo-linking - analisando URLs de entrada e ouvintes de eventos

4. Analisar uma URL de Entrada

Quando um link abre seu aplicativo, analise-o em partes estruturadas antes de navegar.

import * as Linking from "expo-linking";
 
function handleDeepLink(url: string) {
  const parsed = Linking.parse(url);
 
  // shopapp://orders/42?ref=email
  // parsed.path        → "orders/42"
  // parsed.queryParams → { ref: "email" }
  // parsed.hostname    → null (custom scheme)
 
  const segments = (parsed.path ?? "").split("/").filter(Boolean);
  const [screen, id] = segments;
 
  if (screen === "orders" && id) {
    // router.push(`/orders/${id}`);
  }
}

• Linking.parse lida com esquemas personalizados e URLs https:// - o hostname é definido para links universais
• Remova barras iniciais de path antes de dividir - Android e iOS às vezes diferem em barras finais
• Nunca confie em parâmetros de consulta para autorização - valide IDs no lado do servidor antes de exibir dados confidenciais
• Com o Expo Router, prefira rotas baseadas em arquivos em vez de análise manual - o Router mapeia caminhos automaticamente

Relacionado: ../expo-router/expo-router-basics/expo-router-basics.md - caminhos de arquivo se tornam segmentos de URL

5. Ouvir Links Enquanto o App Está Aberto (Início Quente)

Links de início quente chegam enquanto o JavaScript já está em execução - assine em um layout raiz.

import * as Linking from "expo-linking";
import { useEffect } from "react";
 
export function useDeepLinkListener(onUrl: (url: string) => void) {
  useEffect(() => {
    const subscription = Linking.addEventListener("url", ({ url }) => {
      onUrl(url);
    });
 
    return () => subscription.remove();
  }, [onUrl]);
}

• addEventListener("url") é acionado quando o usuário toca em um link e o app está em primeiro plano ou plano de fundo
• Retorne subscription.remove() na limpeza do efeito - vazamentos causam navegações duplicadas após o fast refresh
• Use debounce para eventos duplicados rápidos - alguns OEMs disparam o listener duas vezes no Android
• Emparelhe com o linking integrado do Expo Router - adicione apenas listeners personalizados para análises ou URLs não de rota

Relacionado: API do expo-linking - tratamento de cold-start vs warm-start

6. Manipular Links de Cold-Start no Lançamento

Links de cold-start abrem o app de um estado encerrado - leia a URL inicial uma vez antes de renderizar as rotas.

import * as Linking from "expo-linking";
import { useEffect, useState } from "react";
 
export function useInitialDeepLink() {
  const [initialUrl, setInitialUrl] = useState<string | null>(null);
  const [ready, setReady] = useState(false);
 
  useEffect(() => {
    Linking.getInitialURL()
      .then((url) => setInitialUrl(url))
      .finally(() => setReady(true));
  }, []);
 
  return { initialUrl, ready };
}

• getInitialURL retorna o link que iniciou o app, ou null se aberto da tela inicial
• Controle o ocultamento da splash screen em ready - navegar antes que o Router monte descarta a URL inicial
• Chame getInitialURL uma vez na inicialização - aberturas subsequentes usam o listener de eventos
• O Expo Router lê a URL inicial automaticamente quando scheme é configurado - hooks personalizados são para efeitos colaterais

Relacionado: API do expo-linking - padrão completo de bootstrap cold + warm

7. Mapear Rotas de Arquivo para Caminhos de URL (Expo Router)

O Expo Router transforma seu diretório app/ em uma árvore de URLs - deep links mapeiam para telas sem configuração manual.

app/
  (tabs)/
    index.tsx          → /
    orders/
      index.tsx        → /orders
      [id].tsx         → /orders/:id
  product/
    [slug].tsx         → /product/:slug

// app/orders/[id].tsx
import { useLocalSearchParams } from "expo-router";
import { Text, View } from "react-native";
 
export default function OrderDetailScreen() {
  const { id } = useLocalSearchParams<{ id: string }>();
 
  return (
    <View>
      <Text>Order {id}</Text>
    </View>
  );
}

• Segmentos dinâmicos ([id].tsx) se tornam parâmetros de URL - shopapp://orders/42 chega em OrderDetailScreen
• Grupos de rotas (tabs) não aparecem na URL - mantém as URLs das abas limpas
• Valide id com Zod na borda da tela - deep links malformados devem mostrar um fallback, não falhar
• Rotas tipadas (experiments.typedRoutes) capturam href inválidos no tempo de compilação

Relacionado: ../expo-router/link-and-href/link-and-href.md - objetos Link e href

8. Declarar um Host Web para Links Universais

Deep links HTTPS precisam de uma associação de domínio - adicione associatedDomains (iOS) e intentFilters (Android) via plugins de configuração ou app.config.ts.

// app.config.ts
const config = {
  expo: {
    name: "ShopApp",
    slug: "shop-app",
    scheme: "shopapp",
    ios: {
      bundleIdentifier: "com.example.shopapp",
      associatedDomains: ["applinks:shop.example.com"],
    },
    android: {
      package: "com.example.shopapp",
      intentFilters: [
        {
          action: "VIEW",
          autoVerify: true,
          data: [
            {
              scheme: "https",
              host: "shop.example.com",
              pathPrefix: "/orders",
            },
          ],
          category: ["BROWSABLE", "DEFAULT"],
        },
      ],
    },
  },
};
 
export default config;

• Prefixo applinks: no iOS diz ao sistema para buscar apple-app-site-association do seu CDN
• autoVerify: true no Android aciona a verificação de Digital Asset Links no momento da instalação
• Hospede apenas os caminhos que seu app possui - /orders, /product, não a raiz inteira do site de marketing, a menos que pretendido
• Alterações exigem uma nova build nativa - verifique em TestFlight e trilhas internas antes do lançamento amplo

Relacionado: Links Universais do iOS - formato do arquivo AASA e cabeçalhos CDN

9. Testar um Esquema Personalizado do Terminal

Use npx uri-scheme para disparar links em simuladores e dispositivos conectados sem reconstruir páginas de marketing.

# Simulador iOS
npx uri-scheme open "shopapp://orders/42?ref=cli" --ios
 
# Emulador / dispositivo Android
npx uri-scheme open "shopapp://orders/42?ref=cli" --android

• Instale uri-scheme globalmente ou use npx - nenhuma alteração no código do app é necessária
• Teste o cold start encerrando o app primeiro, depois executando o comando
• Teste o warm start com o app em segundo plano - confirma o caminho do listener de eventos
• Links universais precisam do Safari/Chrome ou xcrun simctl openurl com https:// - veja Matriz de Teste de Deep Link

Relacionado: Matriz de Teste de Deep Link - cobertura de simulador, dispositivo e CI

10. Fornecer um Fallback da Web para Usuários Sem o App

Deep links devem degradar para o seu site de marketing ou loja de aplicativos - nunca uma página de erro em branco.

<!-- Hospedado em https://shop.example.com/orders/42 -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Order 42 - ShopApp</title>
    <meta name="apple-itunes-app" content="app-id=123456789, app-argument=https://shop.example.com/orders/42" />
    <script>
      const isIOS = /iPhone|iPad|iPod/i.test(navigator.userAgent);
      const isAndroid = /Android/i.test(navigator.userAgent);
      if (isIOS || isAndroid) {
        window.location = "shopapp://orders/42";
        setTimeout(() => {
          window.location = isIOS
            ? "https://apps.apple.com/app/id123456789"
            : "https://play.google.com/store/apps/details?id=com.example.shopapp";
        }, 1500);
      }
    </script>
  </head>
  <body>
    <p>Abrindo ShopApp… <a href="https://shop.example.com/orders/42">Ver no navegador</a></p>
  </body>
</html>

• Smart banners (apple-itunes-app) melhoram o handoff web-para-app do iOS quando links universais ainda não foram verificados
• Timeout de fallback evita que usuários fiquem olhando para uma página em branco quando o app não está instalado
• Deep links adiados (instalação → primeira abertura) precisam de SDKs de atribuição ou encanamento de install-referrer personalizado - veja Deep Links Adiados
• Mantenha os caminhos da web e do app alinhados - /orders/42 deve significar a mesma entidade em ambas as superfícies

Relacionado: Deep Links Adiados - atribuição após instalação nova

Exemplos Intermediários

11. Prefixo de Caminhos para Staging vs Produção

Use prefixos de caminho do expo-linking quando vários sabores de build compartilham um esquema, mas com raízes de rota diferentes.

import Constants from "expo-constants";
import * as Linking from "expo-linking";
 
const prefix = Constants.expoConfig?.extra?.linkingPrefix ?? "";
 
export function appPath(route: string) {
  return Linking.createURL(`${prefix}${route}`);
}
 
// Staging extra: linkingPrefix = "staging/"
// → shopapp://staging/orders/42

• Prefixos específicos de sabor isolam links de deep link de staging das análises de produção
• Documente as regras de prefixo em planilhas de UTM de marketing - confundir links de staging e prod distorce a atribuição
• O Expo Router suporta a configuração linking com prefixos em configurações avançadas do expo-router - mantenha uma única fonte de verdade

Relacionado: Deep Links de Notificação Push - incorporando caminhos em payloads de notificação

FAQs

Relacionado

• API do expo-linking - analisar, ouvir e inicializar cold starts
• Links Universais do iOS - domínios associados e AASA
• Links de Aplicativo do Android - filtros de intenção e links verificados
• Matriz de Teste de Deep Link - matriz de simulador, dispositivo e CI
• ../expo-router/expo-router-basics/expo-router-basics.md - fundamentos de roteamento baseado em arquivos
• ../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - convenções de roteamento da equipe

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).