Deep links no Android: configuração completa e testes

Um link como https://exemplo.com/produtos/123 costuma abrir o site no navegador. Com deep links no Android, a mesma URL pode abrir diretamente uma tela do aplicativo, como a página de um produto, uma conversa ou um formulário específico.

A configuração envolve partes diferentes: o manifesto do aplicativo, o site que recebe o link, os domínios associados e o comportamento do sistema. Um pequeno erro no filtro de intenção pode fazer o Android abrir o navegador, abrir o aplicativo sem a tela esperada ou exibir uma tela de escolha entre os aplicativos.

Este guia mostra o caminho de implementação, as diferenças entre links diretos e App Links, os principais métodos de validação e os erros que mais aparecem em projetos reais.

Este conteúdo tem caráter informativo. Decisões técnicas devem ser tomadas com profissional especializado.

O que é deep link no Android

Um deep link é um endereço que conduz o usuário a um destino específico dentro de um aplicativo. Em vez de abrir apenas a tela inicial, ele pode apresentar um item, uma seção, um documento ou uma ação que já está identificada na URL.

Um exemplo cotidiano seria um link de confirmação enviado por e-mail. Ao tocar nele, o usuário pode chegar diretamente ao formulário de confirmação no aplicativo, sem precisar procurar a tela correspondente. Em sistemas web, essa mesma lógica costuma aparecer com URLs de rotas, como /conta/pedidos/9854.

No Android, a URL recebida pelo aplicativo pode ser processada por uma Activity, que representa uma tela ou uma tarefa que o usuário executa. A Activity declarada recebe a URL, interpreta seus dados e decide qual conteúdo deve aparecer.

O comportamento final depende de fatores importantes:

• O aplicativo está instalado?
• A URL pode ser verificada no servidor?
• O domínio tem um arquivo de associação válido?
• A intent filter está declarada corretamente?
• O sistema reconhece o aplicativo como um destino confiável para aquele domínio?

Deep links, links diretos e App Links

O Android trabalha com mecanismos que comumente receive nomes parecidos, mas têm comportamentos diferentes. A documentação do Android diferencia os deep links, os links diretos e os App Links.

Na prática, a distinção mais importante é a seguinte:

Intent com dados

Uma intent é uma mensagem que o aplicativo envia ao sistema Android para solicitar uma ação. Ela pode conter uma URL, mas o sistema não sabe previamente qual aplicativo deve tratá-la. O usuário pode precisar escolher o aplicativo ou iniciar a ação diretamente.

Esse formato é útil para ações internas do aplicativo, como abrir um arquivo com um visualizador específico. Ele não deve ser usado para levar o usuário de uma página pública do site a uma tela do aplicativo.

Link direto

O link direto usa um filtro de intenção declarado no manifesto. Qualquer aplicativo com um filtro compatível pode.enter na disputa pelo endereço. Sem uma preferência do sistema, o Android pode abrir uma caixa de seleção com os aplicativos disponíveis.

O Google recomenda que sites e aplicativos usem App Links para abrir links diretamente no aplicativo, especialmente quando a URL é compartilhada, enviada por mensagem ou acessada por um mecanismo de busca.

App Link

App Links é a forma recomendada para conectar um site a um aplicativo Android. O aplicativo declara que pertence a um domínio, e o site publica um arquivo assetlinks.json que comprova essa associação.

A partir dessa validação, o sistema pode abrir o aplicativo diretamente. Quando ele está instalado, a experiência costuma ser mais rápida e previsível.

Para ativar a visualização automática, o usuário ainda pode desativar o aplicativo para esse domínio nas configurações do sistema. Por isso, o site precisa continuar funcionando como alternativa, especialmente em scenarios de SEO, campanhas e compartilhamento de páginas.

Como configurar deep links no Android

A configuração completa envolve a declaração do esquema, a leitura dos parâmetros e a validação do domínio. O exemplo a seguir usa uma URL no formato https://exemplo.com/produtos/123.

1. Definir o destino da URL

Antes de alterar o código, defina qual tela deve receber o link e quais informações são necessárias. Uma estrutura clara evita rotas duplicadas ou comportamentos diferentes entre o site e o aplicativo.

Para o exemplo, considere:

A mesma rota pode ser usada pelo site e pelo aplicativo. Isso mantém a experiência consistente e facilita o compartilhamento.

2. Declarar a Activity e o filtro de intenção

No arquivo AndroidManifest.xml, a Activity responsável pela tela precisa declarar um filtro com android.intent.action.VIEW, a categoria padrão e o esquema da URL.

<activity
    android:name=".ProductActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

Configure o filtro de intenção para abrir o endereço “https://exemplo.com/produtos” no aplicativo Android.

Esse trecho permite que o Android identifique a `Activity` como capaz de abrir URLs do domínio com o prefixo `/produtos`.

A propriedade `android:exported="true"` é necessária porque outra aplicação precisa iniciar a tela. Por isso, a `Activity` deve validar a origem recebida, especialmente se ela executa ações sensíveis ou altera dados.

### 3. Entender o papel de cada elemento

O filtro reúne regras para o sistema decidir quais endereços podem ser enviados à aplicação. Uma configuração incompleta é uma das causas mais comuns do link abrir o navegador.

- `VIEW` indica que a atividade pode abrir um conteúdo recebido por URL.
- `DEFAULT` permite que a atividade sejaconsidered por um filtro normal de intenção.
- `BROWSABLE` permite a exibição da atividade para links acessíveis pelo navegador.
- `scheme` informa o protocolo, como `https` ou um esquema próprio.
- `host` identifica o domínio.
- `pathPrefix` limita o caminho que pode ser tratado pela atividade.

Quando todos esses dados estão no mesmo `intent-filter`, eles são combinados. Separar a combinação de esquema e domínio em filtros diferentes pode ampliar os tipos de URL aceitos além do desejado.

### 4. Receber e interpretar os parâmetros

A URL recebida pode ser obtida por `intent.getData()`, que retorna os dados original associated with the intent. O código deve validar o esquema, o host, o caminho e os parâmetros antes de carregar o conteúdo.

```kotlin
private fun handleDeepLink(intent: Intent) {
val uri = intent.data ?: return

if (uri.scheme != "https" || uri.host != "exemplo.com") {
return
}

if (!uri.path.startsWith("/produtos/")) {
return
}

val productId = uri.path.substringAfterLast("/").toIntOrNull() ?: return

openProduct(productId)
}

O tratamento deve considerar o estado atual da aplicação. Um link pode chegar quando o aplicativo está fechado, em segundo plano ou com uma tela já aberta. Em Android moderno, as Activitys podem ser recriadas pelo sistema, portanto o estado também pode ser restaurado pelo mecanismo oficial de.save instance state.

5. Criar rotas equivalentes no site

O servidor deve responder à URL com uma página válida. Se a rota pertence a um siteAMP, é recomendável oferecer uma versão sem AMP ou usar as tags rel="canonical" e rel="alternate" de acordo com a arquitetura adotada.

A página do site deve:

• Ter conteúdo equivalente ao destino do aplicativo.
• Responder corretamente em dispositivos móveis.
• Evitar redirecionamentos desnecessários.
• Manter os mesmos caminhos usados pelo aplicativo.
• Informar aos mecanismos de busca que existe uma aplicação para a mesma URL.

Isso evita a clássico "caixa de diálogo de aplicativo" quando o usuário prefere continuar no site.

Configurando App Links com assetlinks.json

O arquivo assetlinks.json fica, por padrão, no domínio raiz ou em um subdiretório relação ao host declarado no aplicativo. Para https://exemplo.com, o caminho esperado é:

https://exemplo.com/.well-known/assetlinks.json

O conteúdo relaciona o aplicativo Android com o domínio. O exemplo abaixo usa o nome do pacote e o certificado de assinatura do aplicativo:

[
{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.exemplo.app",
"sha256_cert_fingerprints": [
"AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
]
}
}
]

A impressão digital exibida no exemplo é apenas ilustrativa. O valor real deve ser copiado da assinatura usada para publicar a aplicação. Um app assinado para homologação pode usar uma impressão digital diferente da versão distribuída na Play Store.

Obter a impressão digital do certificado

No Android Studio, é possível consultar a assinatura usada para depuração. Para buildsSIGNED pela Play Store, use a chave de assinatura da conta que controla essa distribuição.

O arquivo de certificado de depuração costuma ficar no diretório ~/.android/. Em sistemas Windows, o caminho correspondente é %USERPROFILE%\.android\. O nome do arquivo pode variar entre debug.keystore e outras configurações do ambiente.

Ferramentas como keytool e o Android Studio permitem gerar uma impressão SHA-256 que pode ser comparada com a publicada no site.

Publicar o arquivo sem erro

O endpoint precisa responder com:

• Status HTTP 200.
• Tipo de conteúdo application/json.
• JSON válido.
• Domínio correto, sem redirecionamento para outra URL não relacionada.
• Conteúdo acessível por HTTPS.

O arquivo não deve ser protegido por autenticação. Também é importante lembrar que /.well-known representa uma pasta chamada .well-known, e não uma pasta comum com o nome "well-known&quot.

Entender a validação do sistema

Quando o aplicativo é instalado, o Android consulta as associações declaradas. A validação não garante que o link sempre será aberto no aplicativo, porque o usuário pode desativar a preferência. Façai o site permanecer completo e navegável.

A relação delegate_permission/common.handle_all_urls indica que o aplicativo solicita permissão para tratar URLs do domínio. Isso exige uma assinatura válida e um arquivo de associação publicado corretamente.

Como testar deep links no Android

Testar em diferentes situations evita que a configuração pareça correta em um único aparelho. O ideal é usar emulador Android, aparelho físico e navegador com versões atualizadas.

Testar pelo navegador

1. Digite a URL completa no navegador do dispositivo.
2. Confirme se o site responde corretamente.
3. Mantenha o aplicativo instalado.
4. Toque no link ou cole a URL na barra de endereços.
5. Verifique se o sistema abre o destino esperado no aplicativo.

Se o navegador abrir somente o site, o usuário pode ter desativado o aplicativo para aquele domínio. É possível conferir essa configuração em Configurações do Android, Aplicativos, Acesso special to apps, Instalação de aplicativos desconhecidos em algumas versões. Os caminhos mudam conforme o fabricante e a versão do sistema.

Testar com adb

O adb, ferramenta de linha de comando do Android Debug Bridge, permite simular a abertura de uma URL:

adb shell am start \
-a android.intent.action.VIEW \
-d "https://exemplo.com/produtos/123"

Para limitar o teste a um aplicativo específico:

adb shell am start \
-a android.intent.action.VIEW \
-d "https://exemplo.com/produtos/123" \
com.exemplo.app

O segundo comando ajuda a verificar o tratamento interno da URL, mas não comprova que o sistema escolherá o aplicativo automaticamente. Essa distinção importa porque a preferência de App Links depende da associação do domínio.

Usar o Android Studio

O Android Studio oferece ferramentas para criar links de aplicativo durante o desenvolvimento. O fluxo costuma estar em Tools, App Links Assistant, onde são informados domínio e caminho. O assistente também pode ajudar a gerar o arquivo assetlinks.json e registrar o esquema de URL.

Use a ferramenta como apoio. O resultado final ainda precisa ser testado no sistema operacional e nos navegadores mais utilizados pelo público.

Verificar o arquivo de associação

Acesse diretamente o endereço do arquivo no navegador:

https://exemplo.com/.well-known/assetlinks.json

Confira se o JSON está sendo exibido sem página de erro. No Android Studio, a ferramenta Digital Asset Links permite testar o site e o aplicativo, verificando a impressão digital usada na assinatura.

Usando um esquema próprio

Em alguns projetos, a equipe utiliza um esquema personalizado, como minhaapp://produtos/123. Essa abordagem pode ser útil para integrações internas, mas exige um cuidado especial.

O manifesto precisaria conter algo semelhante a:

<data android:scheme="minhaapp" android:host="produtos" />

A URL com esquema próprio pode acionar um aplicativo que já esteja instalado. Entretanto, se nenhum aplicativo compatível estiver disponível, o sistema poderá exibir uma mensagem de erro. O usuário também precisa autorizar o aplicativo para abrir links, o que torna a experiência menos previsível.

Para links públicos vindos do site, https App Links é a escolha mais adequada. Esquemas próprios podem existir como recurso adicional para comandos internos, desde que a equipe entenda as diferenças de segurança e usabilidade.

Parâmetros de URL eUTMs

Uma URL de campanha pode incluir parâmetros de rastreamento, como utm_source, utm_medium e utm_campaign. O aplicativo deve separar esses dados dos parâmetros que controlam a navegação.

Exemplo:

https://exemplo.com/produtos/123?utm_source=newsletter&utm_campaign=promocao-julho

O identificador do produto é 123, enquanto os parâmetros de UTM servem para medir a origem do acesso. O código não deve tentar converter todos os valores da URL em número.

Uma implementação segura pode fazer o seguinte:

• Identificar o caminho com uma allowlist de rotas conhecidas.
• Ler os parâmetros de contexto em campos separados.
• Ignorar valores desconhecidos ou inválidos.
• Preservar os parâmetros de campanha quando necessário.
• Não executar comandos recebidos diretamente pela URL.

Erros comuns na configuração

A maioria dos problemas vem de detalhes pequenos que são difíceis de perceber em uma tela única. O logcat do Android e a inspeção da URL no navegador ajudam a encontrar a origem.

Esquema e host não estão no mesmo filtro

Quando android:scheme, android:host e android:pathPrefix aparecem em elementos data separados, o Android interpreta a combinação de forma diferente. Evite filtros amplos que aceitem URLs não desejadas.

Atividade não exportada

A Activity que responde ao link precisa estar exportada. Em projetos que am android:url, a declaração de segurança e as regras de instanciação merecem atenção.

Parâmetros adicionais no manifesto

O Android permite declarar chaves de dados adicionais no filtro, como identificadores de campanha. Isso é útil quando os valores fazem parte da distinção entre rotas. Se a chave for usada incorretamente, o filtro pode se tornar amplo demais ou narrower do que o desejado.

Cache ePropagation

Depois de publicar ou corrigir assetlinks.json, o sistema pode precisar de algum tempo para atualizar a verificação. Reinstalar o aplicativo ou usar as ferramentas do Android Studio ajuda em cenários de desenvolvimento.

Rota redirecionada

Um redirecionamento pode impedir que o sistema identifique o destino final, especialmente quando a URL passa por outro domínio. Evite corrê-los de marketing em links destinados a App Links.

Deep links e SEO para sites mobile

O deep link não substitui a página web. Ele cria uma ponte entre a URL pública e o aplicativo. Para mecanismos de busca, o conteúdo principal deve continuar disponível no site e oferecer uma experiência equivalente ou superior.

A URL canônica deve apontar para a página pública. Quando o aplicativo representa uma versão da mesma página, a documentação do Google pode ser usada como referência para a relação entre o conteúdo do site e o aplicativo, especialmente em cenários de mecanismos de busca.

Uma implementação responsável considera:

• A mesma URL para site e aplicativo.
• Conteúdo indexável na versão web.
• canonical consistente.
• Página de fallback funcional.
• Dados estruturados, quando pertinentes ao negócio.
• Experiência rápida em redes móveis instáveis.

Se a rota do aplicativo contém uma tela que não pode ser vista sem autenticação, o site deve orientar o usuário a entrar na conta. Nunca exponha dados pessoais somente por causa da presença de um identificador na URL.

Checklist de implementação e validação

Use este roteiro antes de colocar a integração em produção:

• A URL foi definida com esquema, domínio e caminho estáveis?
• A rota web e a rota do aplicativo representam o mesmo conteúdo?
• A Activity está declarada e exportada corretamente?
• O filtro de intenção usa VIEW, DEFAULT e BROWSABLE?
• Os parâmetros de URL são validados no aplicativo?
• O assetlinks.json está em /.well-known/?
• A impressão digital corresponde à assinatura usada na distribuição?
• O site responde com JSON e status HTTP 200?
• O endereço do arquivo não exige login?
• O comportamento foi testado em Android atualizado e em navegador móvel?
• O usuário ainda consegue continuar no site?
• Há tratamento para links inválidos ou incompletos?

Perguntas Frequentes (FAQ)

Qual a diferença entre deep link e App Link no Android?

Um deep link é um link que direciona para um destino interno do aplicativo. Um App Link é um tipo específico de deep link baseado em HTTPS, associado a um domínio por meio do arquivo assetlinks.json. Por isso, App Links oferecem uma experiência mais previsível e são recomendados para links públicos da web.

Onde deve ficar o arquivo assetlinks.json?

O arquivo deve ficar em https://seu-dominio.com/.well-known/assetlinks.json. Ele precisa responder com status HTTP 200, conteúdo JSON válido e a impressão digital correta do aplicativo. Não deve ficar atrás de autenticação ou depender de um redirecionamento para outro domínio.

Como saber qual certificado usar no assetlinks.json?

Use o certificado de assinatura da versão que será distribuída. Durante o desenvolvimento, isso costuma ser o certificado de depuração. Na Play Store, pode ser necessário incluir também a impressão digital da chave de assinatura usada pela conta. A comparação deve ser feita com ferramentas oficiais do Android Studio.

Por que meu deep link abre o navegador em vez do aplicativo?

As causas mais comuns são arquivo assetlinks.json ausente, impressão digital incorreta, host divergente no manifesto ou preferência do aplicativo desativada. Verifique o endpoint diretamente no navegador, confira a assinatura e teste com o adb para separar a recepção da URL da escolha do aplicativo pelo sistema.

É necessário usar um esquema próprio como meuapp://?

Não necessariamente. Para links públicos, o uso de https com App Links é recomendável. Um esquema próprio pode funcionar, mas costuma exigir autorização do usuário e oferece uma experiência diferente quando nenhum aplicativo compatível está instalado.

Como testar deep links sem publicar o aplicativo?

Você pode instalar o aplicativo em modo de depuração e usar o Android Studio ou o adb. O teste pelo adb confirma se a aplicação recebe a URL, enquanto o teste com um link real verifica a associação do domínio e a seleção automática do aplicativo. A validação final deve considerar um aparelho físico e o navegador usado pelo público.

Conclusão

Deep links no Android funcionam melhor quando URL, manifesto, aplicativo e servidor contam a mesma história. A rota precisa existir nos dois ambientes, a Activity deve tratar os parâmetros com segurança e o domínio precisa comprovar a associação por meio do assetlinks.json.

A configuração mais confiável começa com App Links em URLs HTTPS, usa validação explícita do destino e mantém o site como alternativa funcional. Depois, o teste deve cobrir link direto, aplicativo fechado, aplicativo em segundo plano, assinatura de debug e versão publicada.

Para sites WordPress que também oferecem aplicativo Android, a parte mais delicada é manter as rotas e os links estáveis. A Baita Site possui equipe especializada em sites, e-commerce, sistemas e inteligência artificial, com domínio de WordPress e integração de soluções mobile. Fale com a gente e veja como podemos acelerar o seu projeto.

Referências consultadas

• Documentação oficial do Android sobre criação de links diretos e App Links
• Documentação oficial do Android sobre verificação de domínios com Digital Asset Links
• Documentação oficial do Android sobre testes de App Links
• Documentação oficial do Android sobre intent filters e dados
• Digital Asset Links API, documentação oficial do Google
• Google Search Central: enviar e criar sites para celular, em português