Firebase Dynamic Links: cosa sono, creazione di link e integrazione

Cosa sono i Firebase Dynamic Links

Firebase Dynamic Links è una tecnologia Google che crea un singolo link che porta al contenuto desiderato in un'app mobile o sito web, adattando il comportamento in base alla piattaforma e allo stato di installazione. Il link verifica se l'app è installata sul dispositivo: in caso affermativo — la apre con i parametri passati, in caso negativo — reindirizza a Google Play o all'App Store per l'installazione e, dopo l'installazione, reindirizza alla schermata di destinazione.

Caratteristica principale: Deferred Deep Linking

Il principale vantaggio di Dynamic Links rispetto ai deep link normali è il supporto per i deep link differiti. Deferred Deep Linking significa che il contesto di transizione (parametri del link) viene preservato anche se l'app non è ancora installata. Quando l'utente installa l'app dal negozio, Dynamic Links SDK legge il contesto salvato e lo passa alla schermata desiderata. Senza questa tecnologia, l'utente finirebbe semplicemente sulla schermata principale dopo l'installazione, perdendo il codice promozionale, l'invito o il link a un ordine specifico.

Casi d'uso

Dynamic Links sono utilizzati nei programmi referral per attirare nuovi utenti con attribuzione all'account dell'invitante. Le campagne di marketing con transizioni da newsletter email e social network utilizzano Dynamic Links per la misurazione precisa delle conversioni. Negli scenari di onboarding, il link porta un nuovo utente a una schermata di benvenuto con contenuti personalizzati. Nell'e-commerce, i link ai prodotti preservano il contesto e portano alla scheda prodotto anche al primo avvio dopo l'installazione.

Come funzionano i link dinamici

Il meccanismo di funzionamento di Dynamic Links consiste in diverse fasi, ciascuna delle quali può variare in base allo stato dell'app. Quando un utente clicca su un link dinamico, il browser invia una richiesta al server Firebase. Firebase verifica se l'app è installata tramite il controllo dell'intent-filter o dell'universal link. Se l'app è installata, Firebase la apre con il deep link passato. In caso contrario — reindirizza alla pagina del negozio o alla versione web.

Anatomia di un link dinamico

Un Dynamic Link standard è composto da un URL base, parametri del link e tag di marketing opzionali. L'URL base è un dominio come your-app.page.link registrato in Firebase Console. I parametri del deep link vengono impostati tramite parametri di query: link (URL di destinazione all'interno dell'app), apn (Android Package Name), ibi (iOS Bundle ID), st e sd (titolo e descrizione per l'anteprima social). I tag di marketing utm_source, utm_medium, utm_campaign vengono passati a Google Analytics per il tracciamento.

Creazione di link tramite Firebase Console e API

Firebase Console fornisce un'interfaccia visiva per creare Dynamic Links nella sezione Engage > Dynamic Links. Nella console, puoi impostare tutti i parametri del link, inclusi deep link, comportamento web, metadati social e tag UTM. Dopo aver creato il link, la console fornisce un URL pronto all'uso e statistiche su clic e transizioni. Per la creazione in massa di link, viene utilizzata l'API REST Firebase Dynamic Links con autenticazione OAuth 2.0.

Creazione di un link tramite l'API REST

Per la creazione programmatica di Dynamic Links, viene inviata una richiesta POST all'API Firebase Dynamic Links. Il corpo della richiesta contiene dynamicLinkInfo con parametri del deep link, impostazioni della piattaforma e metadati social. L'API restituisce un URL pronto all'uso come https://your-app.page.link/abc123. Per i link a lunga durata, viene utilizzato suffix.option = UNIQUE — link brevi con suffisso univoco. Per i link temporanei — SHORT, con possibili collisioni.

const axios = require("axios")

const apiUrl = "https://firebasedynamiclinks.googleapis.com/v1/shortLinks?key=API_KEY"

const data = {
    dynamicLinkInfo: {
        domainUriPrefix: "https://yourapp.page.link",
        link: "https://yourapp.com/promo/summer",
        androidInfo: { androidPackageName: "com.example.myapp" },
        iosInfo: { iosBundleId: "com.example.myapp.ios" },
        socialMetaTagInfo: {
            socialTitle: "Promozione estiva",
            socialDescription: "Sconto fino al 50% fino a fine mese"
        }
    },
    suffix: { option: "UNIQUE" }
}

axios.post(apiUrl, data)
    .then(res => console.log(res.data.shortLink))
    .catch(err => console.error(err))

Link brevi e tag UTM

Dynamic Links generano automaticamente URL brevi con 6–8 caratteri dopo il dominio, rendendoli adatti per l'uso in SMS e social network. I parametri UTM vengono aggiunti tramite il campo utmParameters o direttamente nel parametro link. Firebase collega automaticamente i clic su Dynamic Links con Google Analytics per Firebase, consentendo di tracciare il traffico referral e l'attribuzione delle campagne.

Integrazione di Dynamic Links in Android

Configurare Dynamic Links in Android include l'aggiunta di Firebase SDK, la configurazione dell'intent-filter per l'activity che riceve i deep link e l'elaborazione dei link tramite Firebase Dynamic Links SDK. Dopo aver installato l'SDK e aggiunto google-services.json, è necessario registrare l'activity in AndroidManifest.xml con un intent-filter per elaborare i link dal dominio della tua app.

Configurazione di intent-filter in AndroidManifest

L'activity che elabora Dynamic Links deve avere un intent-filter per l'azione VIEW e le categorie DEFAULT e BROWSABLE. AndroidManifest.xml include un tag data con android:scheme, android:host e android:pathPrefix corrispondenti al tuo deep link. Per elaborare i link dal dominio page.link, viene aggiunto anche un intent-filter con schema https e host del tuo dominio Dynamic Links.

<!-- AndroidManifest.xml -->
<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="https"
            android:host="yourapp.com"
            android:pathPrefix="/promo" />
    </intent-filter>
</activity>

Elaborazione del link nel codice

Dopo aver configurato intent-filter, devi elaborare il Dynamic Link in arrivo nel codice dell'Activity. L'API FirebaseDynamicLinks riceve il link dall'intent e restituisce un oggetto PendingDynamicLinkData con i parametri estratti. Il metodo getLink restituisce il deep link di destinazione, che può essere analizzato e utilizzato per la navigazione. È importante elaborare il link sia all'avvio a freddo (tramite getIntent in onCreate) che all'avvio a caldo (tramite onNewIntent).

Integrazione di Dynamic Links in iOS

Configurare Dynamic Links in iOS richiede configurazione sia sul lato Firebase che nel progetto Xcode. Devi caricare una chiave APNs in Firebase Console, aggiungere Firebase SDK tramite Swift Package Manager o CocoaPods e configurare App Delegate per gestire Universal Links. Dynamic Links in iOS utilizzano Universal Links per una transizione fluida tra browser e app senza pagine intermedie.

Configurazione degli Universal Links

Universal Links è una tecnologia Apple che collega il tuo dominio a un'app mobile. Il file apple-app-site-association (AASA) viene caricato sul server all'indirizzo https://your-app.page.link/apple-app-site-association. Firebase crea e mantiene automaticamente questo file per il tuo dominio Dynamic Links. In Xcode, devi abilitare Associated Domains e specificare applinks:your-app.page.link nelle Capacità del progetto.

Elaborazione del link tramite Firebase SDK

Per iOS, l'elaborazione di Dynamic Links avviene tramite Firebase SDK in App Delegate o Scene Delegate. Il metodo application:continueUserActivity: intercetta l'Universal Link in arrivo e lo passa all'API Firebase Dynamic Links, che estrae il link di destinazione e i parametri. Firebase SDK gestisce automaticamente i Deferred Deep Links richiedendo i dati di installazione tramite l'archiviazione a breve termine di Firebase Installation API.

import FirebaseDynamicLinks

class AppDelegate: UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping
            ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        return DynamicLinks.dynamicLinks()
            .handleUniversalLink(userActivity.webpageURL!) {
                dynamicLink, error in
                if let link = dynamicLink?.url {
                    self.handleDeepLink(link)
                }
            }
    }
}

Esempio di implementazione in Kotlin

Vediamo un esempio completo di elaborazione di un Dynamic Link in un'app Android con Kotlin. MainActivity legge il Dynamic Link in arrivo sia all'avvio a freddo che a caldo dell'app. Il link viene analizzato in parametri utilizzati per la navigazione verso la schermata desiderata con gli argomenti passati. L'esempio mostra l'elaborazione di un link a una pagina promozionale con un identificatore di campagna promozionale.

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        handleDynamicLink(intent)
    }

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

    private fun handleDynamicLink(intent: Intent) {
        FirebaseDynamicLinks.getInstance()
            .getDynamicLink(intent)
            .addOnSuccessListener { data ->
                val deepLink = data?.link ?: return@addOnSuccessListener
                val promoId = deepLink
                    .getQueryParameter("promoId") ?: ""
                if (promoId.isNotEmpty()) {
                    navigateToPromoScreen(promoId)
                }
            }
            .addOnFailureListener { e ->
                Log.e("DL", "Errore di elaborazione del link", e)
            }
    }
}

Test dei Dynamic Links

Per testare Dynamic Links, viene utilizzata Firebase Console, dove puoi creare un link di prova e inviarlo a un dispositivo tramite messenger o email. Il debugger di Firebase Dynamic Links è disponibile all'indirizzo https://your-app.page.link/?d=1 e mostra informazioni dettagliate sul comportamento del link. Quando si testano i Deferred Deep Links, è necessario assicurarsi che l'app sia disinstallata e che, dopo l'installazione, il link porti alla schermata corretta con i parametri passati.