DEV Community: Cristian Dornelles

Deferred Deep Links: O Clique Aconteceu. A Instalação Também. E Agora? (Parte 6)

Cristian Dornelles — Sun, 26 Apr 2026 15:46:12 +0000

O que construímos até aqui

Nas últimas partes da série, saímos do zero e chegamos a um sistema funcional: configuramos a captura nativa no Android (Post 2) e no iOS (Post 3), integramos tudo ao Flutter com DeepLinkService, MethodChannel e EventChannel (Post 4), e publicamos os arquivos de verificação em deeplinkslab.dev para que App Links e Universal Links funcionem em produção (Post 5).

O link funciona. Mas só quando o app está instalado.

Cenário: João recebe um link de indicação do FitConnect. Clica. Mas ele ainda não tem o app instalado.

O que acontece com o referralCode enquanto ele passa pela loja, faz o download e abre o app pela primeira vez?

Com deep links normais: nada. O contexto se perde. O app abre na tela inicial, sem nenhuma pista de onde João veio.

É exatamente esse problema que os Deferred Deep Links resolvem.

Este é o sexto conteúdo de uma série completa sobre Deep Links no Flutter. Se você ainda não viu os posts anteriores: Post 1 — Guia para Iniciantes | Post 2 — Android com Kotlin | Post 3 — iOS com Swift | Post 4 — Integração Flutter | Post 5 — Produção.

Neste artigo você vai aprender:

Por que deep links normais falham quando o app não está instalado.
Solução simples com LocalStorage.
Solução robusta com backend e fingerprint.

O desafio

O fluxo do problema é direto:

Usuário clica no link — app não está instalado.
Navegador abre a loja (Play Store / App Store).
Usuário instala o app e abre pela primeira vez.
❓ Como o app sabe qual era o link original?

Aqui está o nó: quando o app é aberto diretamente da loja após a instalação, não há nenhum intent nem URL sendo entregue ao sistema. O deep link original ficou no navegador — e o app nunca teve acesso a ele.

A resposta para esse problema é Deferred Deep Links: uma estratégia para preservar o contexto do link entre o clique e o primeiro launch do app.

Fluxo do problema

Solução 1: LocalStorage

A abordagem mais simples usa o próprio device para guardar o estado. A ideia: quando a página web de redirect é aberta (veremos isso no Post 7), ela salva o referralCode no localStorage do navegador. Na primeira abertura do app, o Flutter verifica se existe um estado pendente salvo localmente e repassa o dado ao Flutter.

No Flutter, a lógica fica no DeepLinkService:

// lib/services/deep_link_service.dart

class DeepLinkService {
  // Salvar código após primeira abertura
  Future<void> processDeferredLink() async {
    if (initialLink != null &&
        initialLink!.contains('referralCode')) {

      final code = _extractReferralCode(initialLink!);
      await _storage.write('pending_referral', code);
    }
  }

  // Recuperar código no signup
  Future<String?> getPendingReferralCode() async {
    final code = await _storage.read('pending_referral');

    if (code != null) {
      await _storage.remove('pending_referral'); // Cleanup após uso
      return code;
    }

    return null;
  }
}

A integração acontece em dois momentos distintos do ciclo de vida do app:

// SplashScreen — primeiro launch
await deepLinkService.processDeferredLink();

// SignupScreen — ao carregar a tela
final pendingCode = await deepLinkService.getPendingReferralCode();
if (pendingCode != null) {
  referralCodeController.text = pendingCode;
}

O remove após a leitura é importante: garante que o código seja usado apenas uma vez. Sem isso, o código reapareceria em toda abertura do app até o signup ser concluído.

Vantagens:

✅ Simples de implementar.
✅ Funciona sem conexão.
✅ Sem dependência de backend.

Limitações:

⚠️ Essa abordagem funciona melhor quando o fluxo continua dentro do mesmo contexto web/app híbrido.
⚠️ Sem analytics — não há como saber quantos usuários chegaram via deferred link.

Solução 2: Backend com fingerprint

Quando você precisa de rastreamento cross-device ou analytics de conversão, a solução é mover o estado para o servidor.

O conceito central é o fingerprint: uma combinação de atributos do request HTTP (IP, User-Agent, Accept-Language) que, com alta probabilidade, identifica o mesmo dispositivo em dois momentos diferentes — o clique no link e o primeiro launch do app.

O fluxo no backend:

// Backend: Criar short link
app.post("/api/referral/create-link", async (req, res) => {
  const { referralCode } = req.body;
  const shortCode = generateShortCode();

  await db.save(shortCode, referralCode);

  res.json({
    shortUrl: `https://deeplinkslab.dev/s/${shortCode}`,
  });
});

// Backend: Processar clique
app.get("/s/:code", async (req, res) => {
  const referralCode = await db.get(req.params.code);
  const fingerprint = generateFingerprint(req); // IP + User-Agent + Accept-Language

  // Salvar em cache por 48h
  await redis.setex(`pending:${fingerprint}`, 172800, referralCode);

  // Redirecionar para a loja da plataforma
  const platform = detectPlatform(req);
  res.redirect(getStoreUrl(platform));
});

// Backend: Recuperar código no primeiro launch
app.post("/api/referral/get-pending", async (req, res) => {
  const fingerprint = generateFingerprint(req);
  const code = await redis.get(`pending:${fingerprint}`);

  if (code) {
    await redis.del(`pending:${fingerprint}`); // Cleanup após uso
    res.json({ referralCode: code });
  } else {
    res.status(404).json({ message: "Not found" });
  }
});

No Flutter, o primeiro launch faz uma chamada ao backend para verificar se há um código pendente associado ao fingerprint do device:

// lib/services/deep_link_service.dart

Future<String?> checkPendingOnBackend() async {
  try {
    final response = await dio.post('/api/referral/get-pending');
    return response.data['referralCode'];
  } catch (e) {
    return null;
  }
}

Vantagens:

✅ Funciona cross-device.
✅ Analytics completo de cliques e conversões.
✅ Mais robusto no mesmo device.

Desvantagens:

⚠️ Requer backend e Redis (ou equivalente).
⚠️ Mais complexo de implementar e manter.
⚠️ Fingerprinting não é 100% preciso — redes com NAT ou VPN podem causar colisões.

Quando usar cada uma

Comece com LocalStorage. Se o seu caso de uso for simples — referral no mesmo device, sem necessidade de analytics — essa solução resolve com poucas linhas de código.

Migre para backend quando precisar de analytics de conversão, rastreamento cross-device, ou quando a precisão do fingerprinting for aceitável para o seu contexto de negócio.

O que construímos até aqui

Ao final desta etapa, você já tem:

Clareza sobre por que deep links normais não preservam contexto após instalação.
A solução com LocalStorage: processDeferredLink para salvar e getPendingReferralCode para recuperar.
A arquitetura da solução com backend: short link, fingerprint no Redis e consulta no primeiro launch.
Os critérios para escolher entre as duas abordagens.

Este é o sexto de 9 posts da série. Nos próximos posts, o fluxo fica completo: no Post 7, criamos a página web que serve como ponte entre o navegador e a loja — e é ela que executa a parte do LocalStorage quando o app ainda não está instalado.

No próximo post: a página web de redirect inteligente que detecta a plataforma, exibe o código de indicação visualmente e redireciona para a loja certa.

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

Se esse conteúdo te ajudou, deixa um clap 👏 e salva o post — isso me ajuda a continuar a série.

Você implementaria LocalStorage ou backend com fingerprint?
Ou usaria um serviço pronto como AppsFlyer / Branch / Firebase?

Tags: Flutter, Deep Links, Deferred Deep Links, Mobile Development

App Links e Universal Links: Deep Links em Produção (Parte 5)

Cristian Dornelles — Wed, 22 Apr 2026 01:21:58 +0000

Custom schemes funcionam bem para desenvolvimento, mas para produção você precisa de HTTPS. É aqui que entram App Links no Android e Universal Links no iOS — e onde a maioria dos problemas reais aparece.

Este é o quinto conteúdo de uma série completa sobre Deep Links no Flutter. Se você ainda não viu os posts anteriores: Post 1 | Post 2 | Post 3 | Post 4.

O problema com custom schemes

Até aqui usamos fitconnect:// para testes. Funciona, mas em produção esse scheme tem limitações sérias:

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

Qualquer app pode registrar o mesmo scheme — sem nenhuma verificação.
Se o usuário não tem o app instalado, o sistema exibe um erro genérico.
Não há como garantir que o link chegue ao app correto.

https://deeplinkslab.dev/signup?referralCode=TRAINER1234567890123

✅ Verificação server-side: o sistema operacional confirma com o servidor antes de abrir o app.
✅ Se o app não estiver instalado, o link abre no navegador como fallback natural.
✅ Profissional e seguro.

A diferença não é só cosmética. É uma questão de confiança — tanto do sistema quanto do usuário.

Do domínio fictício ao domínio real

Até aqui, usamos fitconnect.app como domínio fictício para focar na implementação.

Mas agora entramos na parte onde deep links deixam de ser apenas código — e passam a depender de infraestrutura real.

App Links e Universal Links só funcionam com um domínio válido, acessível publicamente e com verificação bidirecional.

Para isso, vamos usar um domínio real dedicado a testes:

deeplinkslab.dev

A partir deste ponto, tudo que implementarmos será o mesmo que você precisa em produção.

Você não precisa usar este domínio — pode (e deveria) usar o seu próprio. Um domínio .dev custa em torno de R$ 60–80 por ano e já vem com HTTPS obrigatório, o que elimina uma configuração a menos. Qualquer registrador funciona: Registro.br, Namecheap, Cloudflare Registrar ou Squarespace Domains.

Se quiser um guia específico — do registro do domínio até o deploy no Cloudflare Pages com os arquivos de verificação prontos — me avisa nos comentários. Se tiver demanda, faço um post dedicado só sobre isso.

Android: configurando o assetlinks.json

O assetlinks.json é o arquivo que o Android baixa do seu servidor para confirmar: "esse app tem permissão para tratar links desse domínio?". Sem ele, o android:autoVerify="true" que adicionamos no Post 2 não tem como concluir a verificação — e o link pode abrir um seletor em vez do app.

Obtendo o SHA256 do certificado

O arquivo assetlinks.json precisa conter o SHA256 do certificado com que o app foi assinado. Para o keystore de debug:

keytool -list -v \
  -keystore ~/.android/debug.keystore \
  -alias androiddebugkey \
  -storepass android \
  -keypass android | grep "SHA256:"

Para o keystore de release, substitua o caminho e as credenciais pelo seu keystore de produção. Debug e release geram SHA256 diferentes — o arquivo de produção precisa conter o fingerprint do certificado de release. Durante o desenvolvimento, o fingerprint de debug é suficiente para testar localmente.

Se você usa o Google Play App Signing, o SHA256 correto para produção está em: Play Console → Configuração → Integridade do app → Certificado de assinatura do app.

O arquivo assetlinks.json

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.fitconnect.app",
      "sha256_cert_fingerprints": [
        "SEU_SHA256"
      ]
    }
  }
]

A relação delegate_permission/common.handle_all_urls é o valor padrão e obrigatório — informa ao Android que o app tem permissão para tratar qualquer URL do domínio declarado.

Deploy

O arquivo deve estar acessível publicamente em:

https://deeplinkslab.dev/.well-known/assetlinks.json

Dois requisitos que costumam causar problemas em produção:

O servidor precisa responder com Content-Type: application/json.
O arquivo deve ser acessível via HTTPS sem redirecionamentos — o Android não segue redirects ao verificar o arquivo.

Se qualquer um desses requisitos falhar, o Android simplesmente ignora o arquivo — e o link passa a abrir no navegador sem nenhum erro visível.

iOS: configurando o apple-app-site-association

No iOS, o equivalente é o apple-app-site-association (sem extensão). O iOS pode manter esse arquivo em cache.

Se algo não funcionar durante o desenvolvimento, reinstalar o app geralmente força uma nova verificação.

O arquivo apple-app-site-association

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAM_ID.com.fitconnect.app",
        "paths": ["/signup", "/signup/*"]
      }
    ]
  }
}

O campo apps deve ser um array vazio — é uma exigência da Apple, mesmo que pareça redundante. O appID combina o Team ID com o bundle ID. O array paths lista os caminhos que o app está autorizado a tratar; /signup/* cobre rotas com subpaths ou query strings.

Obtendo o Team ID

Acesse developer.apple.com/account.
Vá em Membership → o Team ID aparece na lista de informações da conta.

Deploy

https://deeplinkslab.dev/.well-known/apple-app-site-association

O arquivo não deve ter extensão. Sirva-o com Content-Type: application/json e sem redirecionamentos — os mesmos requisitos do Android. O iOS 14+ usa uma CDN da Apple para cachear o arquivo, por isso mudanças podem demorar a ser refletidas; reinstalar o app força a re-verificação durante o desenvolvimento.

O que é essa verificação bidirecional?

A lógica é a mesma nas duas plataformas: o sistema operacional só abre o app se as duas pontas se reconhecerem.

O app declara, no AndroidManifest.xml e no Runner.entitlements, quais domínios ele se propõe a tratar. O servidor, por sua vez, confirma no assetlinks.json e no apple-app-site-association quais aplicativos têm permissão para tratar URLs do domínio.

Se qualquer lado estiver faltando ou inconsistente — fingerprint errado, arquivo inacessível, caminho não listado — o link abre no navegador como fallback, sem mensagem de erro para o usuário. Isso protege contra um vetor real: sem verificação bidirecional, um aplicativo malicioso poderia registrar o mesmo scheme ou domínio e interceptar links destinados ao seu app.

Validando antes de fazer deploy

Android: Google Digital Asset Links

A ferramenta oficial do Google valida o assetlinks.json sem precisar instalar o app:

https://developers.google.com/digital-asset-links/tools/generator

Informe o domínio e o package name — a ferramenta mostra se o arquivo está acessível, se o JSON é válido e se o fingerprint está correto.

Também é possível verificar via adb em um device com o app instalado. No Android 12+, o fluxo recomendado é resetar o estado, forçar a reverificação e só então consultar o resultado:

# Resetar o estado de verificação
adb shell pm set-app-links --package com.fitconnect.app 0 all

# Forçar reverificação
adb shell pm verify-app-links --re-verify com.fitconnect.app

# Consultar o resultado
adb shell pm get-app-links com.fitconnect.app

O status verified confirma que a verificação foi concluída com sucesso. Pular o reset pode fazer o comando retornar um estado antigo em cache — não necessariamente o resultado da configuração atual.

iOS: inspecionando o arquivo diretamente

curl https://deeplinkslab.dev/.well-known/apple-app-site-association

Se o curl retornar o JSON correto, o arquivo está acessível. Para validar o comportamento completo, a Apple recomenda testar em um device físico — o simulador não reproduz a verificação de Associated Domains com fidelidade.

Checklist de produção

Antes de fazer deploy, confirme cada item:

Android:

[ ] SHA256 obtido para o keystore de debug (testes) e release (produção)
[ ] assetlinks.json com package name e fingerprint corretos
[ ] Arquivo acessível em https://deeplinkslab.dev/.well-known/assetlinks.json
[ ] Servidor respondendo com Content-Type: application/json
[ ] Sem redirecionamentos no caminho /.well-known/assetlinks.json
[ ] Validado com a ferramenta Google Digital Asset Links

iOS:

[ ] Team ID obtido no Apple Developer Portal
[ ] apple-app-site-association com appID e paths corretos
[ ] Arquivo acessível em https://deeplinkslab.dev/.well-known/apple-app-site-association
[ ] Associated Domains configurado no Xcode (applinks:deeplinkslab.dev)
[ ] Testado em device físico (não apenas simulador)

O que construímos até aqui

Ao final desta etapa, você já tem:

O assetlinks.json configurado com o SHA256 correto para Android.
O apple-app-site-association com Team ID e paths autorizados para iOS.
Clareza sobre como funciona a verificação bidirecional e por que ela existe.
Ferramentas e comandos para validar os dois arquivos antes de ir a produção.

Este é o quinto de 9 posts da série. Com Android, iOS e Flutter integrados e a verificação de domínio no lugar, o fluxo básico de deep links está completo — mas ainda só funciona quando o usuário já tem o app instalado. No próximo post, resolvemos o caso mais difícil: o que acontece quando o usuário clica no link e ainda não tem o app.

No próximo post: Deferred Deep Links — como salvar o contexto do link e recuperar após a instalação.

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

Este artigo é uma crosspost do Medium — leia lá também e deixa um clap se curtiu.

Já subiu App Links em produção? Qual foi o erro mais difícil de debugar? Conta nos comentários.

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

DEV Community: Cristian Dornelles

Deferred Deep Links: O Clique Aconteceu. A Instalação Também. E Agora? (Parte 6)

O que construímos até aqui

O desafio

Fluxo do problema

Solução 1: LocalStorage

Solução 2: Backend com fingerprint

Quando usar cada uma

O que construímos até aqui

App Links e Universal Links: Deep Links em Produção (Parte 5)

O problema com custom schemes

Do domínio fictício ao domínio real

Android: configurando o assetlinks.json

Obtendo o SHA256 do certificado

O arquivo assetlinks.json

Deploy

iOS: configurando o apple-app-site-association

O arquivo apple-app-site-association

Obtendo o Team ID

Deploy

O que é essa verificação bidirecional?

Validando antes de fazer deploy

Android: Google Digital Asset Links

iOS: inspecionando o arquivo diretamente

Checklist de produção

O que construímos até aqui

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)

Custom Schemes (`fitconnect://`)