Criar links diretos

Com os links diretos, você pode direcionar os usuários diretamente para seu app usando navegadores da Web, notificações, mídias sociais, anúncios e outras fontes. Os links diretos oferecem transições diretas de app para app e da Web para o app 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 de apps, que oferecem uma experiência integrada e confiável para os usuários.

Como funcionam os links diretos

Os links diretos são um recurso geral do sistema Android, compatível com todas as versões e todos os dispositivos. Ele aproveita o sistema de intents do Android para encaminhar 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 fazer o roteamento para um app. Como vários apps podem declarar filtros de intent que correspondem a um determinado URI, o Android realiza estas ações, nesta ordem, para rotear a intent:

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

Isso significa que, mesmo que os filtros de intent correspondam a um determinado URI, não há garantia de que o sistema vai encaminhar 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 opções. Para ter mais controle sobre os links diretos para seu site e domínios, use os links de apps.

A caixa de diálogo de desambiguação do Android permite que o usuário veja todos os apps instalados que se registraram 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.

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 aparecer se um app puder processar o link da Web.

Tipos de links diretos

Há três tipos de links diretos que podem ser usados 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 eficientes 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, quase sempre acionam a caixa de diálogo de desambiguação, o que significa que provavelmente serão processados pelo navegador da Web do usuário por padrão, em vez de serem encaminhados para o app.
• Links do app: disponíveis desde o Android 6.0 (nível 23 da API), são links da Web verificados. Por um processo de associação de site, você pode provar ao sistema Android que é o proprietário do domínio. Depois de verificados, o sistema encaminha automaticamente os links desse domínio diretamente para o app, ignorando completamente a caixa de diálogo de desambiguação. Isso cria uma experiência confiável e integrada para os 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 de intent ACTION_VIEW para que o filtro de intent possa ser alcançado na Pesquisa Google.

<data>

Adicione uma ou mais tags <data>, cada uma representando um formato de URI que é resolvido para a atividade. No mínimo, a tag <data> precisa incluir o atributo android:scheme.

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

<category>

Inclua a categoria BROWSABLE. Ele é necessário para que o filtro de intent seja acessível em um navegador da Web. Sem ele, clicar em um link em um navegador não vai abrir o app.

Inclua também a categoria DEFAULT. Isso permite que o app responda a intents implícitas. Sem isso, a atividade só poderá ser iniciada se a 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 resolvidos para 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 elemento <data>. Embora seja possível incluir vários elementos <data> no mesmo filtro, é importante criar filtros separados quando sua intenção é declarar URLs exclusivos (como uma combinação específica de scheme e host), porque vários elementos <data> no mesmo filtro de intent são mesclados para considerar todas as variações dos 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 isso só é compatível com https://www.example.com e app://open.my.app. No entanto, ele também oferece suporte a estes: app://www.example.com e https://open.my.app.

Depois de adicionar filtros de intent com URIs para o conteúdo da atividade ao manifesto do app, o Android poderá encaminhar qualquer Intent que tenha URIs correspondentes ao seu app no momento da 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 inicia sua atividade usando um filtro de intent, você pode usar os dados fornecidos pelo Intent para determinar o que precisa ser renderizado. Chame os métodos getData() e getAction() para recuperar os dados e a ação associados ao Intent recebido. Você pode chamar esses métodos a qualquer momento durante o ciclo de vida da atividade, mas é recomendável usar o recurso em callbacks iniciais, como onCreate() ou onStart.

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

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

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

@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. Confira 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 os botões "Voltar" e "Para cima" para que o app corresponda às expectativas dos usuários quando eles tocam no botão "Voltar" depois de acessarem o app por um link direto.

Testar os links diretos

Use o Android Debug Bridge com a ferramenta Activity Manager (am) para testar se os URIs do filtro de intent especificados para links diretos são resolvidos para a atividade correta do app. Você pode executar o comando 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 a seguir tenta visualizar uma atividade do app de destino associada ao URI especificado.

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

No Android 17, também é possível usar a flag --debug-link com am start para diagnosticar como o sistema resolve um URL e inspecionar filtros de intent correspondentes ou regras de link dinâmico do app. Para mais informações, consulte Diagnosticar a resolução de links com a flag debug-link.

A declaração de manifesto e o gerenciador de intents que você define estabelecem a conexão entre o app e um site e o que fazer com os links recebidos. No entanto, para que o sistema trate seu app como o gerenciador padrão de um conjunto de URIs, você também precisa solicitar que o sistema verifique essa conexão. A página Verificar links de apps explica como implementar essa verificação.

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

• Intents e filtros de intent
• Como permitir que outros apps iniciem sua atividade
• Adicionar Android App Links com o Android Studio