API expo-linking

Q: Quando devo chamar getInitialURL?

Uma vez no início do aplicativo - tipicamente no _layout.tsx raiz ou em um provedor de autenticação. Não o consulte periodicamente - o valor não muda até a próxima inicialização a frio.

Q: Como abro WhatsApp ou Maps do meu aplicativo?

Adicione esquemas de destino a LSApplicationQueriesSchemes no iOS.

Q: Posso usar expo-linking na web?

parse e createURL funcionam na web com origens http/https. getInitialURL retorna a URL da página na primeira carga - controle com Platform.OS !== "web" se estiver compartilhando código.

Q: Como os parâmetros de consulta com chaves duplicadas são analisados?

?tag=a&tag=b resulta em queryParams.tag como string[]. Normalize para uma única string antes da validação.

Q: Links de inicialização aquecida devem usar replace ou push?

Push quando o usuário deve voltar para a tela anterior. Replace para magic links e redefinições de senha - evite voltar para pilhas não autenticadas.

Q: Como registro links sem vazar PII?

Registre apenas o path - remova as chaves de consulta token, email e code antes da análise. Hash de IDs de pedidos se sua política os tratar como sensíveis.

Q: O addEventListener dispara para universal links?

Sim - links https:// verificados disparam o mesmo evento assim que o aplicativo abre. A verificação falha abre o Safari em vez disso - seu JS nunca é executado.

Q: Como testar getInitialURL em Jest?

Mock addEventListener para invocar o callback manualmente em testes de integração.

Análise de URLs, listeners e tratamento de inicialização a frio vs. inicialização aquecida - o cookbook expo-linking para aplicativos Expo SDK 57 que recebem links de e-mail, SMS, códigos QR e outros aplicativos.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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();
  }, []);
}

Quando usar isso:

Análises personalizadas ou atribuição antes que o Expo Router navegue.
Rotas não baseadas em arquivos (tokens de redefinição de senha, magic links).
URLs de retorno OAuth tratadas fora do Router - veja auth-session.
Abrir aplicativos externos (maps://, mailto:) com openURL.
Construir folhas de compartilhamento e links de referência com createURL.

Exemplo de Trabalho

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

O que isso demonstra:

Inicialização a frio via getInitialURL com um ref para evitar tratamento duplo.
Inicialização aquecida via addEventListener com limpeza na desmontagem.
Bloqueio de autenticação - os links esperam até authReady para que rotas protegidas não pisquem.
Validação Zod na fronteira de linking - URLs malformadas retornam para a página inicial.
router.push do Expo Router com pathname e parâmetros dinâmicos.

Mergulho Profundo

Como Funciona

O SO entrega URLs para seu aplicativo através de manipuladores de esquema personalizados ou filtros de intenção HTTPS verificados.
Ao iniciar, a camada nativa enfileira a URL; getInitialURL a lê assim que o JavaScript é iniciado.
Enquanto em execução, novas URLs chegam como eventos no canal url - a mesma forma { url: string }.
O Expo Router registra sua própria configuração de linking de app/ - seu listener é executado em paralelo para efeitos colaterais.
Linking.parse usa o analisador de URL WHATWG - URLs inválidas retornam { path: null, queryParams: null }.

Inicialização a Frio vs. Inicialização Aquecida

Cenário	Estado do App	API	Armadilha
Inicialização a frio	Processo encerrado	`getInitialURL()`	Navegar antes que a autenticação/Router esteja pronto descarta a URL
Inicialização aquecida (em segundo plano)	JS em execução	`addEventListener("url")`	Manipulador duplicado se o layout for remontado sem limpeza
Inicialização aquecida (em primeiro plano)	JS em execução	`addEventListener("url")`	A mesma URL pode disparar duas vezes em alguns OEMs Android
Usuário abriu pelo ícone	Nenhum link	`getInitialURL()` → `null`	Não trate `null` como um erro

Superfície de API Chave

Método / Evento	Retorna	Uso
`Linking.parse(url)`	`{ scheme, hostname, path, queryParams }`	Inspecionar URLs de entrada
`Linking.createURL(path, opts?)`	`string`	Construir links de compartilhamento/referência
`Linking.getInitialURL()`	`Promise<string \| null>`	Inicialização a frio
`Linking.addEventListener("url", fn)`	`Subscription`	Listener de inicialização aquecida
`Linking.openURL(url)`	`Promise<true>`	Abrir aplicativos externos
`Linking.canOpenURL(url)`	`Promise<boolean>`	Verificar se o aplicativo de destino existe
`Linking.getLinkingURL()`	`string \| null`	URL do Expo Go apenas para desenvolvimento (evitar em produção)

Notas 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;
}

Os valores de queryParams podem ser string | string[] - normalize antes da análise Zod.
path omite a barra inicial para esquemas personalizados - normalize antes da concatenação.
Use rotas tipadas router.push quando experiments.typedRoutes estiver habilitado - caminhos inválidos falham em tempo de compilação.

Armadilhas

Tratamento da URL inicial antes da resolução da autenticação - telas protegidas são montadas e, em seguida, redirecionadas, perdendo o contexto do deep link. Correção: controle useAppLinking({ enabled: authReady }) como mostrado acima.
Navegação dupla na inicialização a frio - tanto o Expo Router quanto seu hook enviam a mesma rota. Correção: desative a navegação personalizada quando o linking do Router for suficiente, ou defina initialRouteName explicitamente.
Esquecer a limpeza do listener - o Fast Refresh empilha listeners; um link dispara cinco navegações. Correção: return () => subscription.remove() em useEffect.
Hardcoding de strings myapp:// - quebra entre sabores e Expo Go. Correção: sempre use Linking.createURL("orders/42").
Confiar em parâmetros de consulta para autenticação - ?token= em URLs aparece em análises e logs. Correção: troque tokens no lado do servidor; use códigos de uso único de curta duração em links.
canOpenURL bloqueado no iOS sem LSApplicationQueriesSchemes - sempre retorna false para esquemas não listados. Correção: declare os esquemas consultados em app.config.ts ios.infoPlist.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Apenas linking do Expo Router	Rotas baseadas em arquivos cobrem todos os caminhos	Você precisa de análises pré-navegação ou troca de tokens
Configuração de linking do React Navigation	Aplicativo React Navigation Brownfield	Projeto Expo Router Greenfield
SDK Branch / AppsFlyer	Links profundos adiados + atribuição	Aplicativo simples apenas com esquema personalizado
`Linking.parse` manual em cada tela	Base de código legada	Código novo - centralizar em um único hook

FAQs

O Expo Router substitui o expo-linking?

O Router usa linking nos bastidores para mapeamento de caminhos.
Mantenha expo-linking para createURL, openURL, canOpenURL e lógica personalizada pré-navegação.

Quando devo chamar getInitialURL?

Uma vez no início do aplicativo - tipicamente no _layout.tsx raiz ou em um provedor de autenticação.
Não o consulte periodicamente - o valor não muda até a próxima inicialização a frio.

Por que getInitialURL é null, mas o aplicativo abriu de um link?

Configuração apenas de listener sem manipulador de inicialização a frio.
A navegação ocorreu antes do efeito - controle a splash screen até que o hook de linking seja concluído.
Esquema Expo Go vs. cliente de desenvolvimento incompatível - o link visou o binário errado.

Como abro WhatsApp ou Maps do meu aplicativo?

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

Adicione esquemas de destino a LSApplicationQueriesSchemes no iOS.

Posso usar expo-linking na web?

parse e createURL funcionam na web com origens http/https.
getInitialURL retorna a URL da página na primeira carga - controle com Platform.OS !== "web" se estiver compartilhando código.

Como os parâmetros de consulta com chaves duplicadas são analisados?

?tag=a&tag=b resulta em queryParams.tag como string[].
Normalize para uma única string antes da validação.

Links de inicialização aquecida devem usar replace ou push?

Push quando o usuário deve voltar para a tela anterior.
Replace para magic links e redefinições de senha - evite voltar para pilhas não autenticadas.

Como registro links sem vazar PII?

Registre apenas o path - remova as chaves de consulta token, email e code antes da análise.
Hash de IDs de pedidos se sua política os tratar como sensíveis.

O addEventListener dispara para universal links?

Sim - links https:// verificados disparam o mesmo evento assim que o aplicativo abre.
A verificação falha abre o Safari em vez disso - seu JS nunca é executado.

Como testar getInitialURL em Jest?

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

Mock addEventListener para invocar o callback manualmente em testes de integração.

Relacionado

Noções Básicas de Deep Linking - esquemas, hosts e configuração do Expo
Universal Links do iOS - links HTTPS no iOS
Android App Links - intenções verificadas do Android
Deep Links de Notificação Push - toque → navegue
../expo-router/expo-router-basics/expo-router-basics.md - mapeamento de rotas baseado em arquivos
../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - regras de validação de parâmetros

Versões do Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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();
  }, []);
}

Quando usar isso:

Análises personalizadas ou atribuição antes que o Expo Router navegue.
Rotas não baseadas em arquivos (tokens de redefinição de senha, magic links).
URLs de retorno OAuth tratadas fora do Router - veja auth-session.
Abrir aplicativos externos (maps://, mailto:) com openURL.
Construir folhas de compartilhamento e links de referência com createURL.

Exemplo de Trabalho

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

O que isso demonstra:

Inicialização a frio via getInitialURL com um ref para evitar tratamento duplo.
Inicialização aquecida via addEventListener com limpeza na desmontagem.
Bloqueio de autenticação - os links esperam até authReady para que rotas protegidas não pisquem.
Validação Zod na fronteira de linking - URLs malformadas retornam para a página inicial.
router.push do Expo Router com pathname e parâmetros dinâmicos.

Mergulho Profundo

Como Funciona

O SO entrega URLs para seu aplicativo através de manipuladores de esquema personalizados ou filtros de intenção HTTPS verificados.
Ao iniciar, a camada nativa enfileira a URL; getInitialURL a lê assim que o JavaScript é iniciado.
Enquanto em execução, novas URLs chegam como eventos no canal url - a mesma forma { url: string }.
O Expo Router registra sua própria configuração de linking de app/ - seu listener é executado em paralelo para efeitos colaterais.
Linking.parse usa o analisador de URL WHATWG - URLs inválidas retornam { path: null, queryParams: null }.

Inicialização a Frio vs. Inicialização Aquecida

Cenário	Estado do App	API	Armadilha
Inicialização a frio	Processo encerrado	`getInitialURL()`	Navegar antes que a autenticação/Router esteja pronto descarta a URL
Inicialização aquecida (em segundo plano)	JS em execução	`addEventListener("url")`	Manipulador duplicado se o layout for remontado sem limpeza
Inicialização aquecida (em primeiro plano)	JS em execução	`addEventListener("url")`	A mesma URL pode disparar duas vezes em alguns OEMs Android
Usuário abriu pelo ícone	Nenhum link	`getInitialURL()` → `null`	Não trate `null` como um erro

Superfície de API Chave

Método / Evento	Retorna	Uso
`Linking.parse(url)`	`{ scheme, hostname, path, queryParams }`	Inspecionar URLs de entrada
`Linking.createURL(path, opts?)`	`string`	Construir links de compartilhamento/referência
`Linking.getInitialURL()`	`Promise<string \| null>`	Inicialização a frio
`Linking.addEventListener("url", fn)`	`Subscription`	Listener de inicialização aquecida
`Linking.openURL(url)`	`Promise<true>`	Abrir aplicativos externos
`Linking.canOpenURL(url)`	`Promise<boolean>`	Verificar se o aplicativo de destino existe
`Linking.getLinkingURL()`	`string \| null`	URL do Expo Go apenas para desenvolvimento (evitar em produção)

Notas 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;
}

Os valores de queryParams podem ser string | string[] - normalize antes da análise Zod.
path omite a barra inicial para esquemas personalizados - normalize antes da concatenação.
Use rotas tipadas router.push quando experiments.typedRoutes estiver habilitado - caminhos inválidos falham em tempo de compilação.

Armadilhas

Tratamento da URL inicial antes da resolução da autenticação - telas protegidas são montadas e, em seguida, redirecionadas, perdendo o contexto do deep link. Correção: controle useAppLinking({ enabled: authReady }) como mostrado acima.
Navegação dupla na inicialização a frio - tanto o Expo Router quanto seu hook enviam a mesma rota. Correção: desative a navegação personalizada quando o linking do Router for suficiente, ou defina initialRouteName explicitamente.
Esquecer a limpeza do listener - o Fast Refresh empilha listeners; um link dispara cinco navegações. Correção: return () => subscription.remove() em useEffect.
Hardcoding de strings myapp:// - quebra entre sabores e Expo Go. Correção: sempre use Linking.createURL("orders/42").
Confiar em parâmetros de consulta para autenticação - ?token= em URLs aparece em análises e logs. Correção: troque tokens no lado do servidor; use códigos de uso único de curta duração em links.
canOpenURL bloqueado no iOS sem LSApplicationQueriesSchemes - sempre retorna false para esquemas não listados. Correção: declare os esquemas consultados em app.config.ts ios.infoPlist.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Apenas linking do Expo Router	Rotas baseadas em arquivos cobrem todos os caminhos	Você precisa de análises pré-navegação ou troca de tokens
Configuração de linking do React Navigation	Aplicativo React Navigation Brownfield	Projeto Expo Router Greenfield
SDK Branch / AppsFlyer	Links profundos adiados + atribuição	Aplicativo simples apenas com esquema personalizado
`Linking.parse` manual em cada tela	Base de código legada	Código novo - centralizar em um único hook

FAQs

O Expo Router substitui o expo-linking?

O Router usa linking nos bastidores para mapeamento de caminhos.
Mantenha expo-linking para createURL, openURL, canOpenURL e lógica personalizada pré-navegação.

Quando devo chamar getInitialURL?

Uma vez no início do aplicativo - tipicamente no _layout.tsx raiz ou em um provedor de autenticação.
Não o consulte periodicamente - o valor não muda até a próxima inicialização a frio.

Por que getInitialURL é null, mas o aplicativo abriu de um link?

Configuração apenas de listener sem manipulador de inicialização a frio.
A navegação ocorreu antes do efeito - controle a splash screen até que o hook de linking seja concluído.
Esquema Expo Go vs. cliente de desenvolvimento incompatível - o link visou o binário errado.

Como abro WhatsApp ou Maps do meu aplicativo?

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

Adicione esquemas de destino a LSApplicationQueriesSchemes no iOS.

Posso usar expo-linking na web?

parse e createURL funcionam na web com origens http/https.
getInitialURL retorna a URL da página na primeira carga - controle com Platform.OS !== "web" se estiver compartilhando código.

Como os parâmetros de consulta com chaves duplicadas são analisados?

?tag=a&tag=b resulta em queryParams.tag como string[].
Normalize para uma única string antes da validação.

Links de inicialização aquecida devem usar replace ou push?

Push quando o usuário deve voltar para a tela anterior.
Replace para magic links e redefinições de senha - evite voltar para pilhas não autenticadas.

Como registro links sem vazar PII?

Registre apenas o path - remova as chaves de consulta token, email e code antes da análise.
Hash de IDs de pedidos se sua política os tratar como sensíveis.

O addEventListener dispara para universal links?

Sim - links https:// verificados disparam o mesmo evento assim que o aplicativo abre.
A verificação falha abre o Safari em vez disso - seu JS nunca é executado.

Como testar getInitialURL em Jest?

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

Mock addEventListener para invocar o callback manualmente em testes de integração.

Relacionado

Noções Básicas de Deep Linking - esquemas, hosts e configuração do Expo
Universal Links do iOS - links HTTPS no iOS
Android App Links - intenções verificadas do Android
Deep Links de Notificação Push - toque → navegue
../expo-router/expo-router-basics/expo-router-basics.md - mapeamento de rotas baseado em arquivos
../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - regras de validação de parâmetros

Versões do Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

API expo-linking

Buscar na documentação

API expo-linking