Intent Filter: o que é, como funciona e é usado no desenvolvimento

O que é Intent Filter?

Intent Filter é um elemento de configuração de uma aplicação Android que informa ao sistema sobre a capacidade do componente de manipular certos tipos de intents implícitos. Ao contrário dos Intents explícitos que especificam uma classe concreta, os Intents implícitos contêm apenas uma descrição da ação necessária, e o próprio sistema encontra um componente adequado com base nos filtros registrados.

Os filtros são declarados dentro de um componente — Activity, Service ou BroadcastReceiver — no arquivo AndroidManifest.xml. Cada filtro pode conter vários elementos action, category e data. Um componente pode ter um número ilimitado de Intent Filters, cada um descrevendo um cenário de manipulação diferente.

Papel na arquitetura Android

Intent Filter implementa o princípio de acoplamento fraco entre componentes de aplicações. A aplicação A não precisa saber da existência da aplicação B — ela simplesmente envia um Intent com a descrição da ação, e o sistema o roteia com base nos filtros. Este mecanismo está na base do Share Sheet, seleção do navegador e manipulação de deep links.

Tipos de Intent: explícitos e implícitos

Os Intents explícitos especificam uma classe de componente concreta para iniciar. Eles são usados para navegação interna dentro de uma única aplicação quando o desenvolvedor sabe exatamente qual Activity deve abrir. Os Intents implícitos contêm apenas uma descrição da ação, e o componente é determinado pelo sistema dinamicamente.

Intent Filter funciona exclusivamente com Intents implícitos. Se um Intent especifica uma classe concreta, o sistema ignora todos os filtros e inicia o componente especificado diretamente. Os filtros são verificados apenas ao resolver chamadas implícitas, tornando-os um elemento chave da interação entre aplicações.

Comparação de Intents explícitos e implícitos

Estrutura do Intent Filter no manifesto

Cada Intent Filter consiste em três grupos de elementos — action, category e data — cuja combinação determina quais Intents o componente receberá. Um filtro é considerado satisfeito se o Intent corresponde a pelo menos um elemento de cada grupo.

Action descreve a ação sendo executada — visualizar, editar, enviar. Category adiciona contexto de processamento adicional — por exemplo, a capacidade de iniciar a partir do navegador. Data define o formato da informação sendo manipulada via URI ou tipo MIME.

Componentes da tag intent-filter

Exemplo de um Intent Filter para uma Activity que abre links para perfis de usuário. O filtro inclui todos os três grupos de elementos para roteamento preciso.

<activity android:name=".ProfileActivity">
    <intent-filter>
        <action
            android:name="android.intent.action.VIEW" />
        <category
            android:name="android.intent.category.DEFAULT" />
        <category
            android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="myapp"
            android:host="profile" />
    </intent-filter>
</activity>

Observe a especificação obrigatória de category DEFAULT — sem ela o sistema não transmitirá Intents implícitos ao componente. A categoria BROWSABLE é adicionada se o link deve ser manipulado a partir do navegador.

Intent Filter para deep links

Um deep link no Android é configurado através de um Intent Filter com action VIEW e uma tag data contendo o esquema, host e caminho. Ao seguir um link como myapp://profile/42, o sistema encontra uma Activity com um filtro correspondente e a inicia com o URI passado. É importante configurar corretamente pathPrefix, pathPattern ou path para correspondência exata.

A partir do Android 6 (API 23), foi adicionado suporte para App Links — deep links verificados via HTTPS. Os App Links usam o mesmo Intent Filter mas com verificação adicional de domínio através de Digital Asset Links. Após a verificação, o sistema abre automaticamente a aplicação sem um diálogo de seleção.

Tag Data para URL

Exemplo de um filtro para App Link com verificação via link HTTPS. Neste caso, o esquema é sempre https e o host corresponde ao domínio especificado em Digital Asset Links.

<intent-filter android:autoVerify="true">
    <action
        android:name="android.intent.action.VIEW" />
    <category
        android:name="android.intent.category.DEFAULT" />
    <category
        android:name="android.intent.category.BROWSABLE" />
    <data
        android:scheme="https"
        android:host="example.com"
        android:pathPrefix="/profile" />
</intent-filter>

O atributo autoVerify instrui o sistema a verificar os Digital Asset Links quando a aplicação é instalada. Se a verificação passar com sucesso, a aplicação se torna automaticamente o manipulador padrão para o domínio e caminhos especificados.

Manipulação de Intent em componentes da aplicação

Depois que o sistema selecionou um componente para manipular o Intent, o desenvolvedor deve extrair dados do intent recebido dentro do componente alvo. Para Activity, o método getIntent() em onCreate() é usado; para BroadcastReceiver, o método onReceive(), onde Intent é passado como parâmetro.

A extração de dados inclui obter a action para determinar o tipo de operação, data para o URI e parâmetros extra para informações adicionais. Cada um destes elementos pode estar ausente, portanto uma verificação de null é obrigatória antes do uso.

Código de manipulação na Activity

Exemplo de manipulação de um deep link recebido em uma Activity em Kotlin. O código extrai o URI do Intent e toma decisões de navegação com base no host e caminho.

class ProfileActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val uri = intent?.data
        if (uri?.host == "profile") {
            val userId = uri.lastPathSegment
            loadProfile(userId)
        }
    }
}

Recomenda-se usar o operador safe call para verificar intent e data por null, pois a atividade pode ser iniciada sem um deep link recebido. Também deve verificar host e pathSegment por null antes de usá-los na navegação.

Prioridade e resolução de conflitos

Se várias aplicações registraram um Intent Filter que corresponde ao mesmo Intent implícito, o sistema mostra ao usuário um diálogo de seleção. O usuário pode selecionar uma aplicação para uso único ou definir um manipulador padrão. A partir do Android 10, o diálogo de seleção é mostrado apenas na primeira chamada, após o que o sistema lembra a escolha do usuário.

Para gerenciar a prioridade, o atributo android:priority na tag intent-filter é usado. Quanto maior o valor, maior a prioridade do componente ao resolver conflitos. No entanto, a prioridade não funciona para filtros de diferentes aplicações — neste caso, um diálogo de seleção é sempre mostrado se nenhuma aplicação estiver definida como padrão.

Diálogo de seleção de aplicação

O desenvolvedor pode chamar programaticamente o diálogo de seleção através de Intent.createChooser(), passando o Intent alvo e um título. Isso é útil quando uma aplicação quer oferecer explicitamente ao usuário a escolha de um manipulador, mesmo se uma aplicação padrão estiver definida. Por exemplo, ao enviar imagens para redes sociais via ACTION_SEND com createChooser garante mostrar o diálogo independentemente das configurações padrão.

Erros comuns ao configurar Intent Filter

Um dos erros mais comuns é a ausência da categoria DEFAULT no Intent Filter. Os desenvolvedores copiam a configuração de exemplos mas esquecem de adicionar esta categoria, como resultado a Activity não recebe Intents implícitos. O sistema simplesmente não vê o filtro para chamadas implícitas, embora os Intents explícitos continuem funcionando.

O segundo erro comum é a especificação incorreta de scheme na tag data sem um URI completo. Se apenas o esquema é especificado mas o host não, o filtro aceitará todos os links com este esquema de qualquer fonte, o que pode levar a chamadas indesejadas de fontes não confiáveis. Recomenda-se sempre especificar pelo menos scheme e host.

O terceiro erro é a ausência de verificação de null para intent.data no código da Activity. Se a Activity é iniciada não através de um deep link mas da forma padrão a partir do launcher, o Intent não contém um URI. Acessar intent.data sem verificação causa uma NullPointerException e fecha a aplicação. Sempre use intent?.data?.toString() com o operador safe call.