Criar links diretos para conteúdo de app

Quando um link clicado ou uma solicitação programática invoca uma intent de URI da Web, o sistema Android tenta cada uma das ações a seguir, em ordem sequencial, até que a solicitação seja bem-sucedida:

  1. Abrir o app preferencial do usuário para processar o URI, se houver um app 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.

Siga as etapas abaixo para criar e testar links para seu conteúdo. Você também pode usar o App Links Assistant no Android Studio para adicionar Android App Links.

Observação : no Android 12 (nível 31 da API) e versões mais recentes, uma intent da Web genérica é resolvida como uma atividade no app somente se ele for aprovado para o domínio específico contido nessa intent da Web. Se o app não for aprovado para o domínio, a intent da Web será resolvida para o app de navegação padrão do usuário.

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 seja acessado na Pesquisa Google.
<data>
Adicione uma ou mais tags <data>. Cada uma delas representa um formato de URI que é resolvido para a atividade. No mínimo, a tag <data> precisa incluir o atributo android:scheme.

É 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 simplesmente com base no nome do 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 possa ser acessado em um navegador da Web. Sem ela, não é possível clicar no link de um navegador para seu app.

Inclua também a categoria DEFAULT. Ela 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 esse recurso oferece suporte apenas a https://www.example.com e app://open.my.app. No entanto, ele oferece suporte a estes dois, além de app://www.example.com e https://open.my.app.

Cuidado:se várias atividades contêm filtros de intent que se resolvem para o mesmo Link do app Android verificado, não há garantia de qual atividade processa o link.

Depois de adicionar filtros de intent com URIs para conteúdo de atividade ao manifesto do app, o Android poderá rotear qualquer Intent que tenha URIs correspondentes para o 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 métodos getData() e getAction() para extrair os dados e a ação associados à Intent recebida. É possível chamar esses métodos a qualquer momento durante o ciclo de vida da atividade, mas geralmente é necessário fazer isso durante os callbacks iniciais, como onCreate() ou onStart().

Confira 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 precisa 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 nunca tenham aberto o aplicativo. Não há problema em exibir solicitações para os usuários em interações subsequentes 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 um link direto.

Testar os links diretos

Você pode usar o Android Debug Bridge com a ferramenta Gerenciador de atividades (AM) para testar se os URIs do filtro de intent especificados para links diretos direcionam para a atividade correta do app. É possível 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 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

A declaração do manifesto e o gerenciador de intent definidos acima definem a conexão entre seu app e um site e o que fazer com os links de entrada. 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 próxima lição explica como implementar essa verificação.

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