URL Scheme: o que é, como funciona e é usado no desenvolvimento

O que é URL Scheme?

URL Scheme — é um identificador de protocolo único que um aplicativo registra no sistema operacional para receber chamadas através de links personalizados. Quando um usuário clica em um link como myapp://profile/123, o sistema identifica o aplicativo que registrou o esquema myapp e passa o controle para ele com o URI completo. Este mecanismo permite que os aplicativos troquem dados e abram uns aos outros sem necessidade de infraestrutura de servidor.

O conceito de URL Scheme é diretamente emprestado dos padrões web RFC 3986, onde o esquema URI é o primeiro componente de qualquer identificador universal de recurso. No desenvolvimento móvel, esta ideia é adaptada para comunicação entre aplicativos, onde em vez de um servidor HTTP, o próprio aplicativo atua como manipulador do link.

Exemplos de URL Schemes conhecidos

Muitos aplicativos populares registram seus próprios URL Schemes para integração com serviços de terceiros. Por exemplo, o Spotify usa o esquema spotify://, o Telegram usa tg://, e o Instagram usa instagram://. Os desenvolvedores também criam frequentemente esquemas como appname:// para navegação interna e testes de ponta a ponta de telas.

Os URL Schemes ainda são amplamente utilizados em notificações push, newsletters por email e códigos QR onde é necessária navegação instantânea para uma seção específica do aplicativo. No entanto, a partir do iOS 9 e Android 6, surgiram mecanismos alternativos que gradualmente complementam e substituem os esquemas simples.

Sintaxe do URL Scheme: esquema, host e caminho

A estrutura de um URI personalizado segue a especificação geral RFC 3986 e consiste em vários componentes. O esquema é especificado primeiro e separado por dois pontos do resto do endereço. Após o esquema podem seguir host, porta, caminho, parâmetros de consulta e fragmento, cada um dos quais é opcional.

A sintaxe completa se parece com scheme://host/path?key=value#fragment. O esquema é o único elemento obrigatório; o restante é determinado pelas necessidades da implementação específica. A barra dupla após o esquema é historicamente emprestada do HTTP e não é estritamente obrigatória pela especificação, mas é universalmente usada como convenção.

Componentes do URI

Para uma representação visual da estrutura do URI, é utilizada uma tabela de componentes. Cada elemento tem seu propósito e nível de obrigatoriedade.

Os desenvolvedores podem escolher arbitrariamente a estrutura do URI, o que cria flexibilidade, mas gera problemas de compatibilidade entre diferentes versões do aplicativo. Recomenda-se documentar o formato do URL Scheme como parte da API pública do aplicativo e versioná-lo quando ocorrerem alterações.

Como o URL Scheme funciona no iOS

O iOS exige registro explícito de cada URL Scheme no arquivo Info.plist do projeto. O desenvolvedor adiciona um array CFBundleURLTypes, cada elemento do qual contém um identificador (CFBundleURLName) e uma lista de esquemas suportados (CFBundleURLSchemes). Após o registro, o sistema direciona automaticamente todas as chamadas recebidas nos esquemas registrados para o aplicativo.

O tratamento de um URL Scheme recebido ocorre no delegado do aplicativo através do método application(_:open:options:). Este método recebe um objeto URL do qual o caminho e os parâmetros de consulta são extraídos para tomar decisões de navegação. O manipulador deve retornar um valor Bool indicando o sucesso da operação.

Tratamento no AppDelegate

Abaixo está um exemplo de implementação de um manipulador de URL Scheme em Swift. O código demonstra a extração do host e dos parâmetros de consulta de um URI recebido usando URLComponents.

func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any]
) -> Bool {
    let host = url.host
    let params = URLComponents(
        url: url,
        resolvingAgainstBaseURL: false
    )?.queryItems
    if host == "profile" {
        navigateToProfile(params)
    }
    return true
}

O método usa URLComponents para análise segura dos parâmetros de consulta. Esta abordagem é preferível à análise manual de strings, pois lida automaticamente com a codificação percentual e a decodificação de caracteres especiais nos valores dos parâmetros.

Como o URL Scheme funciona no Android

O Android usa o sistema Intent Filter para rotear deep links baseados em URL Scheme. O desenvolvedor declara um filtro no AndroidManifest.xml dentro da tag Activity que deve manipular o link. O filtro contém a ação VIEW, as categorias BROWSABLE e DEFAULT, e uma tag data especificando o esquema, host e pathPrefix.

Quando um usuário clica em um link com um esquema personalizado, o sistema verifica o Intent Filter de todos os aplicativos instalados. Se vários aplicativos correspondentes forem encontrados, o usuário recebe um diálogo de seleção. A categoria BROWSABLE permite que o link seja processado a partir do navegador.

Configuração do Intent Filter

Exemplo de declaração de Intent Filter no AndroidManifest.xml para manipular o esquema myapp em uma Activity. A combinação de action e category é obrigatória para o roteamento correto de deep links.

<activity android:name=".MainActivity">
    <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"
            android:pathPrefix="/user" />
    </intent-filter>
</activity>

Após configurar o filtro na Activity, é necessário chamar intent.getData() para obter o URI. É importante verificar intent e data quanto a null, pois a Activity pode ser iniciada sem um deep link recebido, por exemplo durante a inicialização padrão a partir do lançador.

Passagem de parâmetros via URL Scheme

Os parâmetros de consulta no URL Scheme são passados após o ponto de interrogação no formato chave=valor, separados por e comercial. Este formato é idêntico às solicitações HTTP e é facilmente processado pelas ferramentas padrão da plataforma. Os parâmetros devem ser codificados usando codificação percentual para todos os caracteres que não pertencem ao conjunto permitido de URI.

Exemplo de um link completo com parâmetros: myapp://profile?userId=42&source=email&ref=abc123. Após extrair a URL, o aplicativo analisa sequencialmente todos os query-items e com base em seus valores toma uma decisão de navegação para a tela de destino.

Limitação de comprimento do URI

Ao passar dados complexos, é importante considerar a limitação de comprimento do URI. No iOS, o comprimento máximo do URL Scheme é limitado a 2 KB, após o qual o sistema trunca o link. No Android, o limite é de aproximadamente 8 KB, mas o valor exato depende da versão do SO e do fabricante do dispositivo. Para grandes volumes de dados, recomenda-se passar apenas um identificador de sessão via URL Scheme e carregar o restante dos dados do servidor.

Limitações e alternativas do URL Scheme

A principal desvantagem do URL Scheme é a incapacidade de manipular um link se o aplicativo não estiver instalado no dispositivo. O navegador exibe um erro e o usuário perde o contexto de navegação. Para resolver este problema, a Apple introduziu Universal Links no iOS 9 e o Google introduziu App Links no Android 6. Ambos os mecanismos são registrados através de um domínio web associado ao aplicativo.

Universal Links e App Links funcionam como links HTTPS normais, mas quando o aplicativo está instalado, eles o abrem sem um diálogo de seleção. Se o aplicativo não estiver instalado, o link abre uma página web no mesmo domínio, preservando a experiência do usuário. Isso os torna a alternativa preferida para ambientes de produção.

Mecanismos de fallback

Para URL Scheme no iOS e Android, não existe um mecanismo de fallback integrado. Os desenvolvedores usam soluções intermediárias de servidor: o link leva a uma página web que verifica se o aplicativo está instalado via JavaScript e redireciona para o esquema ou para a loja de aplicativos. Firebase Dynamic Links e Branch.io oferecem soluções prontas para este problema com suporte a deferred deep links que determinam automaticamente o status de instalação e roteiam o usuário sem necessidade de desenvolver um pipeline de servidor personalizado.

Surge complexidade adicional ao usar URL Scheme no iOS 15+ e Android 12+, onde as regras de privacidade foram endurecidas. O Safari bloqueia tentativas de abrir um esquema não registrado sem confirmação prévia, e o Android 12 restringe a visibilidade de aplicativos instalados através do PackageManager. Essas mudanças tornam o uso de URL Scheme para comunicação entre aplicativos menos confiável do que em versões anteriores das plataformas.