Firebase Dynamic Links: що це таке, створення посилань та інтеграція

Що таке Firebase Dynamic Links

Firebase Dynamic Links — це технологія Google, яка створює єдине посилання, що веде на потрібний контент у мобільному додатку або вебсайті, адаптуючи поведінку залежно від платформи та стану встановлення. Посилання перевіряє, чи встановлено додаток на пристрої: якщо так — відкриває його з передачею параметрів, якщо ні — направляє в Google Play або App Store для встановлення, а після встановлення перенаправляє на цільовий екран.

Ключова особливість: Deferred Deep Linking

Головна перевага Dynamic Links перед звичайними глибокими посиланнями — підтримка відкладених глибоких посилань. Deferred Deep Linking означає, що контекст переходу (параметри посилання) зберігається навіть якщо додаток ще не встановлено. Коли користувач встановлює додаток з магазину, Dynamic Links SDK зчитує збережений контекст і передає його на потрібний екран. Без цієї технології користувач після встановлення просто потрапляв би на головний екран, втрачаючи промо-код, запрошення або посилання на конкретне замовлення.

Сфери застосування

Dynamic Links використовуються в реферальних програмах для залучення нових користувачів з прив'язкою до акаунта запрошувача. Маркетингові кампанії з переходами з email-розсилок та соціальних мереж використовують Dynamic Links для точного вимірювання конверсії. У сценаріях onboarding посилання веде нового користувача на welcome-екран з персоналізованим контентом. В e-commerce посилання на товари зберігають контекст і ведуть на картку товару навіть при першому запуску після встановлення.

Як працюють динамічні посилання

Механізм роботи Dynamic Links складається з кількох етапів, кожен з яких може варіюватися залежно від стану додатка. Коли користувач натискає на динамічне посилання, браузер надсилає запит на сервер Firebase. Firebase перевіряє, чи встановлено додаток, за допомогою перевірки intent-filter або universal link. Якщо додаток встановлено, Firebase відкриває його з передачею глибокого посилання. Якщо ні — перенаправляє на сторінку магазину або веб-версію.

Анатомія динамічного посилання

Стандартне Dynamic Link складається з базового URL, параметрів посилання та опціональних маркетингових тегів. Базовий URL — це домен виду your-app.page.link, зареєстрований в Firebase Console. Параметри глибокого посилання задаються через query-параметри: link (цільовий URL всередині додатка), apn (Android Package Name), ibi (iOS Bundle ID), st та sd (заголовок та опис для social-прев'ю). Маркетингові теги utm_source, utm_medium, utm_campaign передаються в Google Analytics для відстеження.

Створення посилань через Firebase Console та API

Firebase Console надає візуальний інтерфейс для створення Dynamic Links у розділі Engage > Dynamic Links. У консолі можна задати всі параметри посилання, включаючи глибоке посилання, поведінку у вебі, соціальні метадані та UTM-мітки. Після створення посилання консоль надає готовий URL, а також статистику по кліках та переходах. Для масового створення посилань використовується REST API Firebase Dynamic Links з OAuth 2.0 аутентифікацією.

Створення посилання через REST API

Для програмного створення Dynamic Links використовується POST-запит до Firebase Dynamic Links API. Тіло запиту містить dynamicLinkInfo з параметрами глибокого посилання, платформеними налаштуваннями та social-метаданими. API повертає готовий URL виду https://your-app.page.link/abc123. Для довгоживучих посилань використовується suffix.option = UNIQUE — короткі посилання з унікальним суфіксом. Для тимчасових посилань — SHORT, з можливістю колізій.

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: "Літня акція",
            socialDescription: "Знижки до 50% до кінця місяця"
        }
    },
    suffix: { option: "UNIQUE" }
}

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

Короткі посилання та UTM-мітки

Dynamic Links автоматично генерують короткі URL довжиною 6–8 символів після домену, що робить їх придатними для використання в SMS та соціальних мережах. UTM-параметри додаються через поле utmParameters або безпосередньо в параметр link. Firebase автоматично пов'язує кліки по Dynamic Links з Google Analytics для Firebase, що дозволяє відстежувати реферальний трафік та атрибуцію кампаній.

Інтеграція Dynamic Links в Android

Налаштування Dynamic Links в Android включає додавання Firebase SDK, налаштування intent-filter для activity, яка приймає глибокі посилання, та обробку посилань через Firebase Dynamic Links SDK. Після встановлення SDK та додавання google-services.json необхідно зареєструвати activity в AndroidManifest.xml з intent-filter для обробки посилань з домену вашого додатка.

Налаштування intent-filter в AndroidManifest

Activity, яка обробляє Dynamic Links, повинна мати intent-filter для дії VIEW та категорій DEFAULT і BROWSABLE. AndroidManifest.xml включає тег data з android:scheme, android:host та android:pathPrefix, що відповідають вашому глибокому посиланню. Для обробки посилань з домену page.link також додається intent-filter з схемою https та хостом вашого домену 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>

Обробка посилання в коді

Після налаштування intent-filter необхідно обробити вхідне Dynamic Link в коді Activity. FirebaseDynamicLinks API отримує посилання з intent та повертає об'єкт PendingDynamicLinkData з вилученими параметрами. Метод getLink повертає цільове глибоке посилання, яке можна розібрати та виконати навігацію. Важливо обробляти посилання як при холодному старті (через getIntent в onCreate), так і при гарячому старті (через onNewIntent).

Інтеграція Dynamic Links в iOS

Налаштування Dynamic Links в iOS вимагає конфігурації як на стороні Firebase, так і в Xcode проекті. Необхідно завантажити APNs-ключ у Firebase Console, додати Firebase SDK через Swift Package Manager або CocoaPods та налаштувати App Delegate для обробки універсальних посилань (Universal Links). Dynamic Links в iOS використовують Universal Links для прозорого переходу між браузером та додатком без проміжної сторінки.

Налаштування Universal Links

Universal Links — це технологія Apple, яка пов'язує ваш домен з мобільним додатком. Файл apple-app-site-association (AASA) завантажується на сервер за адресою https://your-app.page.link/apple-app-site-association. Firebase автоматично створює та підтримує цей файл для вашого домену Dynamic Links. В Xcode необхідно включити Associated Domains та вказати applinks:your-app.page.link у Capabilities проекту.

Обробка посилання через Firebase SDK

Для iOS обробка Dynamic Links виконується через Firebase SDK в App Delegate або Scene Delegate. Метод application:continueUserActivity: перехоплює вхідне Universal Link та передає його Firebase Dynamic Links API, який вилучає цільове посилання та параметри. Firebase SDK автоматично обробляє Deferred Deep Links, запитуючи дані про встановлення через короткострокове сховище 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)
                }
            }
    }
}

Приклад реалізації на Kotlin

Розглянемо повний приклад обробки Dynamic Link в Android додатку на Kotlin. MainActivity зчитує вхідне Dynamic Link як при холодному, так і при гарячому старті додатка. Посилання розбирається на параметри, які використовуються для навігації на потрібний екран з передачею аргументів. У прикладі показана обробка посилання на сторінку акції з ідентифікатором промо-акції.

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", "Помилка обробки посилання", e)
            }
    }
}

Тестування Dynamic Links

Для тестування Dynamic Links використовується Firebase Console, де можна створити тестове посилання та відправити його на пристрій через месенджер або email. Firebase Dynamics Links Debugger доступний за URL https://your-app.page.link/?d=1 та виводить детальну інформацію про поведінку посилання. При тестуванні Deferred Deep Links необхідно переконатися, що додаток видалено, а після встановлення посилання веде на правильний екран з переданими параметрами.