Deep links no iOS e no Android: um guia prático

Um deep link é uma URL que abre uma tela específica dentro de um app instalado, em vez de uma página web. A ideia é essa, e ela já foi implementada de três maneiras diferentes ao longo de quinze anos, cada uma com seus próprios modos de falha. O motivo pelo qual os times de marketing não param de abrir chamados sobre isso é que as três ainda coexistem, e a mesma URL pode se comportar de formas diferentes conforme tenha sido tocada em uma mensagem, em um navegador, em um cliente de e-mail ou em uma webview embutida dentro de um app social.

Este guia explica os mecanismos com honestidade, inclusive o que eles não conseguem fazer. Se você levar só uma coisa daqui, que seja esta: rotear um clique até a tela certa de um app é infraestrutura resolvida, e levar um usuário à tela certa depois que ele instala o app não é, pelo menos não a partir da plataforma de links sozinha.

As três gerações de links para apps

Esquemas de URL próprios

O mecanismo original. Um app registra um esquema como myapp, e uma URL como myapp://product/42 entrega a requisição a ele. Esquemas são triviais de implementar e continuam úteis como formato interno de roteamento, mas carregam dois problemas estruturais.

Não há verificação de propriedade: qualquer app pode registrar qualquer esquema e, quando dois apps reivindicam o mesmo, a resolução é indefinida no iOS e vira uma caixa de diálogo de escolha no Android. E não há alternativa: em um dispositivo sem o app instalado, uma URL de esquema produz uma página de erro ou simplesmente nada, então todo link de esquema precisa de um invólucro que detecte a falha e mande o usuário para algum lugar útil. Esse invólucro é exatamente a peça frágil que quebrou quando os navegadores endureceram o tratamento de temporizadores de navegação.

Universal Links no iOS

A substituição criada pela Apple usa URLs HTTPS comuns. Seu app declara um entitlement de domínio associado na forma applinks:yourbrand.com, e o domínio publica um arquivo JSON em /.well-known/apple-app-site-association descrevendo quais caminhos pertencem ao app.

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.yourbrand.app"],
        "components": [{ "/": "/p/*", "comment": "Product pages" }]
      }
    ]
  }
}

O arquivo precisa ser servido por HTTPS, sem redirecionamentos, como JSON, exatamente nesse caminho. O iOS o busca por volta do momento da instalação e da atualização, em boa parte através da CDN da Apple, o que significa que mudanças não entram em vigor instantaneamente. A vantagem é que a mesma URL funciona em todo lugar: se o app está instalado e o caminho corresponde, ele abre; se não, o Safari carrega a página web. Não existe estado de erro.

App Links no Android

O equivalente do Android usa um arquivo Digital Asset Links em /.well-known/assetlinks.json, nomeando o pacote do app e o fingerprint SHA-256 do certificado de assinatura.

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.yourbrand.app",
      "sha256_cert_fingerprints": ["A1:B2:C3:D4:E5:F6:..."]
    }
  }
]

Do lado do app, declara-se um intent filter para o domínio com a verificação automática ativada. Quando a verificação passa, o link abre o app sem nenhuma caixa de diálogo de escolha. Quando ela falha, o link abre o navegador, e a causa mais comum, de longe, é uma divergência de fingerprint: os times publicam o fingerprint da chave de release local enquanto o Play App Signing reassina o app com outra. O fingerprint que deve estar no arquivo é o que a loja mostra para o artefato distribuído.

Como um link curto escolhe seu destino

Um link curto é um ponto de decisão, e não um ponteiro fixo, e é isso que o torna útil em campanhas de app: um único código impresso pode atender usuários de iPhone, usuários de Android e visitantes de desktop de formas diferentes, e a decisão pode mudar depois que o código já foi impresso.

O mecanismo de redirecionamento vê o user agent da requisição, os client hints que ela carrega e sinais derivados da rede, como o país. Um link configurado para tráfego de app costuma guardar três destinos: uma URL iOS, uma URL Android e uma URL web usada para todo o resto. Por cima disso, as regras de segmentação podem rotear por país, dispositivo, sistema operacional ou idioma, de modo que uma campanha consegue mandar o tráfego Android do Canadá para um destino e todo o resto para outro sem criar links separados.

Dois detalhes de implementação valem ser conhecidos, porque explicam a maior parte dos comportamentos confusos.

O primeiro são os crawlers sociais. Quando um bot como o buscador do Facebook ou do Telegram requisita um link para montar um card de prévia, um mecanismo de redirecionamento correto responde com os metadados da prévia, em vez de contar a requisição como clique e em vez de roteá-la como se fosse um celular. Se as suas contagens de cliques disparam no instante em que um link é publicado, antes de alguém tocá-lo, o mecanismo não está fazendo isso.

O segundo é a fronteira da associação, e este é o ponto técnico mais importante de todo o artigo. Os Universal Links são avaliados contra o domínio da URL que o usuário de fato tocou. Se alguém toca go.yourbrand.com/p/42 e esse domínio responde com um redirecionamento para yourbrand.com/p/42, o iOS não trata o alvo do redirecionamento como um link associado, então o app não abre. Para que um link curto abra o app nativamente, o arquivo de associação precisa ser servido no próprio domínio curto. Onde isso não é possível, a saída prática é uma passagem para um esquema próprio ou direto para a loja, que é o que a maioria das funções de deep link dos encurtadores realmente faz. Pergunte a qualquer fornecedor qual das duas ele implementa, porque o texto de marketing é idêntico nos dois casos.

A cadeia de alternativas

Um link de app que funciona é, na prática, uma pequena árvore de decisão, e cada ramo precisa de uma resposta deliberada.

| Situação | O que deveria acontecer | Erro comum | | --- | --- | --- | | App instalado, caminho reconhecido | O app abre na tela de destino | A cadeia de redirecionamentos quebra a associação | | App instalado, caminho não reconhecido | A página web carrega, com o app sugerido | Caixa de diálogo de escolha a cada toque | | App não instalado, mobile | Página da loja da plataforma correta | Link de loja fixado em uma única plataforma | | Desktop | Equivalente web completo da tela | Cair em uma home genérica | | Crawler social | Metadados de prévia, sem contar clique | A busca de prévia infla o analytics |

Aponte o ramo da loja para a ficha adequada a cada plataforma, e não para um link único, e mantenha o ramo web genuinamente equivalente à tela do app. Uma fatia grande do tráfego de campanhas de app termina no ramo web por melhor que o resto esteja configurado, e tratá-lo como beco sem saída desperdiça a maior parte da verba.

A fronteira da instalação, sem rodeios

É aqui que o marketing dos fornecedores e a realidade se separam. Suponha que um usuário novo toque um link para um produto específico, não tenha o app, caia na loja, instale e abra. O app agora mostra a tela inicial padrão, porque nada levou o identificador do produto através da instalação. Fazer isso funcionar se chama deferred deep linking, e não é algo que uma plataforma de links consiga fazer por conta própria.

Isso exige um SDK dentro do app que, na primeira abertura, pergunte a um servidor o que o usuário tocou antes de instalar. O servidor precisa casar os dois eventos, e os sinais disponíveis para esse pareamento encolheram bruscamente. O fingerprinting de dispositivo é pouco confiável e cada vez mais restrito pela política das plataformas. Identificadores de publicidade exigem um consentimento que a maioria dos usuários recusa. Os frameworks de atribuição da Apple reportam atribuição no nível da instalação para os anunciantes, em vez de repassar um caminho ao seu app. A técnica da área de transferência, que um dia carregou um token, hoje dispara uma notificação visível de colagem.

O que resta funciona, mas é outro produto, com outro custo de integração: um SDK de mobile measurement partner, inicialização dentro do app e uma janela de pareamento probabilística, e não exata. O LinkProfit roteia cliques por dispositivo e faz a passagem para a loja, e não afirma fazer roteamento pós-instalação, porque fazer isso direito significa embarcar código dentro do seu app. Se o roteamento diferido for um requisito inegociável, planeje esse SDK ao lado da sua plataforma de links, e não no lugar dela.

Webviews e outras armadilhas práticas

Navegadores embutidos em apps

A maioria dos links tocados dentro de apps sociais abre em uma webview embutida, e não no navegador do sistema, e as webviews tratam a associação com apps de forma inconsistente: algumas ignoram os Universal Links, algumas bloqueiam esquemas próprios, e o comportamento varia entre versões do app. Esse é o motivo mais comum para um link que funciona perfeitamente nos testes abrir o site em produção, já que o teste costuma ser feito tocando um link em um app de mensagens, que se comporta corretamente.

Não existe configuração que resolva isso globalmente. O que funciona é fazer um destino web bom, acrescentar nele um controle visível de abrir no app e testar cada canal de publicação individualmente, em vez de supor que todos se comportam igual.

Erros no arquivo de associação

Quatro deles são recorrentes. Servir o arquivo de associação através de um redirecionamento, incluindo o redirecionamento automático do apex para www, o que o invalida. Servi-lo com o content type errado ou a partir de um caminho que um framework reescreve. Publicar o fingerprint de assinatura errado no Android, como descrito acima. E esquecer que o iOS mantém o arquivo em cache, de modo que uma correção pode levar um dia ou mais para chegar aos dispositivos que já têm o app instalado.

Analytics no ramo do app

Assim que um clique entra em um app, o seu analytics de site deixa de enxergá-lo, e é aqui que os relatórios desmoronam em silêncio. Mantenha os parâmetros de campanha no link para que o mecanismo de redirecionamento os registre, e repasse um identificador ao destino no app para que a sessão dentro do app possa ser ligada ao clique. O nosso guia sobre rastrear cliques em links cobre o que um evento de clique consegue e não consegue revelar, e as mesmas ressalvas sobre bots e visitantes únicos valem aqui.

Testar antes de publicar

curl -sSI https://yourbrand.com/.well-known/apple-app-site-association
curl -sS https://yourbrand.com/.well-known/assetlinks.json

# Android: open a URL as if it were tapped, then inspect verification state
adb shell am start -a android.intent.action.VIEW -d "https://yourbrand.com/p/42"
adb shell pm get-app-links com.yourbrand.app

# iOS simulator
xcrun simctl openurl booted "https://yourbrand.com/p/42"

Os dois primeiros comandos devem retornar 200 sem redirecionamento. Repare que digitar um Universal Link na barra de endereços do Safari deliberadamente não abre o app, então teste a partir de uma nota, de uma mensagem ou do comando do simulador; caso contrário, você vai caçar um bug que não existe.

O que as plataformas de links de fato incluem

O suporte a deep links é empacotado de formas bem diferentes na categoria, e as diferenças são sobre qual plano você precisa comprar, e não sobre capacidade.

| Fornecedor | Disponibilidade de deep links, em agosto de 2026 | | --- | --- | | BL.INK | Todos os planos, nível de entrada a 48 USD por mês para um usuário e um domínio | | Short.io | A partir do plano Team, por 48 USD por mês | | Rebrandly | A partir do plano Growth, de 99 a 119 USD por mês | | Switchy | Cobertura anunciada de mais de 130 apps | | LinkProfit | Destinos por dispositivo em todos os planos |

O BL.INK é a referência honesta aqui: incluir deep links em todos os níveis é incomum, mesmo que o preço de entrada seja alto para um único domínio. O posicionamento do Rebrandly no Growth é o padrão a observar de modo geral, já que o nível de que você precisa por causa de um único recurso tende a determinar a conta inteira.

Uma sequência de implantação que funciona

1. Defina a URL web canônica de cada tela do app para a qual você quer apontar links; a página web é a alternativa e a fonte da verdade.
2. Publique os dois arquivos de associação no domínio que vai aparecer nos links, e verifique-os por HTTPS, sem redirecionamentos.
3. Adicione o entitlement de domínio associado no iOS e o intent filter verificado no Android, usando o fingerprint do build distribuído.
4. Confirme em qual domínio os seus links curtos serão tocados, e se a associação mora ali ou se a plataforma faz a passagem para um esquema ou para a loja.
5. Configure destinos por dispositivo mais uma alternativa web em cada link, com a ficha de loja correta para cada plataforma.
6. Teste nas duas plataformas a partir de um app de mensagens, do navegador do sistema e de cada app social em que você publica.
7. Verifique se os parâmetros de campanha sobrevivem ao redirecionamento e são registrados no analytics.
8. Automatize a criação pela API se os links forem gerados por campanha, por destinatário ou por produto.

Nada disso é difícil isoladamente. A dificuldade é que as peças moram em três lugares, o projeto do app, a zona DNS e a plataforma de links, normalmente sob a responsabilidade de três pessoas diferentes. Deixar escrito quem é o dono do arquivo de associação vale mais do que qualquer dica isolada de configuração deste artigo.