API expo-linking

Análisis de URLs, listeners y manejo de inicio en frío vs inicio en caliente - el manual de expo-linking para aplicaciones de Expo SDK 57 que reciben enlaces desde correo electrónico, SMS, códigos QR y otras aplicaciones.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

import * as Linking from "expo-linking";
import { useEffect } from "react";
import { router } from "expo-router";
 
function routeFromUrl(url: string) {
  const { path, queryParams } = Linking.parse(url);
  const cleanPath = `/${(path ?? "").replace(/^\/+/, "")}`;
  router.push({ pathname: cleanPath as never, params: queryParams ?? {} });
}
 
export function useDeepLinkBootstrap() {
  useEffect(() => {
    Linking.getInitialURL().then((url) => {
      if (url) routeFromUrl(url);
    });
 
    const sub = Linking.addEventListener("url", ({ url }) => routeFromUrl(url));
    return () => sub.remove();
  }, []);
}

Cuándo usarlo:

• Analytics personalizado o atribución antes de que Expo Router navegue.
• Rutas no basadas en archivos (tokens de restablecimiento de contraseña, enlaces mágicos).
• URLs de retorno de OAuth manejadas fuera de Router - ver auth-session.
• Abrir aplicaciones externas (maps://, mailto:) con openURL.
• Construir hojas de compartir y enlaces de referencia con createURL.

Ejemplo funcional

// src/linking/useAppLinking.ts
import * as Linking from "expo-linking";
import { router } from "expo-router";
import { useEffect, useRef } from "react";
import { z } from "zod";
 
const orderParams = z.object({
  id: z.string().min(1),
  ref: z.string().optional(),
});
 
function navigateFromUrl(url: string) {
  const parsed = Linking.parse(url);
  const segments = (parsed.path ?? "").split("/").filter(Boolean);
 
  if (segments[0] === "orders" && segments[1]) {
    const result = orderParams.safeParse({
      id: segments[1],
      ref: parsed.queryParams?.ref,
    });
 
    if (!result.success) {
      router.replace("/");
      return;
    }
 
    router.push({
      pathname: "/orders/[id]",
      params: { id: result.data.id, ref: result.data.ref ?? "" },
    });
    return;
  }
 
  router.replace("/");
}
 
type Options = {
  enabled: boolean;
};
 
export function useAppLinking({ enabled }: Options) {
  const handledInitial = useRef(false);
 
  useEffect(() => {
    if (!enabled) return;
 
    Linking.getInitialURL().then((url) => {
      if (!url || handledInitial.current) return;
      handledInitial.current = true;
      navigateFromUrl(url);
    });
 
    const subscription = Linking.addEventListener("url", ({ url }) => {
      navigateFromUrl(url);
    });
 
    return () => subscription.remove();
  }, [enabled]);
}

// app/_layout.tsx
import { Stack } from "expo-router";
import { useAppLinking } from "../src/linking/useAppLinking";
import { useAuthReady } from "../src/auth/useAuthReady";
 
export default function RootLayout() {
  const authReady = useAuthReady();
 
  useAppLinking({ enabled: authReady });
 
  return (
    <Stack>
      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
      <Stack.Screen name="orders/[id]" options={{ title: "Order" }} />
    </Stack>
  );
}

Lo que esto demuestra:

• Inicio en frío mediante getInitialURL con una guardia ref contra el manejo duplicado.
• Inicio en caliente mediante addEventListener con limpieza al desmontar.
• Cierre de autenticación - los enlaces esperan hasta que authReady para que las rutas protegidas no parpadeen.
• Validación con Zod en el límite del enlace - las URLs mal formadas regresan al inicio.
• Expo Router router.push con pathname dinámico y params.

Profundización

Cómo funciona

• El SO entrega URLs a tu aplicación a través de manejadores de esquemas personalizados o filtros de intención HTTPS verificados.
• Al iniciar, la capa nativa pone en cola la URL; getInitialURL la lee una vez que JavaScript comienza.
• Mientras se ejecuta, las nuevas URLs llegan como eventos en el canal url - la misma forma { url: string }.
• Expo Router registra su propia configuración de enlace desde app/ - tu listener se ejecuta en paralelo para efectos secundarios.
• Linking.parse utiliza el analizador de URL WHATWG - las URLs no válidas devuelven { path: null, queryParams: null }.

Inicio en frío vs inicio en caliente

Superficie de API clave

Notas de TypeScript

import * as Linking from "expo-linking";
 
type ParsedLink = ReturnType<typeof Linking.parse>;
 
function queryParam(
  parsed: ParsedLink,
  key: string
): string | undefined {
  const value = parsed.queryParams?.[key];
  return Array.isArray(value) ? value[0] : value;
}

• Los valores de queryParams pueden ser string | string[] - normaliza antes del análisis con Zod.
• path omite la barra inclinada inicial para esquemas personalizados - normaliza antes de la concatenación.
• Usa rutas tipadas router.push cuando experiments.typedRoutes está habilitado - las rutas no válidas fallan en tiempo de compilación.

Errores comunes

• Manejo de URL inicial antes de que se resuelva la autenticación - las pantallas protegidas se montan, luego se redirigen, perdiendo el contexto del enlace profundo. Solución: cierra useAppLinking({ enabled: authReady }) como se muestra arriba.
• Doble navegación al iniciar en frío - tanto Expo Router como tu hook empujan la misma ruta. Solución: desactiva la navegación personalizada cuando Router linking es suficiente, o establece initialRouteName explícitamente.
• Olvidar limpieza del listener - Fast Refresh apila listeners; un enlace dispara cinco navegaciones. Solución: return () => subscription.remove() en useEffect.
• Codificar cadenas myapp:// de forma rígida - rompe entre sabores y Expo Go. Solución: siempre usa Linking.createURL("orders/42").
• Confiar en query params para autenticación - ?token= en URLs aterrizaba en analytics y logs. Solución: intercambia tokens del lado del servidor; usa códigos de una sola vez de corta duración en enlaces.
• canOpenURL bloqueado en iOS sin LSApplicationQueriesSchemes - siempre devuelve false para esquemas no listados. Solución: declara esquemas consultados en app.config.ts ios.infoPlist.

Alternativas

Preguntas frecuentes

const url = "maps://?q=Coffee+Shop";
if (await Linking.canOpenURL(url)) {
  await Linking.openURL(url);
}

jest.spyOn(Linking, "getInitialURL").mockResolvedValue("shopapp://orders/1");

Relacionado

• Conceptos básicos de enlaces profundos - esquemas, hosts y configuración de Expo
• Enlaces universales de iOS - enlaces HTTPS en iOS
• Enlaces de aplicaciones de Android - intenciones verificadas de Android
• Enlaces profundos de notificaciones push - toca - navega
• ../expo-router/expo-router-basics/expo-router-basics.md - mapeo de rutas basadas en archivos
• ../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - reglas de validación de parámetros

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