Forem: Cristian Dornelles

Checkpoint da Série: o que já funciona, o que quebrou e para onde vamos (Parte 4.5)

Cristian Dornelles — Tue, 14 Apr 2026 17:26:53 +0000

Quatro posts, três plataformas, um bug encontrado em produção.

Antes de seguir para App Links e Universal Links no ar de verdade — com domínio, verificação bidirecional e os problemas que só aparecem fora do emulador — vale um respiro para ver o que já existe e o que ainda falta.

O que construímos até aqui

Post 1 — A fundação conceitual

Tipos de deep link, diferenças entre custom scheme, App Links e Universal Links, e a estrutura base em Dart. Nada de pacote externo — só entender o problema antes de escrever código.

Parte 1 — O Guia para Iniciantes

Post 2 — Android nativo

AndroidManifest.xml com intent-filter para custom scheme e HTTPS. MainActivity.kt registrando os canais nativos — MethodChannel para cold start, EventChannel para app em execução.

Parte 2 — Android com Kotlin

Post 3 — iOS nativo

Info.plist com CFBundleURLTypes, Runner.entitlements com Associated Domains e AppDelegate.swift espelhando a mesma lógica de canais do Android.

Parte 3 — iOS com Swift

Post 4 — Integração Flutter

O DeepLinkService como ponto único de entrada: MethodChannel busca o link inicial, EventChannel recebe links com o app aberto, StreamController.broadcast() distribui para quem estiver ouvindo. A SignupPage pré-preenche o referral code e mostra um indicador visual quando o dado veio de um link.

Parte 4 — Integração Flutter

O bug que encontramos na prática

Durante os testes do Post 4, o app abria normalmente mas o referral code nunca aparecia. Nenhum erro, nenhum log — o deep link simplesmente sumia.

A causa: race condition com StreamController.broadcast().

O problema na prática

// ❌ como estava — evento perdido
await service.initialize(); // link emitido aqui...
_deepLinkSub = service.deepLinkStream.listen(...); // listener registrado tarde demais

// ✅ como ficou — listener primeiro
_deepLinkSub = service.deepLinkStream.listen(...); // ouvindo antes de qualquer evento
await service.initialize(); // link emitido com listener ativo

O broadcast() não bufferiza. Se nenhum listener estiver ativo no momento em que o evento é emitido, ele se perde. A ordem importa.

Esse é o tipo de bug que não aparece em log, não quebra o app, e passa despercebido até produção.

Onde estamos agora

O fluxo ponta a ponta já funciona:

Android → captura o intent corretamente
iOS → captura a URL corretamente
Flutter → recebe via MethodChannel / EventChannel e processa
UI → reage ao deep link com o referral code pré-preenchido

Mas ainda falta o mais difícil: fazer isso funcionar fora do ambiente de desenvolvimento.

Código completo: FitConnect no GitHub — branch post/04-flutter.

Para onde vamos

Post 5 — Produção de verdade

App Links no Android e Universal Links no iOS exigem verificação bidirecional de domínio. Sem isso, o link abre no navegador em vez do app. Vamos configurar o assetlinks.json e o apple-app-site-association, entender o que o sistema verifica e o que fazer quando a verificação falha.

Post 6 — Deferred Deep Links

O usuário clica no link mas não tem o app instalado. Vai para a loja, instala, abre — e o referral code sumiu. O deferred deep link resolve isso. Vamos implementar com LocalStorage no lado web e uma estratégia simples no backend.

Post 7 — Página de redirect inteligente

Uma página HTML que detecta a plataforma, tenta abrir o app, e redireciona para a loja se não conseguir. O elo que conecta o link compartilhado ao app instalado.

Post 8 — Testes e troubleshooting

Checklist de deploy, como testar cada cenário (cold start, app aberto, link inválido), e os erros mais comuns com App Links e Universal Links — incluindo os que só aparecem depois do deploy.

Post 9 — Refatoração com Clean Architecture

O DeepLinkHandler como alternativa ao DeepLinkService atual — separando responsabilidades, facilitando testes e preparando o código para crescer sem virar bagunça.

Se você chegou agora, os quatro primeiros posts constroem a fundação do zero. Se acompanhou desde o início, os próximos cinco levam para produção — com os problemas reais que aparecem quando o domínio precisa estar verificado e o usuário ainda não tem o app.

Código completo disponível no repositório: FitConnect no GitHub

Se esse conteúdo te ajudou, deixa um ❤️ ou um 🔖 aqui no DEV.to — isso ajuda o post a alcançar mais devs.

E você, já implementou deep links no seu app?

Qual foi o maior desafio que encontrou?

Quero usar esses casos reais nos próximos posts da série 👇

Tags: Flutter, Dart, MethodChannel, Deep Links, Mobile Development

Conectando Tudo: Integração Flutter com Deep Links Nativos (Parte 4)

Cristian Dornelles — Sat, 11 Apr 2026 14:23:51 +0000

Se você já tentou integrar deep links no Flutter usando código nativo, provavelmente passou por isso:

o Android recebe o link…

o iOS também…

mas o Flutter simplesmente não reage.

Ou pior:
funciona no cold start… mas não funciona com o app aberto.

É exatamente esse problema que vamos resolver agora.

Dando continuidade à série sobre Deep Links no Flutter, com novos artigos saindo semanalmente, ou quase. Se você ainda não viu os posts anteriores: Post 1 — Guia para Iniciantes | Post 2 — Android com Kotlin | Post 3 — iOS com Swift.

Neste artigo, você vai aprender:

Como implementar DeepLinkService com MethodChannel e EventChannel no Flutter.
Por que usar StreamController.broadcast() para eventos de deep link.
Como pré-preencher a UI automaticamente a partir de um link.

DeepLinkService no Flutter

A solução é ter um ponto único de entrada para todos os deep links no app — o DeepLinkService. Ele fala com o código nativo em dois momentos distintos:

Via MethodChannel: quando o app abre e precisamos saber se havia um link pendente (app estava fechado).
Via EventChannel: stream contínuo para links recebidos enquanto o app já está em execução.

// lib/services/deep_link_service.dart

import 'dart:async';
import 'dart:io';
import 'package:flutter/services.dart';

class DeepLinkService {
  static final DeepLinkService _instance = DeepLinkService._internal();
  factory DeepLinkService() => _instance;
  DeepLinkService._internal();

  final MethodChannel _methodChannel =
      const MethodChannel('com.fitconnect.app/deeplink');

  final EventChannel _eventChannel =
      const EventChannel('com.fitconnect.app/deeplink_stream');

  final StreamController<DeepLinkData> _controller =
      StreamController.broadcast();

  bool _initialized = false;

  Stream<DeepLinkData> get deepLinkStream => _controller.stream;

  Future<void> initialize() async {
    if (_initialized) return;
    _initialized = true;

    // Busca deep link inicial (app estava fechado)
    final String? initialUrl =
        await _methodChannel.invokeMethod('getInitialLink');

    if (initialUrl != null) {
      final data = _parseDeepLink(initialUrl);
      if (data != null) _controller.add(data);
    }

    // Stream para links quando app está aberto
    _eventChannel
      .receiveBroadcastStream()
      .listen(
        (url) {
          if (url is String) {
            final data = _parseDeepLink(url);
            if (data != null) _controller.add(data);
          }
        },
        onError: (error) {
          // Log ou tratamento
        },
        cancelOnError: false,
      );
  }

  DeepLinkData? _parseDeepLink(String url) {
    try {
      final uri = Uri.parse(url);

      return DeepLinkData(
        url: url,
        type: _determineType(uri),
        scheme: uri.scheme,
        host: uri.host,
        path: uri.path,
        queryParameters: uri.queryParameters,
        referralCode: uri.queryParameters['referralCode'],
        receivedAt: DateTime.now(),
      );
    } catch (e) {
      return null;
    }
  }

  DeepLinkType _determineType(Uri uri) {
    if (uri.scheme == 'fitconnect') return DeepLinkType.customScheme;
    if (uri.scheme == 'https' && uri.host == 'fitconnect.app') {
      return Platform.isIOS ? DeepLinkType.universalLink : DeepLinkType.appLink;
    }
    return DeepLinkType.unknown;
  }
}

Como esse controller vive durante todo o ciclo de vida do app, não fazemos o close manual — mas em serviços descartáveis isso seria obrigatório.

Esse padrão também facilita testes e evolução futura (ex: analytics, tracking, feature flags baseadas em deep link).

Mas mais importante do que isso -

na prática, o DeepLinkService funciona como uma camada de tradução:

Ele isola completamente o restante da aplicação da complexidade de cada plataforma.

Por que StreamController.broadcast()?

Um StreamController padrão só permite um listener. Se o app tiver múltiplas telas ouvindo deep links ao mesmo tempo — ou se o listener for registrado após o evento ser emitido — o evento se perde. O .broadcast() resolve os dois problemas: aceita múltiplos listeners e não lança exceção se nenhum estiver ativo no momento do evento.

A responsabilidade de cada canal

O _methodChannel faz uma chamada pontual — getInitialLink — e retorna uma vez. É o suficiente para o cenário de cold start. Já o _eventChannel permanece aberto como um stream; qualquer link recebido com o app em execução chega por ele. Juntos, cobrem todos os cenários sem sobreposição.

O método _parseDeepLink

Uri.parse decompõe a URL em partes (scheme, host, path, queryParameters) sem nenhuma dependência externa. A partir daí, montamos o DeepLinkData com os campos que o app vai precisar — incluindo o referralCode extraído diretamente dos query parameters. Se a URL for inválida, o método retorna null e o link é ignorado silenciosamente.

Evitando processamento duplicado no Flutter

Dependendo da plataforma, o mesmo deep link pode chegar mais de uma vez (especialmente em cold start).

Uma estratégia simples é manter o último link processado e ignorar duplicados —
principalmente em cenários onde o mesmo evento pode chegar via MethodChannel e EventChannel.

Integrando no ciclo de vida do app

Com o DeepLinkService pronto, a integração acontece no widget raiz do app.

É aqui que conectamos o serviço ao ciclo de vida da aplicação.

// lib/app_widget.dart

class _AppState extends State<App> {
  StreamSubscription? _deepLinkSub;

  @override
  void initState() {
    super.initState();
    _initDeepLinks();
  }

  Future<void> _initDeepLinks() async {
    final service = DeepLinkService();

    // Listener registrado antes de initialize() para não perder
    // o evento de cold start emitido durante a inicialização
    _deepLinkSub = service.deepLinkStream.listen((data) {
      if (data.path == '/signup' && data.referralCode != null) {
        _handleSignupLink(data);
      }

    await service.initialize();
    });
  }

  void _handleSignupLink(DeepLinkData data) {
    WidgetsBinding.instance.addPostFrameCallback((_) {
      Navigator.pushNamed(context, '/signup');
    });

    Future.delayed(const Duration(milliseconds: 500), () {
      final controller = context.read<SignupController>();
      controller.setReferralCode(data.referralCode!);
    });
  }

  @override
  void dispose() {
    _deepLinkSub?.cancel();
    super.dispose();
  }
}

Atenção: a ordem importa

Repare que o listener é registrado antes de chamar initialize(). Isso não é acidente.

O StreamController.broadcast() não bufferiza eventos — se nenhum listener estiver ativo no momento em que o evento é emitido, ele se perde silenciosamente. E o initialize() pode emitir o link inicial (cold start) ainda durante sua execução.

Se você inverter a ordem:

// ❌ errado — o evento de cold start é perdido
await service.initialize(); // evento emitido aqui...
_deepLinkSub = service.deepLinkStream.listen(...); // ...mas o listener só existe aqui

O app abre, o link chega no Android/iOS, mas o Flutter nunca reage. Nenhum erro, nenhum log — o deep link simplesmente some.

O uso de Future.delayed aqui é uma simplificação didática. Em produção, o ideal é desacoplar navegação e estado — via state management (MobX, Bloc, etc.) ou via evento disparado após o build da tela. Isso elimina dependência de timing arbitrário e condições de corrida entre navegação e UI.

O StreamSubscription precisa ser cancelado no dispose para evitar memory leaks. Como o widget raiz raramente é removido da árvore, na prática isso raramente é acionado — mas é uma boa prática que vale manter.

UI da SignupPage

A última peça é a tela de cadastro. O campo de referral code precisa de uma decisão de UX clara: mostrar ao usuário que o dado veio de um link, mas permitir que ele edite se quiser.

// lib/features/signup/signup_page.dart

TextField(
  controller: controller.referralCodeController,
  decoration: InputDecoration(
    labelText: controller.cameFromDeepLink
        ? 'Código de Indicação (via link)'
        : 'Código de Indicação (opcional)',
    suffixIcon: controller.cameFromDeepLink
        ? const Icon(Icons.link, color: Colors.green)
        : null,
  ),
  maxLength: 20,
  enabled: true, // Sempre editável
)

O campo é sempre editável — mesmo quando pré-preenchido por deep link. O label e o ícone mudam para dar contexto ao usuário, mas nunca bloqueamos a edição. Travar o campo criaria fricção desnecessária: e se o usuário cometeu um erro no código de indicação ou quer usar outro?

Fluxo completo

A partir daqui, o deep link deixa de ser um detalhe técnico.

Ele passa a ser parte da experiência do usuário.

O app não apenas abre.

Ele entende o contexto.

No próximo post, vamos sair do ambiente de desenvolvimento e ir para produção:

App Links funcionando de verdade no Android
Universal Links validados no iOS
Verificação bidirecional com domínio

É aqui que começam os problemas reais de produção:

domínio não verificado corretamente
link abrindo no navegador em vez do app
comportamento inconsistente entre Android e iOS

E é exatamente isso que vamos resolver.

O que construímos até aqui

Ao final desta etapa, você já tem:

O DeepLinkService como ponto único de entrada para deep links no Flutter.
Integração com MethodChannel (cold start) e EventChannel (app em execução).
Roteamento automático para a SignupPage com o referral code pré-preenchido.
A decisão de UX de manter o campo sempre editável, com indicador visual de origem.

Este é o quarto de 9 posts da série. Com Android, iOS e Flutter integrados, o fluxo ponta a ponta já funciona — mas ainda em ambiente de desenvolvimento. No próximo post, vamos colocar isso em produção: configurar App Links no Android e Universal Links no iOS com verificação bidirecional de domínio. Se você já teve dor de cabeça com essa etapa, conta nos comentários — vou usar isso no Post 5.

Código completo disponível no repositório: FitConnect no GitHub

Se esse conteúdo te ajudou, deixa um ❤️ ou um 🔖 aqui no DEV.to — isso ajuda o post a alcançar mais devs.

E você, já implementou deep links no seu app?

Qual foi o maior desafio que encontrou?

Quero usar esses casos reais nos próximos posts da série 👇

Tags: Flutter, Dart, MethodChannel, Deep Links, Mobile Development

Deep Links no iOS: Implementação Nativa com Swift + Flutter (Parte 3)

Cristian Dornelles — Wed, 08 Apr 2026 12:38:20 +0000

No post anterior, configuramos o Android para capturar deep links usando Kotlin. Agora é a vez do iOS — e você vai ver como a implementação em Swift pode ficar bastante limpa.

Dando continuidade à série sobre Deep Links no Flutter, agora vamos implementar o fluxo nativo no iOS. Se você ainda não viu os posts anteriores, recomendo começar por aqui: Post 1 — Guia para Iniciantes | Post 2 — Android com Kotlin.

Neste artigo, você vai aprender:

Como configurar Info.plist e Associated Domains para deep links.
A diferença entre custom schemes e Universal Links no iOS.
Como implementar AppDelegate.swift com FlutterMethodChannel e FlutterEventChannel.

Configurando o Info.plist

No iOS, o registro de um custom scheme é feito no Info.plist, por meio da chave CFBundleURLTypes. É aqui que o sistema operacional aprende que links com o scheme fitconnect:// devem abrir este app.

<!-- ios/Runner/Info.plist -->

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.fitconnect.app</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>fitconnect</string>
        </array>
    </dict>
</array>

CFBundleURLSchemes é o que de fato registra o scheme. O CFBundleURLName é um identificador interno — por convenção, usa-se o bundle ID reverso. O CFBundleTypeRole como Editor indica que o app não apenas lê o tipo de URL, mas também pode criar links com esse scheme.

Configurando Universal Links

Universal Links exigem um passo a mais: o app precisa declarar quais domínios ele está autorizado a tratar. Essa declaração vai no arquivo Runner.entitlements, sob a chave com.apple.developer.associated-domains.

<!-- ios/Runner/Runner.entitlements -->

<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:fitconnect.app</string>
</array>

O prefixo applinks: é obrigatório — é ele que instrui o iOS a tratar o domínio como Universal Link. Sem ele, o sistema ignora a entrada. A verificação bidirecional (o arquivo apple-app-site-association no servidor) será montada no Post 5.

Implementando o AppDelegate.swift

Com a configuração pronta, o iOS entrega os links ao AppDelegate. Diferente do Android, onde a entrada costuma ser centralizada em torno do Intent, no iOS o link pode chegar por caminhos diferentes: no cold start via launchOptions, por custom schemes via open url e por Universal Links via continue userActivity.

import Flutter
import UIKit

@main
@objc class AppDelegate: FlutterAppDelegate {

    private let CHANNEL = "com.fitconnect.app/deeplink"
    private let EVENT_CHANNEL = "com.fitconnect.app/deeplink_stream"

    private var methodChannel: FlutterMethodChannel?
    private var eventChannel: FlutterEventChannel?
    private var eventSink: FlutterEventSink?

    private var initialLink: String?
    private var lastProcessedLink: String?

    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

        let controller = window?.rootViewController as! FlutterViewController
        setupChannels(controller: controller)

        // Captura deep link inicial (cold start)
        if let url = launchOptions?[.url] as? URL {
            handleDeepLink(url: url, isInitial: true)
        } else if
            let userActivityDictionary = launchOptions?[.userActivityDictionary] as? [AnyHashable: Any] {
            for value in userActivityDictionary.values {
                if let userActivity = value as? NSUserActivity,
                   userActivity.activityType == NSUserActivityTypeBrowsingWeb,
                   let url = userActivity.webpageURL {
                    handleDeepLink(url: url, isInitial: true)
                    break
                }
            }
        }

        GeneratedPluginRegistrant.register(with: self)
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }

    private func setupChannels(controller: FlutterViewController) {
        // MethodChannel: Flutter pede o deep link inicial
        methodChannel = FlutterMethodChannel(
            name: CHANNEL,
            binaryMessenger: controller.binaryMessenger
        )
        methodChannel?.setMethodCallHandler { [weak self] call, result in
            if call.method == "getInitialLink" {
                result(self?.initialLink)
            } else {
                result(FlutterMethodNotImplemented)
            }
        }

        // EventChannel: stream de deep links em tempo real enquanto o app está em execução
        eventChannel = FlutterEventChannel(
            name: EVENT_CHANNEL,
            binaryMessenger: controller.binaryMessenger
        )
        eventChannel?.setStreamHandler(self)
    }

    // Custom URL Scheme
    override func application(
        _ app: UIApplication,
        open url: URL,
        options: [UIApplication.OpenURLOptionsKey : Any] = [:]
    ) -> Bool {
        handleDeepLink(url: url, isInitial: false)
        return super.application(app, open: url, options: options)
    }

    // Universal Links
    override func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
              let url = userActivity.webpageURL else {
            return false
        }

        handleDeepLink(url: url, isInitial: false)
        return true
    }

    private func handleDeepLink(url: URL, isInitial: Bool) {
        let urlString = url.absoluteString

        // Evita processar o mesmo link duas vezes
        if urlString == lastProcessedLink { return }

        lastProcessedLink = urlString
        NSLog("Deep link: \(urlString)")

        if isInitial {
            initialLink = urlString
        } else {
            eventSink?(urlString)
        }
    }
}

extension AppDelegate: FlutterStreamHandler {
    func onListen(
        withArguments arguments: Any?,
        eventSink events: @escaping FlutterEventSink
    ) -> FlutterError? {
        self.eventSink = events
        return nil
    }

    func onCancel(withArguments arguments: Any?) -> FlutterError? {
        self.eventSink = nil
        return nil
    }
}

Por que dois métodos de entrada?

open url: chamado quando o link usa um custom scheme (fitconnect://). O iOS já sabe que é para abrir o app porque o scheme foi registrado no Info.plist.
continue userActivity: chamado para Universal Links (HTTPS). O iOS só chega aqui após confirmar que o domínio está no Runner.entitlements e que o servidor possui o arquivo apple-app-site-association. Se qualquer verificação falhar, o link abre no Safari como fallback — sem erros, sem seletor.

Por que o AppDelegate adota FlutterStreamHandler via extension?

Em vez de criar uma classe separada para o stream handler, o próprio AppDelegate implementa o protocolo FlutterStreamHandler via extension. Isso mantém o código coeso: tudo relacionado à entrega de links fica no mesmo lugar. O onListen guarda a referência para o eventSink, e o onCancel a limpa quando o Flutter para de ouvir.

Testando no iOS

Para testar sem precisar de um device físico, o simulador do Xcode expõe o comando xcrun simctl openurl.

# Custom scheme — não requer verificação de domínio
xcrun simctl openurl booted \
  "fitconnect://fitconnect.app/signup?referralCode=TRAINER1234567890123"

# Universal Link (HTTPS)
xcrun simctl openurl booted \
  "https://fitconnect.app/signup?referralCode=TRAINER1234567890123"

Atenção: testar Universal Links no iOS pode ser enganoso. Em muitos casos, abrir a URL diretamente no Safari não reproduz o comportamento real de associação com o app. Para validar corretamente, prefira tocar no link a partir de apps como Mail, Notas ou iMessage.

Android vs iOS: comparação rápida

A lógica é a mesma nas duas plataformas — o que muda são as APIs e os arquivos de configuração. O handleDeepLink no Swift é o equivalente direto do handleIntent no Kotlin.

O que construímos até aqui

Ao final desta etapa, você já tem:

O Info.plist configurado para custom schemes.
O Runner.entitlements com o domínio para Universal Links.
O AppDelegate.swift com FlutterMethodChannel (link inicial) e FlutterEventChannel (stream em tempo real).
Clareza sobre a diferença entre open url e continue userActivity e quando cada um é chamado.
Comandos xcrun simctl prontos para testar no simulador.

Este é o terceiro de 9 posts da série. Com Android e iOS prontos, temos o código nativo completo das duas plataformas. Se você já passou por algum problema com Universal Links — domínio não verificado, link abrindo no Safari em vez do app — conta nos comentários, esse tipo de detalhe vai direto para os próximos artigos.

No próximo post, conectamos tudo no Flutter: o DeepLinkService em Dart que fala com o código nativo via MethodChannel e EventChannel.

Código completo disponível no repositório: FitConnect no GitHub

Se esse conteúdo te ajudou, deixa um ❤️ ou um 🔖 aqui no DEV.to — isso ajuda o post a alcançar mais devs.

E você, já implementou deep links no seu app?

Qual foi o maior desafio que encontrou?

Quero usar esses casos reais nos próximos posts da série 👇

Tags: Flutter, iOS, Swift, Universal Links, Deep Links

Deep Links no Android: Implementação Nativa com Kotlin + Flutter (Parte 2)

Cristian Dornelles — Mon, 06 Apr 2026 13:58:31 +0000

No post anterior, preparamos a base — constantes, enum de tipos e modelo de dados. Agora é hora de sujar as mãos com código nativo. Vamos configurar o Android para capturar deep links e entregá-los ao Flutter — sem nenhum pacote externo no meio do caminho.

Spoiler: é mais simples do que parece — mas alguns detalhes fazem toda a diferença na prática.

Dando continuidade à série sobre Deep Links no Flutter, com novos artigos saindo semanalmente, ou quase. Se você ainda não viu a base do projeto em Flutter, recomendo começar pelo primeiro artigo da série: Post 1 — Guia para Iniciantes.

Neste artigo, você vai aprender:

Como configurar o AndroidManifest.xml para deep links.
A diferença entre MethodChannel e EventChannel.
Como testar com adb sem precisar de um dispositivo físico.

Configurando o AndroidManifest.xml

O Android descobre que seu app pode tratar um link por meio de intent-filters declarados no AndroidManifest.xml. Podemos declarar dois intent-filters separados (um para custom scheme e outro para HTTPS) ou um único filtro com múltiplos <data>. Neste exemplo, vamos manter separados para maior clareza didática.

<!-- android/app/src/main/AndroidManifest.xml -->
<activity
    android:name=".MainActivity"
    android:launchMode="singleTop"
    ...>

    <!-- Intent filter padrão (launcher) -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.LAUNCHER"/>
    </intent-filter>

    <!-- Deep Link: Custom Scheme -->
    <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="fitconnect" />
        <data android:host="fitconnect.app" />
    </intent-filter>

    <!-- Deep Link: HTTPS (App 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" />
        <data android:host="fitconnect.app" />
        <data android:pathPrefix="/signup" />
    </intent-filter>
</activity>

Três atributos merecem atenção:

android:launchMode="singleTop": evita criar uma nova instância da Activity quando ela já está no topo da stack, direcionando o novo intent para onNewIntent. Sem isso, o usuário poderia acabar com múltiplas instâncias da mesma Activity na stack.
BROWSABLE: autoriza que links externos — de um e-mail, mensagem ou navegador — possam abrir o app. Sem essa categoria, o intent-filter é invisível para o sistema.
android:autoVerify="true": ativa a verificação bidirecional do App Links. O Android vai checar se o servidor confirma que este app tem permissão para tratar o domínio. Montamos esse arquivo de verificação no Post 5.

Implementando o MainActivity.kt

Com o manifest configurado, o Android vai entregar o link como um Intent para a MainActivity. Agora precisamos capturá-lo e repassar ao Flutter via dois canais:

MethodChannel: Flutter chama quando o app abre e precisa saber se havia um link pendente.
EventChannel: stream contínuo para links recebidos com o app já em execução.

package com.fitconnect.app

import android.content.Intent
import android.net.Uri
import android.os.Bundle
import android.util.Log
import io.flutter.embedding.android.FlutterFragmentActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.EventChannel
import io.flutter.plugin.common.MethodChannel

class MainActivity : FlutterFragmentActivity() {
    private val TAG = "FitConnect"
    private val CHANNEL = "com.fitconnect.app/deeplink"
    private val EVENT_CHANNEL = "com.fitconnect.app/deeplink_stream"

    private var methodChannel: MethodChannel? = null
    private var eventChannel: EventChannel? = null
    private var eventSink: EventChannel.EventSink? = null

    private var initialLink: String? = null
    private var lastProcessedLink: String? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Log.d(TAG, "onCreate - checking for deep link")
        handleIntent(intent, isInitial = true)
    }

    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)

        // MethodChannel: Flutter pede deep link inicial
        methodChannel = MethodChannel(
            flutterEngine.dartExecutor.binaryMessenger,
            CHANNEL
        )
        methodChannel?.setMethodCallHandler { call, result ->
            when (call.method) {
                "getInitialLink" -> result.success(initialLink)
                else -> result.notImplemented()
            }
        }

        // EventChannel: Stream de deep links em tempo real
        eventChannel = EventChannel(
            flutterEngine.dartExecutor.binaryMessenger,
            EVENT_CHANNEL
        )
        eventChannel?.setStreamHandler(object : EventChannel.StreamHandler {
            override fun onListen(args: Any?, events: EventChannel.EventSink?) {
                eventSink = events
            }
            override fun onCancel(args: Any?) {
                eventSink = null
            }
        })
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        Log.d(TAG, "onNewIntent - app was already open")
        handleIntent(intent, isInitial = false)
    }

    private fun handleIntent(intent: Intent?, isInitial: Boolean) {
        val data: Uri? = intent?.data

        if (intent?.action == Intent.ACTION_VIEW && data != null) {
            val deepLinkUrl = data.toString()

            // Evita processar o mesmo link duas vezes
            if (deepLinkUrl == lastProcessedLink) return

            lastProcessedLink = deepLinkUrl
            Log.i(TAG, "Deep link: $deepLinkUrl")

            if (isInitial) {
                // App estava fechado
                initialLink = deepLinkUrl
            } else {
                // App estava aberto — envia via stream
                eventSink?.success(deepLinkUrl)
            }
        }
    }
}

O que acontece em cada cenário

O fluxo de entrega do link depende de como o app foi aberto:

O lastProcessedLink existe para um caso específico: em algumas versões do Android, onCreate e onNewIntent podem ser chamados em sequência para o mesmo link. Sem essa proteção, o Flutter processaria o mesmo deep link duas vezes.

Testando com adb

Antes de integrar com o Flutter, vale confirmar que o Android está capturando os links corretamente. O adb permite simular cliques em links diretamente pelo terminal.

# Testa o custom scheme (fitconnect://)
# Deve abrir o app sem precisar de verificação de domínio
adb shell am start -a android.intent.action.VIEW \
  -d "fitconnect://fitconnect.app/signup?referralCode=TRAINER1234567890123"

# Testa o App Link (HTTPS)
# Pode abrir um seletor de aplicativos se a verificação do domínio ainda não estiver concluída
adb shell am start -a android.intent.action.VIEW \
  -d "https://fitconnect.app/signup?referralCode=TRAINER1234567890123"

Se o custom scheme abrir o app, o manifest está correto. Se o HTTPS mostrar um seletor de aplicativos em vez de abrir direto — é sinal de que a verificação bidirecional ainda não está configurada. Isso é esperado neste ponto da série e será resolvido no Post 5.

O que construímos até aqui

Ao final desta etapa, você já tem:

O AndroidManifest configurado com os dois intent-filters: custom scheme e App Links.
O MainActivity.kt com MethodChannel (link inicial) e EventChannel (stream em tempo real).
Clareza sobre a diferença entre onCreate e onNewIntent e por que ambos precisam ser tratados.
Comandos adb prontos para testar sem precisar de dispositivo físico.

Este é o segundo de 9 posts da série. Se você já passou por alguma situação estranha com intent-filters no Android, conta nos comentários — esse tipo de detalhe vai direto para os próximos artigos.

Na próxima etapa, vamos replicar esse fluxo no iOS usando Swift — e você vai perceber como os conceitos são os mesmos, mesmo com APIs diferentes.

Código completo disponível no repositório: FitConnect no GitHub

Se esse conteúdo te ajudou, deixa um ❤️ ou um 🔖 aqui no DEV.to — isso ajuda o post a alcançar mais devs.

E você, já implementou deep links no seu app?

Qual foi o maior desafio que encontrou?

Quero usar esses casos reais nos próximos posts da série 👇

Tags: Flutter, Android, Kotlin, Deep Links, Mobile Development

Deep Links em Flutter: O Guia Definitivo para Iniciantes (Sem Pacotes de Terceiros) (Parte 1)

Cristian Dornelles — Sat, 04 Apr 2026 18:59:27 +0000

Imagine isso: seu usuário recebe um link de desconto, clica nele — e BOOM! Ele não só abre seu app, mas já está na tela de checkout com o cupom aplicado. Isso é mágica? Não — são Deep Links!

Este é o primeiro conteúdo de uma série completa sobre Deep Links no Flutter, com novos artigos saindo semanalmente, ou quase. Vamos entender os conceitos fundamentais, explorar os diferentes tipos e preparar a estrutura base do nosso projeto do zero, sem depender de pacotes de terceiros.

Ao longo desta série, vou te mostrar como implementar deep links em Flutter — sem utilizar pacotes prontos. Por quê? Porque você vai aprender exatamente como tudo funciona por baixo dos panos.

Neste artigo, você vai aprender:

O que são deep links.
Diferença entre App Links e Custom Schemes.
Como estruturar a base no Flutter.

O que são Deep Links?

Deep links são URLs que levam o usuário diretamente para uma tela específica do seu app, em vez de abrir no navegador.

Exemplo real:

Fluxo tradicional: Abre navegador → usuário instala o app → abre → navega até a tela.
Deep link: Abre o app diretamente na tela correta.

Para termos uma visão completa, o diagrama abaixo ilustra o roteamento (conhecido como Deferred Deep Linking), onde — até mesmo se o usuário não tiver o app — o contexto do link é preservado após ele passar pelas lojas de apps:

Fluxo completo

Esse fluxo completo, onde o usuário pode instalar o app e ainda assim manter o contexto original do link, é o que chamamos de Deferred Deep Linking.

Anatomia de um Deep Link

https://fitconnect.app/signup?referralCode=TRAINER12345

Scheme: https
Host: fitconnect.app
Path: /signup
Query: ?referralCode=TRAINER12345

Cada parte dessa estrutura tem um papel específico na navegação. O scheme identifica o protocolo (ou, no caso de custom schemes, o aplicativo), o host e o path determinam a rota, e os query parameters carregam dados extras (como um código de indicação — referralCode).

Tipos de Deep Links

Existem dois tipos principais e a escolha entre eles tem implicações diretas na segurança e na experiência do usuário.

Custom Schemes (`fitconnect://`)

fitconnect://fitconnect.app/signup?referralCode=TRAINER12345

✅ Rápido de implementar.
✅ Ótimo para testes locais.
⚠️ Menos seguro — qualquer aplicativo pode registrar o mesmo scheme.
⚠️ Se o app não estiver instalado, o sistema exibe um erro feio.

App Links (Android) / Universal Links (iOS)

https://fitconnect.app/signup?referralCode=TRAINER12345

✅ Seguro — verificação bidirecional entre aplicativo e servidor.
✅ Se o app não estiver instalado, abre normalmente no navegador.
✅ Recomendado para produção.
⚠️ Requer domínio próprio.
⚠️ Setup mais complexo.

O que é essa verificação bidirecional? O sistema operacional só abre o app se ambas as pontas se reconhecerem: o app declara quais domínios ele trata, e o servidor confirma quais aplicativos têm permissão para isso — por meio de um arquivo hospedado no próprio domínio da aplicação (assetlinks.json no Android, apple-app-site-association no iOS). Se qualquer lado estiver faltando ou inconsistente, o link abre no navegador como fallback. Isso impede que um aplicativo malicioso reivindique seu domínio e intercepte seus links. Vamos montar esses arquivos em detalhes no Post 5.

Na prática: use custom schemes durante o desenvolvimento e migre para HTTPS (App Links / Universal Links) em produção.

Nossa Aplicação: FitConnect

Para tornar o aprendizado concreto, vamos construir o FitConnect — uma plataforma fictícia que conecta personal trainers com clientes por meio de um sistema de indicação.

O cenário:

Maria é personal trainer e quer indicar o app para seus alunos. Ela compartilha seu link de indicação. Quando um aluno se cadastra usando o link, Maria ganha bônus e o aluno ganha desconto.

O deep link principal da série:

https://fitconnect.app/signup?referralCode=TRAINER12345678901234

Quando um aluno clica nesse link, o app deve abrir diretamente na tela de cadastro com o código TRAINER12345678901234 já preenchido. Simples de descrever, mas com bastante detalhe de implementação por baixo.

Domínio: fitconnect.app
Custom scheme: fitconnect://
Package: com.fitconnect.app

Preparando a Estrutura

Antes de escrever qualquer código nativo, vale a pena definir as constantes, tipos e modelos que vão ser compartilhados entre todas as camadas do app.

Constantes

Centralizar strings como os nomes dos channels evita erros de digitação difíceis de rastrear. Se o nome do channel no Dart não bater exatamente com o do Kotlin ou Swift, a comunicação falha silenciosamente.

// lib/shared/const/deep_link_const.dart
class DeepLinkConst {
  static const String methodChannel = 'com.fitconnect.app/deeplink';
  static const String eventChannel = 'com.fitconnect.app/deeplink_stream';

  static const String customScheme = 'fitconnect';
  static const String httpsScheme = 'https';
  static const String appHost = 'fitconnect.app';

  static const String signupPath = '/signup';
  static const String referralCodeParam = 'referralCode';
  static const int referralCodeLength = 20;
}

Enum de Tipos

O getter isSecure torna o código mais expressivo — em vez de comparar strings ou verificar o scheme manualmente, você simplesmente checa data.type.isSecure.

// lib/shared/enums/deep_link_type.dart
enum DeepLinkType {
  customScheme,
  appLink,       // Android HTTPS
  universalLink, // iOS HTTPS
  unknown;

  bool get isSecure => this == appLink || this == universalLink;
}

Modelo de Dados (Freezed)

Se preferir, você não precisa utilizar o Freezed e pode criar seus modelos na mão. A grande vantagem de adotá-lo é a garantia de imutabilidade e a geração automática de código para comparação de objetos e o método copyWith. Como os deep links carregam parâmetros importantes (como o código de indicação), tratar esses dados de forma imutável nos protege de bugs difíceis de rastrear na navegação do app.

// lib/shared/models/deep_link_data.dart
@freezed
class DeepLinkData with _$DeepLinkData {
  const factory DeepLinkData({
    required String url,
    required DeepLinkType type,
    required String scheme,
    String? host,
    String? path,
    @Default({}) Map<String, String> queryParameters,
    String? referralCode,
    required DateTime receivedAt,
  }) = _DeepLinkData;
}

O que construímos até aqui

Ao final desta etapa, você já tem:

Clareza sobre como deep links funcionam.
Entendimento das diferenças entre os tipos de links.
Uma base sólida no Flutter para começar a implementação.

Essa base será utilizada nos próximos passos para integrar o código nativo e completar o fluxo ponta a ponta.

Na próxima etapa, vamos partir para a implementação nativa no Android — incluindo AndroidManifest.xml e MainActivity.kt completos.

Código completo disponível no repositório: FitConnect no GitHub

Este é o primeiro post de uma série de 9 sobre deep links em Flutter. Nos próximos artigos, vamos do código nativo para o Android e iOS até deferred links, redirect pages e testes — tudo sem depender de pacotes prontos. Se você tem dúvidas, sugestões ou já passou por algum problema parecido com deep links, conta nos comentários! Adoro saber como essa experiência se aplica em projetos reais. E se quiser acompanhar os próximos posts, é só seguir aqui no Medium.

Se esse conteúdo te ajudou, deixa um ❤️ ou um 🔖 aqui no DEV.to — isso ajuda o post a alcançar mais devs.

E você, já implementou deep links no seu app?

Qual foi o maior desafio que encontrou?

Quero usar esses casos reais nos próximos posts da série 👇

flutter #android #ios #deeplinks #mobile #programming

Forem: Cristian Dornelles

Checkpoint da Série: o que já funciona, o que quebrou e para onde vamos (Parte 4.5)

O que construímos até aqui

Post 1 — A fundação conceitual

Post 2 — Android nativo

Post 3 — iOS nativo

Post 4 — Integração Flutter

O bug que encontramos na prática

O problema na prática

Onde estamos agora

Para onde vamos

Post 5 — Produção de verdade

Post 6 — Deferred Deep Links

Post 7 — Página de redirect inteligente

Post 8 — Testes e troubleshooting

Post 9 — Refatoração com Clean Architecture

Conectando Tudo: Integração Flutter com Deep Links Nativos (Parte 4)

DeepLinkService no Flutter

Por que StreamController.broadcast()?

A responsabilidade de cada canal

O método _parseDeepLink

Evitando processamento duplicado no Flutter

Integrando no ciclo de vida do app

Atenção: a ordem importa

UI da SignupPage

Fluxo completo

O que construímos até aqui

Deep Links no iOS: Implementação Nativa com Swift + Flutter (Parte 3)

Configurando o Info.plist

Configurando Universal Links

Implementando o AppDelegate.swift

Por que dois métodos de entrada?

Por que o AppDelegate adota FlutterStreamHandler via extension?

Testando no iOS

Android vs iOS: comparação rápida

O que construímos até aqui

Quero usar esses casos reais nos próximos posts da série 👇

Deep Links no Android: Implementação Nativa com Kotlin + Flutter (Parte 2)

Configurando o AndroidManifest.xml

Implementando o MainActivity.kt

O que acontece em cada cenário

Testando com adb

O que construímos até aqui

Quero usar esses casos reais nos próximos posts da série 👇

Deep Links em Flutter: O Guia Definitivo para Iniciantes (Sem Pacotes de Terceiros) (Parte 1)

O que são Deep Links?

Anatomia de um Deep Link

Tipos de Deep Links

Custom Schemes (fitconnect://)

App Links (Android) / Universal Links (iOS)

Nossa Aplicação: FitConnect

Preparando a Estrutura

Constantes

Enum de Tipos

Modelo de Dados (Freezed)

O que construímos até aqui

flutter #android #ios #deeplinks #mobile #programming

Custom Schemes (`fitconnect://`)