Criar links diretos

Os links diretos permitem que você leve os usuários diretamente ao seu app em navegadores da Web, notificações, redes sociais, anúncios e outras fontes. Os links diretos oferecem transições diretas entre apps e da Web para apps que podem ajudar a aumentar o engajamento com conteúdo contextual e segmentado.

Este guia explica como os links diretos funcionam e como criar e testar links diretos para seu conteúdo.

Para links diretos que fazem referência ao seu próprio site ou domínios, recomendamos o uso de Links do app, que oferece uma experiência confiável e integrada para seus usuários.

Como os links diretos funcionam

Os links diretos são um recurso geral do sistema Android, compatível com todas as versões e em todos os dispositivos. Ele aproveita o sistema de intents do Android para rotear links diretos para apps interessados. Os apps que querem processar um URI de link direto específico declaram um filtro de intent correspondente nos arquivos de manifesto do app.

No momento da execução, quando o usuário toca em um link, o Android aciona uma intent e tenta roteá-la para um app. Como vários apps podem declarar filtros de intent que correspondam a um determinado URI, o Android realiza estas ações, nesta ordem, para rotear a intent:

Abrir o app padrão do usuário que pode processar o URI, se houver um app designado.
Abrir o único app disponível para processar o URI.
Permitir que o usuário selecione um app em uma caixa de diálogo de desambiguação.

Isso significa que, mesmo que seus filtros de intent correspondam a um determinado URI, não há garantia de que o sistema vai rotear a intent de link direto para seu app. O usuário tem um papel fundamental no gerenciamento de qual app processa a intent, o que oferece controle e escolha. Para ter mais controle sobre os links diretos para seu próprio site e domínios, use os Links do app.

A caixa de diálogo de desambiguação do Android permite que o usuário veja todos os apps instalados que foram registrados para processar uma intent de link direto. O usuário também pode selecionar um app como padrão para esse tipo de link. Depois que o usuário define um padrão, o sistema não mostra mais a caixa de diálogo para essa intent específica, e o app escolhido é aberto automaticamente.

Figura 1. Caixa de diálogo de desambiguação.

O comportamento da caixa de diálogo de desambiguação evoluiu nas versões do Android. Por exemplo, no Android 12 e versões mais recentes, os links da Web que não são Links do app verificados geralmente são abertos em um navegador da Web por padrão. Já em versões anteriores, uma caixa de diálogo de desambiguação pode ter aparecido se um app pudesse processar o link da Web.

Observação: com o Android 12 (nível 31 da API), intents da Web genéricas são resolvidas como uma atividade no app apenas se ele for aprovado para o domínio específico contido na intent. Se o app não for aprovado para o domínio, a intent da Web será resolvida no app de navegação padrão do usuário.

Tipos de links diretos

Há três tipos de links diretos que você pode oferecer suporte no Android:

Links diretos personalizados: são links diretos que usam um esquema de URI personalizado (como example://products/123) para levar um usuário diretamente a um conteúdo específico em um app. Eles são úteis para navegação interna ou links de fontes que você controla, mas não são links da Web padrão e ainda podem acionar a caixa de diálogo de desambiguação se outro app registrar o mesmo esquema personalizado.
Links da Web: são links diretos que usam os esquemas padrão http e https. Eles são mais versáteis porque são URLs padrão, mas no Android 12 e versões mais recentes, eles quase sempre acionam a caixa de diálogo de desambiguação, o que significa que é provável que sejam processados pelo navegador da Web do usuário por padrão, em vez de serem roteados para seu app.
Links do app: disponíveis desde o Android 6.0 (nível 23 da API), são verificados links da Web. Por meio de um processo de associação de sites, você pode comprovar ao sistema Android que é proprietário do domínio. Depois de verificados, o sistema roteia automaticamente os links desse domínio diretamente para seu app, ignorando completamente a caixa de diálogo de desambiguação. Isso cria uma experiência confiável e integrada para seus usuários.

Adicionar filtros de intent para links recebidos

Para criar um link para o conteúdo do seu app, adicione um filtro de intent que contenha estes elementos e valores de atributo no manifesto:

<action>

Especifique a ação da intent ACTION_VIEW para que o filtro de intent possa ser acessado a partir da Pesquisa Google.

<data>

Adicione uma ou mais <data> tags, de modo que cada uma delas represente um formato de URI compatível com a atividade. No mínimo, a <data> tag precisa incluir o android:scheme atributo.

É possível adicionar outros atributos para refinar ainda mais o tipo de URI aceito pela atividade. Por exemplo, você pode ter várias atividades que aceitam URIs semelhantes, mas que são diferentes apenas no nome do caminho. Nesse caso, use o android:path atributo ou as variantes pathPattern ou pathPrefix para diferenciar qual atividade o sistema precisa abrir para diferentes caminhos de URI.

<category>

Inclua a BROWSABLE categoria. Essa ação é necessária para que o filtro de intent possa ser acessado de um navegador da Web. Sem ela, não é possível clicar no link de um navegador para seu app.

Inclua também a DEFAULT categoria. Ela permite que o app responda a intents implícitas. Sem isso, a atividade só poderá ser iniciada se o intent especificar o nome do componente do app.

O snippet XML a seguir mostra como especificar um filtro de intent no manifesto para links diretos. Os URIs "example://gizmos" e "http://www.example.com/gizmos" são compatíveis com essa atividade.

<activity
    android:name="com.example.android.GizmosActivity"
    android:label="@string/title_gizmos" >
    <intent-filter android:label="@string/filter_view_http_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "http://www.example.com/gizmos” -->
        <data android:scheme="http"
              android:host="www.example.com"
              android:pathPrefix="/gizmos" />
        <!-- note that the leading "/" is required for pathPrefix-->
    </intent-filter>
    <intent-filter android:label="@string/filter_view_example_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "example://gizmos” -->
        <data android:scheme="example"
              android:host="gizmos" />
    </intent-filter>
</activity>

A única diferença entre os dois filtros de intent é o <data> elemento. Embora seja possível incluir vários elementos <data> no mesmo filtro, é importante que você crie filtros separados se sua intenção for declarar URLs exclusivos (como uma combinação específica de scheme e host), uma vez que vários elementos <data> no mesmo filtro de intent são realmente mesclados para considerar todas as variações de seus atributos combinados. Por exemplo, considere o seguinte:

<intent-filter>
  ...
  <data android:scheme="https" android:host="www.example.com" />
  <data android:scheme="app" android:host="open.my.app" />
</intent-filter>

Pode parecer que esse filtro é compatível apenas com https://www.example.com e app://open.my.app. No entanto, ele é compatível também com app://www.example.com e https://open.my.app.

Cuidado: se várias atividades contiverem filtros de intent que sejam resolvidos para o mesmo Link do app Android verificado, não haverá garantia de qual atividade processará o link.

Depois de adicionar filtros de intent com URIs para conteúdo de atividade ao manifesto do seu app, o Android poderá rotear qualquer Intent que tenha URIs correspondentes para seu app durante a execução.

Para saber mais sobre como definir filtros de intent, consulte Como permitir que outros apps iniciem sua atividade.

Ler dados de intents recebidas

Depois que o sistema iniciar sua atividade por meio de um filtro de intent, você poderá usar os dados fornecidos pelo Intent para determinar o que precisa ser renderizado. Chame os getData() e getAction() métodos para recuperar os dados e ação associada à Intent de entrada. Esses métodos podem ser chamados a qualquer momento do ciclo de vida da atividade, mas geralmente precisam ser acionados durante os callbacks iniciais, como onCreate() ou onStart.

Veja um snippet que mostra como recuperar dados de um Intent:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    val action: String? = intent?.action
    val data: Uri? = intent?.data
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent = getIntent();
    String action = intent.getAction();
    Uri data = intent.getData();
}

Siga estas práticas recomendadas para melhorar a experiência do usuário:

O link direto deve levar os usuários diretamente ao conteúdo, sem solicitações, páginas intersticiais ou logins. Verifique se os usuários podem ver o conteúdo do app, mesmo que eles nunca tenham aberto o app antes. Não há problema em exibir solicitações para os usuários em interações posteriores ou quando eles abrem o app na tela de início.
Siga as orientações de design descritas em Navegação com Voltar e Para cima para que seu app corresponda às expectativas dos usuários em relação à navegação anterior depois que eles acessarem o app por meio de um link direto.

Testar os links diretos

Você pode usar o Android Debug Bridge com a ferramenta Gerenciador de atividades (AM, na sigla em inglês) para testar se os URIs do filtro de intent que você especificou para links diretos direcionam para a atividade correta do app. É possível executar o comando do adb em um dispositivo ou emulador.

A sintaxe geral para testar um URI de filtro de intent com adb é:

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d <URI> <PACKAGE>

Por exemplo, o comando abaixo tenta visualizar uma atividade no app de destino associada ao URI especificado.

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d "example://gizmos" com.example.android

Observação: ao definir uma coleção de tipos primitivos em uma rota, como **@Serializable data class Product(val colors: List)**, o formato de URL de link direto gerado automaticamente é **basePath?colors={value**}. Se você tentar especificar um URI com vários parâmetros de consulta (por exemplo, **basepath?colors=red&colors=blue**), será necessário escapar o "e" comercial (por exemplo, **basepath?colors=red\&colors=blue**).

A declaração do manifesto e o gerenciador de intents que você configurou definem a relação entre seu app e um site e o que fazer com os links recebidos. No entanto, para que o sistema trate o app como gerenciador padrão de um conjunto de URIs, é preciso solicitar também que o sistema verifique essa conexão. Verificar os Links do app explica como implementar essa verificação.

Para saber mais sobre intents e links de app, consulte os seguintes recursos:

Criar links diretos Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.