App Link: cos'è, principio di funzionamento e configurazione

Cos'è App Link

App Link (Android App Link) è un collegamento HTTPS standard che, quando cliccato su un dispositivo Android, apre automaticamente l'app installata senza mostrare la finestra di dialogo standard di scelta tra browser e app. Google ha introdotto App Link in Android 6.0 (API 23) come soluzione al problema della “finestra di dialogo del selettore”, che riduceva la conversione dei deep link a causa del clic aggiuntivo e della confusione dell'utente.

L'innovazione chiave: verifica. Android verifica che il dominio appartenga effettivamente allo sviluppatore dell'app tramite l'API Digital Asset Links. Google Play Store controlla App Link alla pubblicazione e può rifiutare un aggiornamento se la verifica fallisce. Questo rende App Link più sicuro di Custom URL Scheme: nessun'altra app può intercettare un collegamento al tuo dominio.

Digital Asset Links è un protocollo aperto che Google utilizza non solo per App Link, ma anche per collegare siti web ad app nei risultati di ricerca, Google Assistant e Smart Lock for Passwords. Il protocollo si basa sulla verifica crittografica: in assetlinks.json viene specificata l'impronta SHA256 del certificato di firma dell'app, che elimina la contraffazione.

Come funziona App Link

Il processo di funzionamento di App Link consiste in tre fasi: verifica di Digital Asset Links, elaborazione tramite Intent Filter e reindirizzamento automatico. Ogni fase è obbligatoria. Se la verifica fallisce, Android mostra una finestra di dialogo di scelta — tale deep link funziona normalmente ma senza il vantaggio della transizione automatica.

Digital Asset Links (assetlinks.json)

Asset Links è un file JSON posizionato sul server all'indirizzo https://domain/.well-known/assetlinks.json. Il file contiene un array di oggetti con campi: relation (array di stringhe che descrivono il tipo di relazione), target (oggetto con namespace e package_name dell'app, oltre a sha256_cert_fingerprints — array di impronte SHA256 del certificato di firma).

// assetlinks.json — configurazione minima di App Link
[{
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
        "namespace": "android_app",
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": [
            "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:AD:A4:C5:AD:6B:01:14:79:6B:CB:12:6B:21:39:6F:EA"
        ]
    }
}]

L'impronta SHA256 si ottiene dal certificato con cui è stata firmata l'app. Per le build di debug viene utilizzato il certificato di debug standard di Android, per le build di rilascio il certificato di Google Play Console o il proprio. Importante: quando si cambia il certificato di firma (ad esempio, passando ad App Signing by Google Play), è necessario aggiornare assetlinks.json sul server, altrimenti App Link smetterà di funzionare.

Intent Filter e verifica

Android verifica App Link al primo clic su un collegamento. Il sistema scarica assetlinks.json dal server, confronta package_name e l'impronta SHA256 con il certificato dell'app installata. Se i dati corrispondono, Android contrassegna l'Intent Filter come verificato e tutti i collegamenti successivi a questo dominio si aprono automaticamente, senza finestra di dialogo.

// AndroidManifest.xml — Intent Filter per App Link
<activity
    android:name=".ui.ProductActivity"
    android:exported="true">
    <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"
            android:host="example.com"
            android:pathPrefix="/product" />
    </intent-filter>
</activity>

autoVerify="true" è un attributo obbligatorio che indica ad Android di verificare assetlinks.json. Senza questo attributo, l'Intent Filter non verrà verificato e App Link non verrà attivato. Android supporta più Intent Filter in una singola Activity — per host diversi. Il sistema verifica ciascun host separatamente. La verifica viene eseguita in modo asincrono e può richiedere fino a 20 secondi al primo clic.

Reindirizzamento automatico

Dopo una verifica riuscita, Android apre automaticamente l'app quando si clicca su qualsiasi collegamento che corrisponde all'Intent Filter verificato. L'utente non vede una finestra di dialogo di scelta — l'app si apre istantaneamente. Se l'app non è installata, il collegamento si apre nel browser (come una normale pagina web). Questa è l'esperienza utente ideale: transizione senza interruzioni senza azioni non necessarie.

Importante: il reindirizzamento automatico funziona solo per lo schema https. App Link non supporta http (protocollo non sicuro). Se un utente apre manualmente un collegamento http (ad esempio, da SMS), Android non esegue la verifica e mostra una finestra di dialogo di scelta. Si consiglia di utilizzare https per tutti i collegamenti che portano all'app e configurare il reindirizzamento HTTP a HTTPS sul server.

App Link vs Deep Link

App Link è l'evoluzione di Deep Link su Android, non una sostituzione. La differenza tra loro è fondamentale. Deep Link normale (Custom URL Scheme) funziona tramite un Intent Filter con uno schema personalizzato (myapp://) e senza autoVerify. Android non verifica se l'app è effettivamente associata a questo schema — qualsiasi app può registrare myapp:// e intercettare collegamenti.

App Link risolve tre problemi di Deep Link. Primo: sicurezza — la verifica tramite Digital Asset Links impedisce l'intercettazione dei collegamenti. Secondo: esperienza utente — l'assenza della finestra di dialogo di scelta aumenta la conversione verso l'azione target del 20–40%. Terzo: indicizzazione — Google indicizza gli URL https di App Link e può mostrarli nei risultati di ricerca come collegamenti a contenuti all'interno dell'app.

Compatibilità: App Link funziona su Android 6.0+ (99% dei dispositivi). Per Android 5.x (Lollipop) viene utilizzato il Deep Link normale con finestra di dialogo di scelta. Pertanto, si consiglia di supportare entrambi i meccanismi: App Link per dispositivi moderni e Custom URL Scheme come fallback per versioni precedenti. Un Intent Filter con autoVerify="true" non rompe la compatibilità all'indietro — su Android < 6 l'attributo viene ignorato.

Configurazione di App Link

La configurazione di App Link richiede tre passaggi: configurazione dell'Intent Filter nel manifest, posizionamento di assetlinks.json sul server e verifica della verifica. Il primo passaggio è aggiungere un Intent Filter con android:autoVerify="true" in AndroidManifest.xml. È importante specificare lo schema https, l'host e i percorsi che l'app deve gestire. I percorsi possono contenere caratteri jolly (*) per le sottocartelle.

Il secondo passaggio è la creazione di assetlinks.json. Il file può essere generato tramite Android Studio (Tools → App Links Assistant). L'assistente aiuta anche con il debug e i test. Il file viene posizionato sul server in /.well-known/assetlinks.json. Il server deve restituire Content-Type: application/json ed essere accessibile via HTTPS senza reindirizzamenti. Google Play Console mostra anche lo stato di verifica di App Link nella sezione Publishing.

1. Aggiungere Intent Filter con android:autoVerify="true" in AndroidManifest.xml
2. Ottenere l'impronta SHA256 del certificato (keytool o App Links Assistant)
3. Creare assetlinks.json con package_name e sha256_cert_fingerprints
4. Posizionare il file in /.well-known/assetlinks.json su un server HTTPS
5. Verificare la verifica tramite adb: adb shell dumpsync domain_verification

Test — il terzo passaggio. Utilizzare adb per verificare: il comando adb shell am start -W -a android.intent.action.VIEW -d “https://example.com/product/42” apre l'app. Se il browser si apre invece dell'app, controllare assetlinks.json e autoVerify. Android Studio App Links Assistant contiene un tester integrato: mostra lo stato di verifica per ogni dominio e percorso. Per i test automatizzati, utilizzare Android Testing Library con Intent Matcher.

Caratteristiche di implementazione

Android 12 (API 31) ha introdotto modifiche nella gestione di App Link. È stata aggiunta una nuova verifica specifica per dominio: il sistema controlla ogni singolo collegamento, non l'intero Intent Filter. Questo migliora la sicurezza, ma richiede l'aggiornamento del file assetlinks.json quando si aggiungono nuovi percorsi. Android 12 ha anche introdotto Android App Links Assistant incluso con ADB — comandi per gestire la verifica tramite shell.

Domini multipli è uno scenario tipico per la produzione. L'app può gestire collegamenti da example.com, m.example.com ed example.org. Ogni dominio richiede un assetlinks.json separato sul server corrispondente. Nel manifest vengono aggiunti più Intent Filter — uno per dominio. Tutti i domini devono essere accessibili via HTTPS e superare la verifica in modo indipendente.

App Link e Jetpack Navigation è il modo consigliato per gestire App Link nelle app Android moderne. Jetpack Navigation supporta deep link dichiarativi in nav_graph.xml o tramite NavDeepLinkRequest. Questo semplifica la navigazione: lo sviluppatore descrive quale schermata si apre per un determinato URL, e il componente Navigation gestisce l'Intent e ripristina lo stack di navigazione da solo. Google consiglia di utilizzare Jetpack Navigation per App Link.

// Elaborazione di App Link tramite Jetpack Navigation
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        handleDeepLink(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handleDeepLink(intent)
    }

    private fun handleDeepLink(intent: Intent) {
        intent.data?.let { uri ->
            navController.handleDeepLink(NavDeepLinkRequest
                .Builder
                .fromUri(uri)
                .build()
            )
        }
    }
}

Google Play Store controlla App Link alla pubblicazione. Se il manifest contiene un Intent Filter con autoVerify ma assetlinks.json non è disponibile o non è corretto, Google Play può rifiutare l'aggiornamento con un avviso. Nella console sviluppatore (Policy and Programs → App Links) viene visualizzato lo stato di verifica di ciascun dominio. Prima della pubblicazione, controllare sempre lo stato — correggerlo dopo il rifiuto dell'aggiornamento ritarda il rilascio.