Deep linking

1Che cos'è un deep link?#

I deep link permettono a fonti esterne (browser, SMS, e-mail, social media, notifiche push, codici QR) di aprire la tua app direttamente su una pagina specifica invece che sulla home.

La tua app supporta due tipi, e NON sono ugualmente facili:

1. ⚡ Schema personalizzato (myapp://percorso): funziona subito, non c'è niente da configurare. Ideale per notifiche push e codici QR.

1. 🌐 Link https:// (https://mysite.com/page): richiedono UN file caricato sul tuo sito web. Senza di esso Android tiene il link nel browser e la tua app non si apre mai. È il motivo più comune per cui i deep link 'non funzionano'.

Entrambi sono trattati qui sotto. Se ti serve solo qualcosa che funzioni oggi, usa lo schema personalizzato.

2Come funzionano gli URL con schema personalizzato#

Quando si tocca un link con schema personalizzato (ad es. myapp://products/shoes), l'app:

1. Riceve l'URL con lo schema personalizzato
2. Lo collega automaticamente all'URL del tuo sito web
3. Apre la WebView sulla pagina corretta

✅ Lo schema deriva dal nome della tua app (minuscolo, solo lettere).

✅ Esempio di corrispondenza:
myapp://products/shoes
→ https://mysite.com/products/shoes

I segmenti del percorso dopo lo schema vengono mantenuti e aggiunti al dominio del tuo sito web.

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

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

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

3Link https:// - un file deve andare sul tuo sito web#

Questa è la parte che molti si perdono, quindi leggila prima di testare.

AppMint inserisce automaticamente il tuo dominio nell'app. Ma Android NON aprirà la tua app da un link https:// finché il tuo SITO WEB non dimostra che l'app ti appartiene. Da Android 12 in poi, un link non verificato apre semplicemente il browser: nessuna finestra, nessuna scelta. Ecco perchÊ un link può sembrare 'non fare niente'.

La prova è un piccolo file. AppMint l'ha già creato per te: dopo la build, cerca assetlinks.json in Download. Contiene il nome del pacchetto e l'impronta digitale di firma della tua app.

Caricalo sul tuo sito web esattamente a questo indirizzo (il nome della cartella inizia con un punto):

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

4Pubblichi su Google Play? Usa l'impronta digitale di Play#

Google Play firma di nuovo la tua app con la SUA chiave. Quindi l'impronta digitale nell'assetlinks.json generato da AppMint, che è quella della tua chiave locale, non corrisponderà a quella di ciò che gli utenti installano davvero da Play.

Se pubblichi su Play, sostituisci l'impronta digitale:

1. Play Console → la tua app → Test e rilascio → Configurazione → Integrità dell'app
2. Copia lo SHA-256 da 'Certificato della chiave di firma dell'app'
3. Inserisci quel valore in assetlinks.json e ricaricalo

Puoi inserire ENTRAMBE le impronte digitali nello stesso file: quella locale per gli APK che condividi direttamente e quella di Play per le installazioni da Play. In questo modo funzionano entrambe.

[{
  "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
    ]
  }
}]

5Controlla se Android l'ha accettato#

Dopo aver caricato il file, REINSTALLA l'app (Android controlla solo al momento dell'installazione, e può volerci un minuto).

Il comando qui sotto ti dice la verità. Cerca il tuo dominio con 'verified'. Se dice 'legacy_failure' o il dominio manca, il file non viene letto correttamente: torna indietro e controlla le quattro regole.

# 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

6PerchÊ di solito fallisce#

In ordine di frequenza con cui ciascuna è la causa:

1. Il file non è stato caricato o si trova nel percorso sbagliato. Deve essere /.well-known/assetlinks.json, con il punto.

1. www o senza www. Android tratta https://example.com e https://www.example.com come domini DIVERSI. AppMint registra l'host esatto del tuo URL del sito web. Se usi entrambi, metti il file su entrambi e indicaci quale host hai inserito.

1. Un reindirizzamento. Molti host reindirizzano il dominio principale a www. Questo rompe la verifica anche se il file si carica nel browser.

1. Pubblicata su Play ma con l'impronta digitale locale: vedi il passaggio precedente.

1. Non hai reinstallato l'app dopo il caricamento. Android controlla al momento dell'installazione.

I link con schema personalizzato (myapp://...) non richiedono NIENTE di tutto questo e funzionano sempre: usali per le notifiche push e i codici QR se vuoi qualcosa che funzioni oggi stesso.

7Testare i deep link con ADB#

Testa i tuoi deep link da un PC collegato tramite debug USB:

1. Abilita il debug USB sul tuo telefono
2. Collega il telefono via USB
3. Esegui i comandi qui sotto.

⚠️ Importante: 'am start' con un link https può aprire la tua app anche quando la verifica è FALLITA, perché stai passando il link direttamente ad Android. Non dimostra che un vero tocco in Gmail o Chrome funzionerà. Solo 'pm get-app-links' (passaggio precedente) te lo dice. Usa am start per controllare l'instradamento delle PAGINE, non la configurazione del dominio.

# 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 link nelle notifiche push#

Quando invii una notifica push con OneSignal, incolla qualsiasi URL di deep link nel campo 'Launch URL'. L'app si aprirà e navigherà direttamente a quella pagina.

Funzionano entrambi i tipi di URL:
✅ 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 all'avvio a caldo#

Se la tua app è già in esecuzione in background quando viene attivato un deep link, Android consegna il link direttamente senza riavviare l'app: si chiama 'avvio a caldo'.

✅ La tua app lo gestisce in automatico. La WebView navigherà alla nuova pagina anche quando l'app è già aperta.

⚠️ Se i deep link aprono solo la home, controlla che:

• L'URL del sito web nella configurazione corrisponde al dominio del deep link
• Il percorso nell'URL con schema personalizzato è corretto

⚠️ Se i link https:// non aprono l'app PER NIENTE, non è un problema di avvio a caldo: è il passaggio assetlinks.json qui sopra. Link con schema personalizzato che funzionano mentre i link https non fanno nulla è il classico segnale.

Warm launch works automatically.
No extra setup needed.