Firebase Dynamic Links: какво е това, създаване на връзки и интеграция

Какво са Firebase Dynamic Links

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

Ключова характеристика: Deferred Deep Linking

Основното предимство на Dynamic Links в сравнение с обикновените deep links е поддръжката на отложени дълбоки връзки. Deferred Deep Linking означава, че контекстът на прехода (параметрите на връзката) се запазва дори ако приложението все още не е инсталирано. Когато потребителят инсталира приложението от магазина, Dynamic Links SDK прочита запазения контекст и го предава на подходящия екран. Без тази технология потребителят след инсталация просто би попаднал на главния екран, губейки промоционалния код, поканата или връзката към конкретна поръчка.

Области на приложение

Dynamic Links се използват в реферални програми за привличане на нови потребители с обвързване към акаунта на канещия. Маркетингови кампании с преходи от имейл бюлетини и социални мрежи използват Dynamic Links за точно измерване на конверсията. В onboarding сценарии връзката води новия потребител до екран за добре дошли с персонализирано съдържание. В електронната търговия връзките към продукти запазват контекста и водят до картата на продукта дори при първото стартиране след инсталация.

Как работят динамичните връзки

Механизмът на работа на 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 (заглавие и описание за социален преглед). Маркетинговите тагове 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 с параметри на дълбоката връзка, настройки на платформата и социални метаданни. 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 за активността, която приема дълбоки връзки, и обработка на връзки чрез Firebase Dynamic Links SDK. След инсталиране на SDK и добавяне на google-services.json, активността трябва да се регистрира в AndroidManifest.xml с intent-filter за обработка на връзки от домейна на приложението.

Конфигуриране на intent-filter в AndroidManifest

Активността, която обработва 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 трябва да се обработи в кода на активността. 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, където може да се създаде тестова връзка и да се изпрати на устройството чрез месинджър или имейл. Firebase Dynamics Links Debugger е достъпен на URL https://your-app.page.link/?d=1 и показва подробна информация за поведението на връзката. При тестване на Deferred Deep Links трябва да се уверите, че приложението е премахнато, а след инсталация връзката води до правилния екран с предадените параметри.