Deep Linking

1O que é Deep Linking?#

O Deep Linking permite que fontes externas (navegadores, SMS, e-mails, redes sociais, notificações push, QR codes) abram seu app direto em uma página específica em vez da página inicial.

Seu app aceita dois tipos, e eles NÃO são igualmente fáceis:

1. ⚡ Esquema personalizado (myapp://path) - funciona na hora, sem nada para configurar. Ideal para notificações push e QR codes.

1. 🌐 Links https:// (https://mysite.com/page) - precisam de UM arquivo enviado ao seu site. Sem ele, o Android mantém o link no navegador e seu app nunca abre. Este é o motivo mais comum de os deep links 'não funcionarem'.

Os dois estão explicados abaixo. Se você só precisa de algo funcionando hoje, use o esquema personalizado.

2Como funcionam as URLs de esquema personalizado#

Quando um link de esquema personalizado é tocado (por exemplo, myapp://products/shoes), o app:

1. Recebe a URL do esquema personalizado
2. Mapeia automaticamente para a URL do seu site
3. Abre a WebView na página correta

✅ O esquema é derivado do nome do seu app (minúsculas, somente letras).

✅ Exemplo de mapeamento:
myapp://products/shoes
→ https://mysite.com/products/shoes

Os segmentos do caminho após o esquema são preservados e adicionados ao domínio do seu site.

Custom scheme format:
  <appname>://<path>

Examples:
  myshop://cart
  → https://myshop.com/cart

  puma://in/en/help
  → https://in.puma.com/in/en/help

3Links https:// - um arquivo precisa ir para o seu site#

Esta é a parte que as pessoas perdem, então leia antes de testar.

O AppMint coloca seu domínio no app automaticamente. Mas o Android NÃO abre seu app a partir de um link https:// até que seu SITE prove que o app pertence a você. No Android 12 e mais recentes, um link não comprovado simplesmente abre o navegador - sem diálogo, sem escolha. É por isso que um link pode parecer 'não fazer nada'.

A prova é um pequeno arquivo. O AppMint já o criou para você: depois de compilar, procure assetlinks.json em Downloads. Ele contém o nome do pacote e a impressão digital de assinatura do seu app.

Envie-o para o seu site EXATAMENTE neste endereço (o nome da pasta começa com um ponto):

https://yoursite.com/.well-known/assetlinks.json

Rules — all four must be true:
  1. Served over https (not http)
  2. Content-Type: application/json
  3. NO redirect (a redirect to www breaks it)
  4. Reachable publicly — no login, no Cloudflare challenge

Check it from any computer:
  curl -i https://yoursite.com/.well-known/assetlinks.json

4Publicando no Google Play? Use a impressão digital do Play#

O Google Play reassina seu app com a chave DELE. Então a impressão digital dentro do assetlinks.json gerado pelo AppMint - que é a sua chave local - não vai corresponder ao que os usuários realmente instalam pelo Play.

Se você publica no Google Play, troque a impressão digital:

1. Play Console → seu app → Testar e lançar → Configuração → Integridade do app
2. Copie o SHA-256 de 'Certificado da chave de assinatura do app'
3. Coloque esse valor no assetlinks.json e envie de novo

Você pode listar AMBAS as impressões digitais no mesmo arquivo - a local para APKs que você compartilha diretamente e a do Play para instalações pelo Play. Assim as duas funcionam.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourapp.name",
    "sha256_cert_fingerprints": [
      "AA:BB:...",   // your local key (direct APK)
      "11:22:..."    // Play App Signing key
    ]
  }
}]

5Verifique se o Android aceitou#

Depois de enviar o arquivo, REINSTALE o app (o Android só verifica na instalação, e pode levar um minuto).

O comando abaixo mostra a verdade. Procure seu domínio com 'verified'. Se aparecer 'legacy_failure' ou o domínio não estiver na lista, o arquivo não está sendo lido corretamente - volte e confira as quatro regras.

# Does Android consider your domain verified?
adb shell pm get-app-links com.yourapp.name

# Force a re-check without reinstalling (Android 12+):
adb shell pm verify-app-links --re-verify com.yourapp.name

# Google's own checker (open in a browser):
https://digitalassetlinks.googleapis.com/v1/statements:list?
  source.web.site=https://yoursite.com&
  relation=delegate_permission/common.handle_all_urls

6Por que costuma falhar#

Em ordem de frequência de cada causa:

1. O arquivo não foi enviado, ou está no caminho errado. Precisa ser /.well-known/assetlinks.json - com o ponto.

1. www vs sem www. O Android trata https://example.com e https://www.example.com como domínios DIFERENTES. O AppMint registra exatamente o host da URL do seu site. Se você usa os dois, coloque o arquivo nos dois e nos diga qual host você informou.

1. Um redirecionamento. Muitos provedores redirecionam o domínio raiz para www. Isso quebra a verificação mesmo que o arquivo carregue no navegador.

1. Publicado no Play mas usando a impressão digital local - veja a etapa anterior.

1. Não reinstalou depois de enviar. O Android verifica na instalação.

Links de esquema personalizado (myapp://...) não precisam de NADA disso e sempre funcionam - use-os para notificações push e QR codes se quiser algo funcionando hoje.

7Testando deep links via ADB#

Teste seus deep links a partir de um PC conectado com depuração USB:

1. Ative a Depuração USB no seu celular
2. Conecte via USB
3. Execute os comandos abaixo.

⚠️ Importante: 'am start' com um link https pode abrir seu app mesmo quando a verificação FALHOU, porque você está entregando o link direto ao Android. Isso não prova que um toque real no Gmail ou no Chrome vai funcionar. Só 'pm get-app-links' (etapa anterior) diz isso. Use am start para verificar o roteamento da PÁGINA, não a configuração do domínio.

# Test custom scheme:
adb shell am start -a android.intent.action.VIEW \
  -d "myapp://some/page"

# Test website URL:
adb shell am start -a android.intent.action.VIEW \
  -d "https://mysite.com/some/page"

# Verify which app handles it:
adb shell cmd package resolve-activity --brief \
  -a android.intent.action.VIEW \
  -d "myapp://some/page"

8Deep links em notificações push#

Ao enviar uma notificação push pelo OneSignal, cole qualquer URL de deep link no campo 'Launch URL'. O app abrirá e navegará direto para essa página.

Os dois tipos de URL funcionam:
✅ https://mysite.com/flash-sale
✅ myapp://flash-sale

OneSignal Dashboard → New Push:

Launch URL: https://mysite.com/flash-sale
  OR
Launch URL: myapp://flash-sale

Both will open the app on the sale page.

9Importante: comportamento de abertura a quente (warm launch)#

Se seu app já estiver rodando em segundo plano quando um deep link for acionado, o Android entrega o link diretamente sem reiniciar o app - isso se chama 'warm launch'.

✅ Seu app trata isso automaticamente. A WebView navegará para a nova página mesmo com o app já aberto.

⚠️ Se os deep links abrem apenas a página inicial, verifique se:

• A URL do site na configuração corresponde ao domínio do deep link
• O caminho na URL do esquema personalizado está correto

⚠️ Se os links https:// não abrem o app DE JEITO NENHUM, isso não é um problema de warm launch - é a etapa do assetlinks.json acima. Links de esquema personalizado funcionando enquanto os links https não fazem nada é o sinal clássico.

Warm launch works automatically.
No extra setup needed.