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 используются в реферальных программах для привлечения новых пользователей с привязкой к аккаунту пригласившего. Маркетинговые кампании с переходами из 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 необходимо убедиться, что приложение удалено, а после установки ссылка ведёт на правильный экран с переданными параметрами.