URL Scheme: cos'è, come funziona e viene usato nello sviluppo

Cos'è URL Scheme?

URL Scheme — è un identificatore di protocollo univoco che un'app registra nel sistema operativo per ricevere chiamate tramite link personalizzati. Quando un utente clicca su un link come myapp://profile/123, il sistema identifica l'app che ha registrato lo schema myapp e le passa il controllo con l'URI completo. Questo meccanismo consente alle app di scambiarsi dati e aprirsi reciprocamente senza necessità di infrastruttura server.

Il concetto di URL Scheme è direttamente preso in prestito dagli standard web RFC 3986, dove lo schema URI è il primo componente di qualsiasi identificatore universale di risorsa. Nello sviluppo mobile, questa idea è adattata per la comunicazione inter-app, dove al posto di un server HTTP, l'app stessa funge da gestore del link.

Esempi di URL Scheme noti

Molte app popolari registrano i propri URL Scheme per l'integrazione con servizi di terze parti. Ad esempio, Spotify utilizza lo schema spotify://, Telegram utilizza tg:// e Instagram utilizza instagram://. Gli sviluppatori creano spesso anche schemi come appname:// per la navigazione interna e i test end-to-end degli schermi.

Gli URL Scheme sono ancora ampiamente utilizzati nelle notifiche push, nelle newsletter via email e nei codici QR dove è richiesta la navigazione immediata a una sezione specifica dell'app. Tuttavia, a partire da iOS 9 e Android 6, sono emersi meccanismi alternativi che gradualmente completano e sostituiscono gli schemi semplici.

Sintassi di URL Scheme: schema, host e percorso

La struttura di un URI personalizzato segue la specifica generale RFC 3986 ed è composta da diversi componenti. Lo schema viene specificato per primo e separato dal resto dell'indirizzo da due punti. Dopo lo schema possono seguire host, porta, percorso, parametri di query e frammento, ciascuno dei quali è opzionale.

La sintassi completa è scheme://host/path?key=value#fragment. Lo schema è l'unico elemento obbligatorio; il resto è determinato dalle esigenze dell'implementazione specifica. Il doppio slash dopo lo schema è storicamente preso in prestito da HTTP e non è strettamente obbligatorio secondo la specifica, ma è universalmente utilizzato come convenzione.

Componenti dell'URI

Per una rappresentazione visiva della struttura dell'URI viene utilizzata una tabella dei componenti. Ogni elemento ha il suo scopo e livello di obbligatorietà.

Gli sviluppatori possono scegliere arbitrariamente la struttura dell'URI, creando flessibilità ma generando problemi di compatibilità tra diverse versioni dell'app. Si raccomanda di documentare il formato URL Scheme come parte dell'API pubblica dell'app e di versionarlo quando si apportano modifiche.

Come funziona URL Scheme su iOS

iOS richiede la registrazione esplicita di ogni URL Scheme nel file Info.plist del progetto. Lo sviluppatore aggiunge un array CFBundleURLTypes, ogni elemento del quale contiene un identificatore (CFBundleURLName) e un elenco di schemi supportati (CFBundleURLSchemes). Dopo la registrazione, il sistema indirizza automaticamente tutte le chiamate in arrivo sugli schemi registrati all'app.

La gestione di un URL Scheme in arrivo avviene nel delegato dell'app tramite il metodo application(_:open:options:). Questo metodo riceve un oggetto URL da cui vengono estratti il percorso e i parametri di query per prendere decisioni di navigazione. Il gestore deve restituire un valore Bool che indica il successo dell'operazione.

Gestione in AppDelegate

Di seguito è riportato un esempio di implementazione di un gestore URL Scheme in Swift. Il codice dimostra l'estrazione dell'host e dei parametri di query da un URI in arrivo utilizzando URLComponents.

func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any]
) -> Bool {
    let host = url.host
    let params = URLComponents(
        url: url,
        resolvingAgainstBaseURL: false
    )?.queryItems
    if host == "profile" {
        navigateToProfile(params)
    }
    return true
}

Il metodo utilizza URLComponents per l'analisi sicura dei parametri di query. Questo approccio è preferibile all'analisi manuale delle stringhe poiché gestisce automaticamente la codifica percentuale e la decodifica dei caratteri speciali nei valori dei parametri.

Come funziona URL Scheme su Android

Android utilizza il sistema Intent Filter per instradare i deep link basati su URL Scheme. Lo sviluppatore dichiara un filtro in AndroidManifest.xml all'interno del tag Activity che deve gestire il link. Il filtro contiene l'azione VIEW, le categorie BROWSABLE e DEFAULT, e un tag data che specifica schema, host e pathPrefix.

Quando un utente clicca su un link con uno schema personalizzato, il sistema controlla l'Intent Filter di tutte le app installate. Se vengono trovate più app corrispondenti, all'utente viene presentata una finestra di dialogo di scelta. La categoria BROWSABLE consente l'elaborazione del link dal browser.

Configurazione dell'Intent Filter

Esempio di dichiarazione di Intent Filter in AndroidManifest.xml per gestire lo schema myapp su un'Activity. La combinazione di action e category è obbligatoria per il corretto instradamento dei deep link.

<activity android:name=".MainActivity">
    <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="myapp"
            android:host="profile"
            android:pathPrefix="/user" />
    </intent-filter>
</activity>

Dopo aver configurato il filtro nell'Activity, è necessario chiamare intent.getData() per ottenere l'URI. È importante verificare che intent e dati non siano null, poiché l'Activity potrebbe essere avviata senza un deep link in arrivo, ad esempio durante l'avvio standard dal launcher.

Passaggio di parametri tramite URL Scheme

I parametri di query in URL Scheme vengono passati dopo il punto interrogativo nel formato chiave=valore, separati da e commerciale. Questo formato è identico alle richieste HTTP e viene facilmente elaborato dagli strumenti standard della piattaforma. I parametri devono essere codificati utilizzando la codifica percentuale per tutti i caratteri non appartenenti al set consentito di caratteri URI.

Esempio di un link completo con parametri: myapp://profile?userId=42&source=email&ref=abc123. Dopo aver estratto l'URL, l'app analizza sequenzialmente tutti i query-item e in base ai loro valori prende una decisione di navigazione verso la schermata di destinazione.

Limite di lunghezza dell'URI

Nel passare dati complessi, è importante considerare il limite di lunghezza dell'URI. Su iOS, la lunghezza massima di URL Scheme è limitata a 2 KB, dopo di che il sistema tronca il link. Su Android, il limite è di circa 8 KB, ma il valore esatto dipende dalla versione del sistema operativo e dal produttore del dispositivo. Per grandi volumi di dati, si consiglia di passare solo un identificatore di sessione tramite URL Scheme e caricare il resto dei dati dal server.

Limitazioni e alternative di URL Scheme

Il principale svantaggio di URL Scheme è l'incapacità di gestire un link se l'app non è installata sul dispositivo. Il browser visualizza un errore e l'utente perde il contesto di navigazione. Per risolvere questo problema, Apple ha introdotto Universal Links in iOS 9 e Google ha introdotto App Links in Android 6. Entrambi i meccanismi vengono registrati tramite un dominio web associato all'app.

Universal Links e App Links funzionano come normali link HTTPS, ma quando l'app è installata, la aprono senza finestra di dialogo di scelta. Se l'app non è installata, il link apre una pagina web sullo stesso dominio, preservando l'esperienza utente. Questo li rende l'alternativa preferita per gli ambienti di produzione.

Meccanismi di fallback

Per URL Scheme su iOS e Android, non esiste un meccanismo di fallback integrato. Gli sviluppatori utilizzano soluzioni intermedie sul server: il link porta a una pagina web che verifica se l'app è installata tramite JavaScript e reindirizza allo schema o all'app store. Firebase Dynamic Links e Branch.io offrono soluzioni pronte per questo problema con supporto per deferred deep link che determinano automaticamente lo stato di installazione e instradano l'utente senza necessità di sviluppare una pipeline server personalizzata.

Ulteriore complessità sorge quando si utilizza URL Scheme su iOS 15+ e Android 12+, dove le regole sulla privacy sono state inasprite. Safari blocca i tentativi di aprire uno schema non registrato senza previa conferma, e Android 12 limita la visibilità delle app installate tramite PackageManager. Questi cambiamenti rendono l'uso di URL Scheme per la comunicazione inter-app meno affidabile rispetto alle versioni precedenti delle piattaforme.