Firebase Dynamic Links: ce este, crearea linkurilor și integrarea

Ce sunt Firebase Dynamic Links

Firebase Dynamic Links este tehnologia Google care creează un singur link ce duce la conținutul dorit în aplicația mobilă sau pe site, adaptând comportamentul în funcție de platformă și starea instalării. Linkul verifică dacă aplicația este instalată pe dispozitiv: dacă da — o deschide cu transmiterea parametrilor, dacă nu — direcționează către Google Play sau App Store pentru instalare, iar după instalare redirecționează către ecranul țintă.

Caracteristica cheie: Deferred Deep Linking

Principalul avantaj al Dynamic Links față de linkurile profunde obișnuite este suportul pentru linkurile profunde amânate. Deferred Deep Linking înseamnă că contextul tranziției (parametrii linkului) se păstrează chiar dacă aplicația nu este încă instalată. Când utilizatorul instalează aplicația din magazin, Dynamic Links SDK citește contextul salvat și îl transmite către ecranul potrivit. Fără această tehnologie, utilizatorul după instalare ar ajunge pur și simplu pe ecranul principal, pierzând codul promoțional, invitația sau linkul către o comandă specifică.

Domenii de aplicare

Dynamic Links sunt utilizate în programele de recomandare pentru atragerea de noi utilizatori cu legare la contul celui care invită. Campaniile de marketing cu tranziții din newslettere și rețele sociale folosesc Dynamic Links pentru măsurarea precisă a conversiei. În scenariile de onboarding, linkul duce noul utilizator către un ecran de bun venit cu conținut personalizat. În e-commerce, linkurile către produse păstrează contextul și duc la fișa produsului chiar și la prima lansare după instalare.

Cum funcționează linkurile dinamice

Mecanismul de funcționare al Dynamic Links constă din mai multe etape, fiecare putând varia în funcție de starea aplicației. Când utilizatorul face clic pe un link dinamic, browserul trimite o cerere către serverul Firebase. Firebase verifică dacă aplicația este instalată prin intermediul verificării intent-filter sau universal link. Dacă aplicația este instalată, Firebase o deschide cu transmiterea linkului profund. Dacă nu — redirecționează către pagina magazinului sau versiunea web.

Anatomia unui link dinamic

Un Dynamic Link standard constă dintr-un URL de bază, parametrii linkului și taguri de marketing opționale. URL-ul de bază este un domeniu de tip your-app.page.link, înregistrat în Firebase Console. Parametrii linkului profund sunt specificați prin parametrii de query: link (URL-ul țintă din aplicație), apn (Android Package Name), ibi (iOS Bundle ID), st și sd (titlul și descrierea pentru previzualizarea socială). Tagurile de marketing utm_source, utm_medium, utm_campaign sunt transmise către Google Analytics pentru urmărire.

Crearea linkurilor prin Firebase Console și API

Firebase Console oferă o interfață vizuală pentru crearea Dynamic Links în secțiunea Engage > Dynamic Links. În consolă se pot seta toți parametrii linkului, inclusiv linkul profund, comportamentul web, metadatele sociale și tagurile UTM. După crearea linkului, consola oferă URL-ul gata pregătit, precum și statistici privind clicurile și tranzițiile. Pentru crearea în masă a linkurilor se utilizează REST API Firebase Dynamic Links cu autentificare OAuth 2.0.

Crearea linkului prin REST API

Pentru crearea programatică a Dynamic Links se utilizează o cerere POST către Firebase Dynamic Links API. Corpul cererii conține dynamicLinkInfo cu parametrii linkului profund, setările platformei și metadatele sociale. API returnează un URL gata pregătit de tipul https://your-app.page.link/abc123. Pentru linkurile de lungă durată se utilizează suffix.option = UNIQUE — linkuri scurte cu sufix unic. Pentru linkurile temporare — SHORT, cu posibilitatea de coliziuni.

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: "Promoție de vară",
            socialDescription: "Reduceri de până la 50% până la sfârșitul lunii"
        }
    },
    suffix: { option: "UNIQUE" }
}

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

Linkuri scurte și taguri UTM

Dynamic Links generează automat URL-uri scurte cu lungimea de 6–8 caractere după domeniu, făcându-le potrivite pentru utilizare în SMS și rețele sociale. Parametrii UTM se adaugă prin câmpul utmParameters sau direct în parametrul link. Firebase leagă automat clicurile Dynamic Links de Google Analytics pentru Firebase, permițând urmărirea traficului de recomandare și atribuirea campaniilor.

Integrarea Dynamic Links în Android

Configurarea Dynamic Links în Android include adăugarea Firebase SDK, configurarea intent-filter pentru activitatea care primește linkuri profunde și procesarea linkurilor prin Firebase Dynamic Links SDK. După instalarea SDK și adăugarea google-services.json, trebuie înregistrată activitatea în AndroidManifest.xml cu intent-filter pentru procesarea linkurilor de pe domeniul aplicației.

Configurarea intent-filter în AndroidManifest

Activitatea care procesează Dynamic Links trebuie să aibă intent-filter pentru acțiunea VIEW și categoriile DEFAULT și BROWSABLE. AndroidManifest.xml include tagul data cu android:scheme, android:host și android:pathPrefix corespunzătoare linkului profund. Pentru procesarea linkurilor de pe domeniul page.link se adaugă și un intent-filter cu schema https și hostul domeniului 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>

Procesarea linkului în cod

După configurarea intent-filter, trebuie procesat Dynamic Link-ul primit în codul activității. FirebaseDynamicLinks API preia linkul din intent și returnează un obiect PendingDynamicLinkData cu parametrii extrași. Metoda getLink returnează linkul profund țintă care poate fi analizat și utilizat pentru navigare. Este important să se proceseze linkul atât la pornirea rece (prin getIntent în onCreate), cât și la pornirea caldă (prin onNewIntent).

Integrarea Dynamic Links în iOS

Configurarea Dynamic Links în iOS necesită configurare atât pe partea Firebase, cât și în proiectul Xcode. Trebuie încărcată cheia APNs în Firebase Console, adăugat Firebase SDK prin Swift Package Manager sau CocoaPods și configurat App Delegate pentru procesarea Universal Links. Dynamic Links în iOS utilizează Universal Links pentru tranziția transparentă între browser și aplicație fără pagină intermediară.

Configurarea Universal Links

Universal Links sunt tehnologia Apple care leagă domeniul de aplicația mobilă. Fișierul apple-app-site-association (AASA) este încărcat pe server la adresa https://your-app.page.link/apple-app-site-association. Firebase creează și menține automat acest fișier pentru domeniul Dynamic Links. În Xcode trebuie activate Associated Domains și specificat applinks:your-app.page.link în Capabilities ale proiectului.

Procesarea linkului prin Firebase SDK

Pentru iOS, procesarea Dynamic Links se efectuează prin Firebase SDK în App Delegate sau Scene Delegate. Metoda application:continueUserActivity: interceptează Universal Link-ul primit și îl transmite Firebase Dynamic Links API, care extrage linkul țintă și parametrii. Firebase SDK procesează automat Deferred Deep Links, solicitând datele de instalare prin stocarea pe termen scurt 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)
                }
            }
    }
}

Exemplu de implementare în Kotlin

Să analizăm un exemplu complet de procesare a Dynamic Link într-o aplicație Android în Kotlin. MainActivity citește Dynamic Link-ul primit atât la pornirea rece, cât și la pornirea caldă a aplicației. Linkul este descompus în parametri care sunt utilizați pentru navigarea către ecranul potrivit cu transmiterea argumentelor. Exemplul arată procesarea linkului către pagina de promoție cu identificatorul promoției.

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", "Eroare la procesarea linkului", e)
            }
    }
}

Testarea Dynamic Links

Pentru testarea Dynamic Links se utilizează Firebase Console, unde se poate crea un link de test și trimite pe dispozitiv prin mesager sau email. Firebase Dynamics Links Debugger este disponibil la URL-ul https://your-app.page.link/?d=1 și afișează informații detaliate despre comportamentul linkului. La testarea Deferred Deep Links trebuie să vă asigurați că aplicația este ștearsă, iar după instalare linkul duce la ecranul corect cu parametrii transmiși.