Config DeepLink in Flutter (PT-BR)

Introdução

Neste artigo, vou mostrar como configurar deep links no Flutter, associando o aplicativo Android a um site e roteando corretamente as páginas usando o pacote go_router. Vamos explorar a configuração do AndroidManifest.xml, o processo de verificação do domínio e como lidar com deeplinks no Flutter de maneira eficiente.

O que são Deep Links?

Vamos detalhar os três tipos de deep links oferecidos no Android app links: Links Diretos, Links da Web e Links do App Android. Cada um deles permite que o usuário interaja com o aplicativo de uma maneira específica ao clicar em um link.

Links Diretos (Deep Links)

Os Deep Links clássicos permitem que URLs específicas redirecionem os usuários para partes internas do aplicativo. Quando um deep link é clicado, o Android verifica se há um aplicativo que possa abrir essa URL. Se existir, ele será lançado automaticamente ou poderá abrir uma caixa de diálogo de desambiguação.

Como funciona:

• Um deep link é mapeado para uma página ou recurso específico do app.

• Se o aplicativo estiver instalado, ele será aberto na tela específica, conforme a URL acessada.

• Se o app não estiver instalado, o link será tratado por um navegador web.

Exemplo: No exemplo a seguir temos um androidManifest configurado para abrir esquemas geográficos.

<activity
    android:name=".MyMapActivity"
    android:exported="true"
    ...>
    <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="geo" />
    </intent-filter>
</activity>

Como podem ver ele abriu uma caixa de desambiguação dando a possibilidade de abrir o link no Maps ou no Chrome

Vantagens:

• Permite o acesso rápido a partes específicas do app.

• A experiência do usuário é otimizada, com redirecionamento para o conteúdo correto.

Desvantagens:

• Funciona apenas se o aplicativo estiver instalado.

Links da Web (Web Links)

Os Web Links são URLs normais (HTTP ou HTTPS) que, quando clicados, podem ser abertas tanto no navegador quanto no aplicativo. Se o aplicativo Android estiver configurado para manipular certos URLs, ele pode capturá-los e abrir o app ao invés do navegador. Se o app não estiver disponível, o link abrirá no navegador.

O snippet de código a seguir mostra um exemplo de filtro de link da Web:

<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="http" />
    <data android:host="myownpersonaldomain.com" />
</intent-filter>

Como funciona:

• O usuário clica em um link normal da web (https://www.seusite.com/produto/123).

• Se o aplicativo estiver instalado e for configurado para capturar esses links, ele será aberto com o conteúdo correspondente.

• Se o aplicativo não estiver instalado, a URL é aberta no navegador.

Exemplo:

Um link como:

https://www.seusite.com/produto/123

abriria a página do produto 123 no app, se o app estiver instalado, ou no navegador, caso contrário.

Vantagens:

• Funciona tanto no app quanto na web, proporcionando flexibilidade.

• Se o app não estiver instalado, o conteúdo ainda pode ser acessado.

Desvantagens:

• Requer a configuração adequada para que o app capture o link.

Links do App Android (Android App Links)

Os Android App Links são uma evolução dos deep links e web links. Eles permitem que o Android verifique automaticamente se o aplicativo pode abrir um link de um determinado domínio e abrir o app sem exibir uma tela de escolha ao usuário. Isso ocorre através de uma verificação de domínio que garante que o link pertence ao aplicativo, aumentando a segurança.

O snippet de código a seguir mostra um exemplo de filtro de links do app android:

<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="http" />
    <data android:scheme="https" />

    <data android:host="..." />
</intent-filter>

Note que agora no intent-filter tem o android:autoVerify=true, esse trecho de código é responsável por fazer a filtragem automática do link e entrar automaticamente no app sem a necessidade de abrir uma caixa de diálogo de desambiguação

Como funciona:

• Quando um link é clicado, o Android verifica se o domínio é verificado para aquele aplicativo (através do arquivo assetlinks.json).

• Se o app for confiável para aquele link, ele abrirá diretamente o conteúdo no app.

• Caso o app não esteja instalado, o link abrirá no navegador sem exibir uma caixa de diálogo para escolha.

Exemplo:

Um link como:

https://www.seusite.com/produto/123

abriria diretamente no aplicativo, se configurado e o domínio verificado, ou no navegador se o app não estiver instalado.

Vantagens:

• Elimina a tela de escolha, garantindo uma experiência mais fluida.

• Verificação de domínio proporciona maior segurança e controle.

Desvantagens:

• Requer verificação de domínio e configuração extra para funcionar corretamente.

Arquivo assetlinks.json

O arquivo assetlinks.json é essencial para que o Android reconheça que seu aplicativo é autorizado a abrir links do seu domínio. Ele define a relação entre o aplicativo e o site, incluindo as permissões para manusear URLs do domínio.

Conteúdo do arquivo assetlinks.json:

jsonCopiar código[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.seuapp.flutter",
      "sha256_cert_fingerprints": [
        "A1:B2:C3:D4:...:F5"
      ]
    }
  }
]

• relation: Define que o aplicativo pode manipular todos os URLs (common.handle_all_urls).

• namespace: Define que a aplicação é do tipo android_app.

• package_name: Nome do pacote do seu aplicativo Android.

• sha256_cert_fingerprints: Certificado SHA-256 da assinatura do aplicativo. Esse é um dado necessário para garantir que apenas o seu aplicativo possa responder a esses links.

Obtendo o SHA-256 Certificado

Para obter o SHA-256, execute um dos seguintes comandos no terminal (Linux ou Mac) ou no prompt de comando (Windows) dentro da pasta android do seu app flutter:

keytool -list -v -alias <your-key-alias> -keystore <path-to-your-keystore> | grep 'SHA256'

• <your-key-alias>: Alias da chave de assinatura do seu aplicativo.

• <path-to-your-keystore>: O caminho para o seu arquivo .keystore.

./gradlew signingReport

Após a execução, você verá o fingerprint SHA-256 que deverá ser inserido no arquivo assetlinks.json.

Configurando o Firebase Hosting para hospedar o assetlinks.json

Se você estiver utilizando o Firebase Hosting, o próximo passo é hospedar o arquivo assetlinks.json no caminho correto.

Passos:

1. Instalar as Ferramentas do Firebase CLI: Se ainda não tiver instalado o Firebase CLI, faça isso com o seguinte comando:

    npm install -g firebase-tools
   

2. Iniciar o Firebase Hosting: No diretório do seu projeto, inicialize o Firebase Hosting:

    firebase init hosting
   

   Isso irá gerar um conjunto de arquivos no diretório, incluindo firebase.json e uma pasta public.

3. Adicionar o arquivo assetlinks.json no diretório correto: O arquivo assetlinks.json deve ser hospedado no diretório .well-known, que deve estar localizado na raiz do seu site. Crie esse diretório dentro da pasta public:

   No terminal:

    mkdir -p public/.well-known
   

   Em seguida, adicione o arquivo assetlinks.json criado anteriormente dentro desse diretório:

    /public/.well-known/assetlinks.json
   

4. Fazendo o Deploy no Firebase Hosting: Após configurar o arquivo assetlinks.json no diretório correto, faça o deploy do site para o Firebase Hosting:

    firebase deploy --only hosting
   

5. Verificando a URL do assetlinks.json: Após o deploy, você pode verificar se o arquivo foi hospedado corretamente acessando:

    https://www.seudominio.com/.well-known/assetlinks.json
   

   Certifique-se de que o arquivo esteja acessível publicamente e o conteúdo está correto.

Configurando o Android App Links

Agora que o assetlinks.json está hospedado, você precisa garantir que o Android App Links está configurado no seu aplicativo. Já mostramos como configurar o AndroidManifest.xml, então agora você pode testar o comportamento.

Testando o App Links no Android

Para verificar se o deep link e o App Link estão funcionando corretamente:

• Teste Localmente com o ADB: Você pode testar seu deep link diretamente no dispositivo conectado com o comando ADB:

    adb shell am start -W -a android.intent.action.VIEW -d "https://www.seudominio.com/produto/123" com.seuapp.flutter
  

  Isso abrirá o aplicativo diretamente na tela do produto, assumindo que a configuração está correta.

• Verifique a Associação do Domínio: Se o link estiver associado corretamente, o Android abrirá o aplicativo sem perguntar ao usuário se ele deseja abrir no navegador ou no aplicativo.

Usando go_router para lidar com deep links

O go_router é uma excelente biblioteca para gerenciar rotas no Flutter, especialmente quando se trabalha com deep links. Abaixo está um exemplo de como configurar as rotas e lidar com os parâmetros de deep links:

final GoRouter _router = GoRouter(
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => HomeScreen(),
    ),
    GoRoute(
      path: '/produto/:id',
      builder: (context, state) {
        final String? id = state.params['id'];
        return ProdutoScreen(id: id);
      },
    ),
  ],
);

@override
Widget build(BuildContext context) {
  return MaterialApp.router(
    routerConfig: _router,
  );
}

Aqui, você define uma rota dinâmica /produto/:id, onde o id será extraído da URL quando o deep link for acessado.

Conclusão

Neste artigo, exploramos como implementar deep links no Android com Flutter, destacando os tipos de links: Deep Links, Web Links e Android App Links. Também abordamos a configuração do arquivo assetlinks.json, hospedado no Firebase Hosting para verificação de domínio, garantindo que seu app Android seja reconhecido como responsável por abrir links do seu site. Além disso, mostramos como configurar o AndroidManifest.xml e utilizar o go_router em Flutter para gerenciar o roteamento. Com isso, você melhora a navegação do usuário e a integração entre web e aplicativo.