Firebase Dynamic Links: co to jest, tworzenie linków i integracja

Czym są Firebase Dynamic Links

Firebase Dynamic Links — to technologia Google, która tworzy pojedynczy link prowadzący do odpowiedniej treści w aplikacji mobilnej lub na stronie internetowej, dostosowując zachowanie w zależności od platformy i stanu instalacji. Link sprawdza, czy aplikacja jest zainstalowana na urządzeniu: jeśli tak — otwiera ją z przekazaniem parametrów, jeśli nie — kieruje do Google Play lub App Store w celu instalacji, a po instalacji przekierowuje na docelowy ekran.

Kluczowa cecha: Deferred Deep Linking

Główną zaletą Dynamic Links w porównaniu ze zwykłymi deep links jest obsługa odroczonych głębokich linków. Deferred Deep Linking oznacza, że kontekst przejścia (parametry linku) jest zachowywany nawet jeśli aplikacja nie jest jeszcze zainstalowana. Gdy użytkownik instaluje aplikację ze sklepu, Dynamic Links SDK odczytuje zachowany kontekst i przekazuje go na odpowiedni ekran. Bez tej technologii użytkownik po instalacji po prostu trafiałby na główny ekran, tracąc kod promocyjny, zaproszenie lub link do konkretnego zamówienia.

Obszary zastosowania

Dynamic Links są używane w programach poleceń do pozyskiwania nowych użytkowników z przypisaniem do konta zapraszającego. Kampanie marketingowe z przejściami z newsletterów i mediów społecznościowych wykorzystują Dynamic Links do precyzyjnego mierzenia konwersji. W scenariuszach onboarding link prowadzi nowego użytkownika na ekran powitalny z spersonalizowaną treścią. W e-commerce linki do produktów zachowują kontekst i prowadzą do karty produktu nawet przy pierwszym uruchomieniu po instalacji.

Jak działają dynamiczne linki

Mechanizm działania Dynamic Links składa się z kilku etapów, z których każdy może się różnić w zależności od stanu aplikacji. Gdy użytkownik klika dynamiczny link, przeglądarka wysyła zapytanie do serwera Firebase. Firebase sprawdza, czy aplikacja jest zainstalowana, za pomocą weryfikacji intent-filter lub universal link. Jeśli aplikacja jest zainstalowana, Firebase otwiera ją z przekazaniem głębokiego linku. Jeśli nie — przekierowuje na stronę sklepu lub wersję internetową.

Anatomia dynamicznego linku

Standardowy Dynamic Link składa się z podstawowego URL, parametrów linku i opcjonalnych tagów marketingowych. Podstawowy URL — to domena w postaci your-app.page.link, zarejestrowana w Firebase Console. Parametry głębokiego linku są określane przez parametry zapytania: link (docelowy URL w aplikacji), apn (Android Package Name), ibi (iOS Bundle ID), st i sd (tytuł i opis do podglądu społecznościowego). Tagi marketingowe utm_source, utm_medium, utm_campaign są przekazywane do Google Analytics w celach śledzenia.

Tworzenie linków przez Firebase Console i API

Firebase Console udostępnia wizualny interfejs do tworzenia Dynamic Links w sekcji Engage > Dynamic Links. W konsoli można ustawić wszystkie parametry linku, w tym głęboki link, zachowanie w sieci, metadane społecznościowe i znaczniki UTM. Po utworzeniu linku konsola udostępnia gotowy URL oraz statystyki kliknięć i przejść. Do masowego tworzenia linków używane jest REST API Firebase Dynamic Links z uwierzytelnianiem OAuth 2.0.

Tworzenie linku przez REST API

Do programowego tworzenia Dynamic Links używane jest żądanie POST do Firebase Dynamic Links API. Treść żądania zawiera dynamicLinkInfo z parametrami głębokiego linku, ustawieniami platformy i metadanymi społecznościowymi. API zwraca gotowy URL w postaci https://your-app.page.link/abc123. Długotrwałe linki używają suffix.option = UNIQUE — krótkie linki z unikalnym sufiksem. Dla tymczasowych linków — SHORT, z możliwością kolizji.

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: "Letnia promocja",
            socialDescription: "Zniżki do 50% do końca miesiąca"
        }
    },
    suffix: { option: "UNIQUE" }
}

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

Krótkie linki i znaczniki UTM

Dynamic Links automatycznie generują krótkie URL o długości 6–8 znaków po domenie, co czyni je odpowiednimi do użycia w SMS i mediach społecznościowych. Parametry UTM są dodawane przez pole utmParameters lub bezpośrednio w parametrze link. Firebase automatycznie łączy kliknięcia Dynamic Links z Google Analytics dla Firebase, co pozwala śledzić ruch referencyjny i atrybucję kampanii.

Integracja Dynamic Links w Android

Konfiguracja Dynamic Links w Android obejmuje dodanie Firebase SDK, konfigurację intent-filter dla aktywności, która przyjmuje głębokie linki, oraz obsługę linków przez Firebase Dynamic Links SDK. Po zainstalowaniu SDK i dodaniu google-services.json należy zarejestrować aktywność w AndroidManifest.xml z intent-filter do obsługi linków z domeny twojej aplikacji.

Konfiguracja intent-filter w AndroidManifest

Aktywność, która obsługuje Dynamic Links, musi mieć intent-filter dla akcji VIEW oraz kategorii DEFAULT i BROWSABLE. AndroidManifest.xml zawiera tag data z android:scheme, android:host i android:pathPrefix, odpowiadającymi twojemu głębokiemu linkowi. Do obsługi linków z domeny page.link dodaje się również intent-filter z schematem https i hostem twojej domeny 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>

Obsługa linku w kodzie

Po skonfigurowaniu intent-filter należy obsłużyć przychodzący Dynamic Link w kodzie aktywności. FirebaseDynamicLinks API pobiera link z intent i zwraca obiekt PendingDynamicLinkData z wyodrębnionymi parametrami. Metoda getLink zwraca docelowy głęboki link, który można przeanalizować i wykonać nawigację. Ważne jest, aby obsługiwać link zarówno przy zimnym starcie (przez getIntent w onCreate), jak i przy gorącym starcie (przez onNewIntent).

Integracja Dynamic Links w iOS

Konfiguracja Dynamic Links w iOS wymaga konfiguracji zarówno po stronie Firebase, jak i w projekcie Xcode. Należy załadować klucz APNs w Firebase Console, dodać Firebase SDK przez Swift Package Manager lub CocoaPods i skonfigurować App Delegate do obsługi uniwersalnych linków (Universal Links). Dynamic Links w iOS używają Universal Links do płynnego przejścia między przeglądarką a aplikacją bez pośredniej strony.

Konfiguracja Universal Links

Universal Links — to technologia Apple, która łączy twoją domenę z aplikacją mobilną. Plik apple-app-site-association (AASA) jest ładowany na serwer pod adresem https://your-app.page.link/apple-app-site-association. Firebase automatycznie tworzy i utrzymuje ten plik dla twojej domeny Dynamic Links. W Xcode należy włączyć Associated Domains i wskazać applinks:your-app.page.link w Capabilities projektu.

Obsługa linku przez Firebase SDK

Dla iOS obsługa Dynamic Links jest wykonywana przez Firebase SDK w App Delegate lub Scene Delegate. Metoda application:continueUserActivity: przechwytuje przychodzący Universal Link i przekazuje go do Firebase Dynamic Links API, który wyodrębnia docelowy link i parametry. Firebase SDK automatycznie obsługuje Deferred Deep Links, żądając danych o instalacji przez krótkoterminowe przechowywanie 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)
                }
            }
    }
}

Przykład implementacji w Kotlin

Rozważmy pełny przykład obsługi Dynamic Link w aplikacji Android w Kotlin. MainActivity odczytuje przychodzący Dynamic Link zarówno przy zimnym, jak i gorącym starcie aplikacji. Link jest rozkładany na parametry, które są używane do nawigacji na odpowiedni ekran z przekazaniem argumentów. W przykładzie pokazano obsługę linku do strony promocji z identyfikatorem promocji.

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", "Błąd przetwarzania linku", e)
            }
    }
}

Testowanie Dynamic Links

Do testowania Dynamic Links używana jest Firebase Console, gdzie można utworzyć testowy link i wysłać go na urządzenie przez komunikator lub email. Firebase Dynamics Links Debugger jest dostępny pod URL https://your-app.page.link/?d=1 i wyświetla szczegółowe informacje o zachowaniu linku. Podczas testowania Deferred Deep Links należy upewnić się, że aplikacja jest usunięta, a po instalacji link prowadzi na prawidłowy ekran z przekazanymi parametrami.