Conceptos Básicos de Deep Linking

10 ejemplos para cablear esquemas personalizados, enlaces universales e integración de Expo - la base que toda app SDK 57 necesita antes de enrutar usuarios desde email, SMS, códigos QR o notificaciones push a la pantalla correcta.

Requisitos Previos

Crea un proyecto de Expo con enrutamiento basado en archivos e instala los primitivos de linking:

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

Confirma la versión de SDK:

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

Herramientas: Estos ejemplos tienen como objetivo Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 y React 19.2.3.

Ejemplos Básicos

1. Esquema Personalizado vs Enlace HTTPS

Los enlaces profundos para móviles llegan en dos formas. Elige según si necesitas enrutamiento HTTPS verificado o un camino solo para desarrollo rápido.

┌──────────────────────────────────────────────────────────────────────────┐
│ Tipo                │ URL de ejemplo                 │ Se abre sin solicitud │
├─────────────────────┼────────────────────────────────┼──────────────────────┤
│ Esquema personalizado│ myapp://orders/42              │ Sí (si app está instalada) │
│ Enlace Universal/App │ https://shop.example.com/o/42  │ Sí (cuando está verificado) │
│ Alternativa web     │ https://shop.example.com/o/42  │ Navegador (sin app) │
└──────────────────────────────────────────────────────────────────────────┘

• Los esquemas personalizados son los más rápidos para enviar - registra scheme en app.config.ts y maneja rutas en el código
• Los Enlaces Universales/App Links requieren archivos de verificación alojados en el servidor pero se sienten nativos - sin hoja de desambiguación en iOS
• Los emails de marketing y las publicaciones sociales deberían preferir enlaces HTTPS con alternativas web para usuarios sin la app
• Los redirects de OAuth y las herramientas de desarrollo a menudo usan esquemas personalizados - mira ../auth-session/expo-auth-session-and-oauth/expo-auth-session-and-oauth.md

Relacionado: iOS Universal Links - configuración de apple-app-site-association | Android App Links - verificación de assetlinks.json

2. Registra un Esquema Personalizado en app.config.ts

La propiedad scheme le indica a iOS y Android qué prefijo de URL pertenece a tu app.

// 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;

• Un esquema único en minúsculas (shopapp) produce URLs como shopapp://orders/42
• Múltiples esquemas usan un array: scheme: ["shopapp", "com.example.shopapp"]
• Reconstruye los binarios nativos después de cambiar scheme - las actualizaciones OTA no pueden agregar nuevos manejadores de URL
• Empareja strings de esquema entre consolas OAuth, plantillas de email y códigos QR - los errores tipográficos causan operaciones silenciosas

Relacionado: ../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - reglas de esquema y dominio para revisión

3. Construye Enlaces Salientes con createURL

expo-linking genera URLs que respetan tu esquema configurado y prefijo de ruta opcional.

import * as Linking from "expo-linking";
 
const orderUrl = Linking.createURL("orders/42", {
  queryParams: { ref: "email" },
});
 
// Cliente de desarrollo / producción: shopapp://orders/42?ref=email

• createURL prepone el esquema de la app y normaliza barras - prefiere esto sobre la concatenación de strings
• Pasa isTripleSlashed: true solo cuando integres con filtros de intención de Android heredados
• Comparte enlaces desde flujos de "Invita a un amigo" en la app usando createURL para que dev y prod se mantengan consistentes
• Registra orderUrl en __DEV__ para copiar en flujos de Maestro y hojas de cálculo de marketing

Relacionado: expo-linking API - análisis de URLs entrantes y listeners de eventos

4. Analiza una URL Entrante

Cuando un enlace abre tu app, análizalo en partes estructuradas 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 (esquema personalizado)
 
  const segments = (parsed.path ?? "").split("/").filter(Boolean);
  const [screen, id] = segments;
 
  if (screen === "orders" && id) {
    // router.push(`/orders/${id}`);
  }
}

• Linking.parse maneja tanto esquemas personalizados como URLs https:// - hostname se establece para enlaces universales
• Elimina barras diagonales iniciales de path antes de dividir - Android e iOS a veces difieren en barras finales
• Nunca confíes en parámetros de consulta para autorización - valida IDs en el servidor antes de mostrar datos sensibles
• Con Expo Router, prefiere rutas basadas en archivos sobre análisis manual - Router mapea rutas automáticamente

Relacionado: ../expo-router/expo-router-basics/expo-router-basics.md - las rutas de archivos se convierten en segmentos de URL

5. Escucha Enlaces Mientras la App Está Abierta (Inicio Cálido)

Los enlaces de inicio cálido llegan mientras JavaScript ya se está ejecutando - suscribirse en un layout raíz.

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") se dispara cuando el usuario toca un enlace y la app está en primer plano o fondo
• Retorna subscription.remove() en la limpieza del efecto - los fugas causan navegaciones duplicadas después de actualización rápida
• Debounce eventos duplicados rápidos - algunos OEMs disparan el listener dos veces en Android
• Empareja con el linking integrado de Expo Router - solo agrega listeners personalizados para análisis o URLs que no son rutas

Relacionado: expo-linking API - manejo de inicio en frío vs inicio cálido

6. Maneja Enlaces de Inicio en Frío al Lanzamiento

Los enlaces de inicio en frío abren la app desde un estado eliminado - lee la URL inicial una sola vez antes de renderizar rutas.

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 el enlace que lanzó la app, o null si fue abierta desde la pantalla de inicio
• Cierra la pantalla de splash en ready - navegar antes de que Router se monte deja caer la URL inicial
• Llama a getInitialURL una sola vez al inicio - las aperturas posteriores usan el listener de eventos
• Expo Router lee la URL inicial automáticamente cuando scheme está configurado - los hooks personalizados son para efectos secundarios

Relacionado: expo-linking API - patrón de bootstrap completo de inicio en frío + inicio cálido

7. Mapea Rutas de Archivos a Rutas de URL (Expo Router)

Expo Router convierte tu directorio app/ en un árbol de URL - los enlaces profundos mapean a pantallas sin cableado 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>Pedido {id}</Text>
    </View>
  );
}

• Los segmentos dinámicos ([id].tsx) se convierten en parámetros de URL - shopapp://orders/42 aterriza en OrderDetailScreen
• Los grupos de rutas (tabs) no aparecen en la URL - mantiene las URLs de pestañas limpias
• Valida id con Zod en el límite de la pantalla - los enlaces profundos malformados deberían mostrar un alternativa, no fallar
• Las rutas tipadas (experiments.typedRoutes) atrapan href inválidos en tiempo de compilación

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

8. Declara un Host Web para Enlaces Universales

Los enlaces profundos HTTPS necesitan una asociación de dominio - agrega associatedDomains (iOS) e intentFilters (Android) a través de plugins de configuración o 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;

• El prefijo applinks: en iOS le indica al sistema que traiga apple-app-site-association desde tu CDN
• autoVerify: true en Android dispara verificación de Vínculos de Activos Digitales en tiempo de instalación
• Aloja solo las rutas que tu app posee - /orders, /product, no la raíz del sitio de marketing completo a menos que sea intencional
• Los cambios requieren una nueva compilación nativa - verifica en TestFlight e pistas internas antes de una liberación amplia

Relacionado: iOS Universal Links - formato de archivo AASA y encabezados CDN

9. Prueba un Esquema Personalizado desde la Terminal

Usa npx uri-scheme para disparar enlaces a simuladores y dispositivos conectados sin reconstruir páginas de marketing.

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

• Instala uri-scheme globalmente o usa npx - no se requieren cambios de código de app
• Prueba inicio en frío matando la app primero, luego ejecutando el comando
• Prueba inicio cálido con la app en segundo plano - confirma la ruta del listener de eventos
• Los enlaces universales necesitan Safari/Chrome o xcrun simctl openurl con https:// - mira Matriz de Prueba de Deep Link

Relacionado: Matriz de Prueba de Deep Link - matriz de simulador, dispositivo e CI

10. Proporciona una Alternativa Web para Usuarios Sin la App

Los enlaces profundos deberían degradarse a tu sitio de marketing o app store - nunca una página de error en blanco.

<!-- Alojado en https://shop.example.com/orders/42 -->
<!DOCTYPE html>
<html lang="es">
  <head>
    <meta charset="utf-8" />
    <title>Pedido 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>Abriendo ShopApp… <a href="https://shop.example.com/orders/42">Ver en navegador</a></p>
  </body>
</html>

• Los banners inteligentes (apple-itunes-app) mejoran la transferencia web a app en iOS cuando los enlaces universales aún no están verificados
• El timeout de alternativa previene que los usuarios se queden mirando una página en blanco cuando la app no está instalada
• Los enlaces profundos diferidos (instalación - primer abierta) necesitan SDKs de atribución o plomería personalizada de install-referrer - mira Deferred Deep Links
• Mantén las rutas web y de app alineadas - /orders/42 debería significar la misma entidad en ambas superficies

Relacionado: Deferred Deep Links - atribución después de instalación fresca

Ejemplos Intermedios

11. Rutas de Prefijo para Staging vs Producción

Usa prefijos de ruta de expo-linking cuando múltiples sabores de compilación compartan un esquema pero diferentes raíces de rutas.

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

• Los prefijos específicos del sabor aíslan los enlaces profundos de staging del análisis de producción
• Documenta reglas de prefijo en hojas de cálculo de UTM de marketing - confundir enlaces de staging y prod sesga la atribución
• Expo Router soporta configuración de linking con prefijos en configuraciones avanzadas de expo-router - mantén una fuente única de verdad

Relacionado: Push Notification Deep Links - incrustar rutas en cargas de notificación

Preguntas Frecuentes

Relacionado

• expo-linking API - analiza, escucha e inicia en frío
• iOS Universal Links - dominios asociados y AASA
• Android App Links - filtros de intención y enlaces verificados
• Matriz de Prueba de Deep Link - matriz de simulador, dispositivo e CI
• ../expo-router/expo-router-basics/expo-router-basics.md - fundamentos de enrutamiento basado en archivos
• ../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - convenciones de enrutamiento del equipo

Versiones de Stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0 y Expo SDK 57 (expo ~57.0.4).