Как создавать динамические ссылки на Android

С помощью Firebase Dynamic Links Builder API можно создавать короткие или длинные Dynamic Links. Этот API принимает либо длинный URL Dynamic Link, либо объект, содержащий параметры Dynamic Link, и возвращает URL, подобные следующим:

https://example.com/link/WXYZ
https://example.page.link/WXYZ

Чтобы создавать Dynamic Links в приложении для Android, необходимо добавить Firebase SDK. Если ваше приложение настроено на получение Dynamic Links, вы уже выполнили эти шаги и можете пропустить этот раздел.

  1. Если вы ещё этого не сделали, добавьте Firebase в проект для Android.

    При регистрации приложения укажите ключ подписи SHA-1. Если вы используете ссылки на приложения, также укажите ключ SHA-256.

  2. В файле Gradle на уровне модуля (приложения) (обычно это <project>/<app-module>/build.gradle.kts или <project>/<app-module>/build.gradle) добавьте зависимость для библиотеки Dynamic Links для Android. Для управления версиями библиотек рекомендуем использовать Firebase Android BoM.

    Чтобы использовать все возможности Dynamic Links, рекомендуем включить Google Analytics в проекте Firebase и добавить в приложение Firebase SDK для Google Аналитики.

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:35.0.1"))
    
        // Add the dependencies for the Dynamic Links and Analytics libraries
        // When using the BoM, you don't specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-dynamic-links'
        implementation 'com.google.firebase:firebase-analytics'
    }

    Благодаря Firebase Android BoM в вашем приложении всегда будут использоваться совместимые версии библиотек Firebase Android.

    (Альтернативный вариант) Добавьте зависимости библиотеки Firebase без использования BoM.

    Если вы не хотите использовать Firebase BoM, то должны указать версию каждой библиотеки Firebase в строке зависимости.

    Если вы используете в приложении несколько библиотек Firebase, настоятельно рекомендуем управлять их версиями с помощью BoM. Это обеспечит совместимость всех версий.

    dependencies {
        // Add the dependencies for the Dynamic Links and Analytics libraries
        // When NOT using the BoM, you must specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-dynamic-links:22.1.0'
        implementation 'com.google.firebase:firebase-analytics:24.0.0'
    }
  3. В консоли Firebase откройте раздел Dynamic Links.
  4. Если вы ещё не приняли условия использования и не задали домен для Dynamic Links, сделайте это, когда появится запрос.

    Если у вас уже есть домен Dynamic Links, запишите его. При программном создании Dynamic Links необходимо указать домен Dynamic Links.

  5. Рекомендуется указать шаблоны URL, которые разрешены в ссылках на контент и резервных ссылках. Это не позволит посторонним лицам создавать Dynamic Links, которые перенаправляют пользователей с вашего домена на сайты, которые вы не контролируете. Подробнее о том, как разрешить определенные шаблоны URL…

Используйте консоль Firebase

Если вы хотите создать одну ссылку Dynamic Link для тестирования или для маркетинговой команды, чтобы она могла легко создать ссылку, которую можно использовать, например, в публикации в социальных сетях, проще всего перейти в консоль Firebase и создать ее вручную, следуя пошаговой форме.

Чтобы создать объект Dynamic Link, создайте новый объект DynamicLink с помощью его конструктора, указав параметры Dynamic Link с помощью методов конструктора. Затем вызовите метод buildDynamicLink или buildShortDynamicLink.

В примере ниже создается длинная ссылка Dynamic Link на https://www.example.com/, которая открывается в приложении com.example.ios на iOS и в вашем приложении на Android.

Kotlin

val dynamicLink = Firebase.dynamicLinks.dynamicLink {
    link = Uri.parse("https://www.example.com/")
    domainUriPrefix = "https://example.page.link"
    // Open links with this app on Android
    androidParameters { }
    // Open links with com.example.ios on iOS
    iosParameters("com.example.ios") { }
}

val dynamicLinkUri = dynamicLink.uri

Java

DynamicLink dynamicLink = FirebaseDynamicLinks.getInstance().createDynamicLink()
        .setLink(Uri.parse("https://www.example.com/"))
        .setDomainUriPrefix("https://example.page.link")
        // Open links with this app on Android
        .setAndroidParameters(new DynamicLink.AndroidParameters.Builder().build())
        // Open links with com.example.ios on iOS
        .setIosParameters(new DynamicLink.IosParameters.Builder("com.example.ios").build())
        .buildDynamicLink();

Uri dynamicLinkUri = dynamicLink.getUri();

Чтобы создать короткий URL Dynamic Link, создайте DynamicLink таким же образом, а затем вызовите buildShortDynamicLink. Для создания короткой ссылки требуется сетевой вызов, поэтому вместо прямого возврата ссылки buildShortDynamicLink возвращает Task, что делает короткую ссылку доступной после завершения запроса. Пример:

Kotlin

val shortLinkTask = Firebase.dynamicLinks.shortLinkAsync {
    link = Uri.parse("https://www.example.com/")
    domainUriPrefix = "https://example.page.link"
    // Set parameters
    // ...
}.addOnSuccessListener { (shortLink, flowchartLink) ->
    // You'll need to import com.google.firebase.dynamiclinks.component1 and
    // com.google.firebase.dynamiclinks.component2

    // Short link created
    processShortLink(shortLink, flowchartLink)
}.addOnFailureListener {
    // Error
    // ...
}

Java

Task<ShortDynamicLink> shortLinkTask = FirebaseDynamicLinks.getInstance().createDynamicLink()
        .setLink(Uri.parse("https://www.example.com/"))
        .setDomainUriPrefix("https://example.page.link")
        // Set parameters
        // ...
        .buildShortDynamicLink()
        .addOnCompleteListener(this, new OnCompleteListener<ShortDynamicLink>() {
            @Override
            public void onComplete(@NonNull Task<ShortDynamicLink> task) {
                if (task.isSuccessful()) {
                    // Short link created
                    Uri shortLink = task.getResult().getShortLink();
                    Uri flowchartLink = task.getResult().getPreviewLink();
                } else {
                    // Error
                    // ...
                }
            }
        });

По умолчанию короткие Dynamic Links генерируются с суффиксами из 17 символов, поэтому угадать действительную Dynamic Link практически невозможно. Если в вашем случае нет ничего страшного в том, что кто-то угадает короткую ссылку, вы можете генерировать суффиксы, длина которых достаточна только для обеспечения уникальности. Для этого передайте ShortDynamicLink.Suffix.SHORT в метод buildShortDynamicLink:

Kotlin

val shortLinkTask = Firebase.dynamicLinks.shortLinkAsync(ShortDynamicLink.Suffix.SHORT) {
    // Set parameters
    // ...
}

Java

Task<ShortDynamicLink> shortLinkTask = FirebaseDynamicLinks.getInstance().createDynamicLink()
        // ...
        .buildShortDynamicLink(ShortDynamicLink.Suffix.SHORT);
        // ...

Вы можете использовать Dynamic Link Builder API, чтобы создавать Dynamic Links с любыми поддерживаемыми параметрами. Подробная информация приведена в справочной документации по API.

В примере ниже создается объект Dynamic Link с несколькими распространенными параметрами.

Kotlin

val dynamicLink = Firebase.dynamicLinks.dynamicLink { // or Firebase.dynamicLinks.shortLinkAsync
    link = Uri.parse("https://www.example.com/")
    domainUriPrefix = "https://example.page.link"
    androidParameters("com.example.android") {
        minimumVersion = 125
    }
    iosParameters("com.example.ios") {
        appStoreId = "123456789"
        minimumVersion = "1.0.1"
    }
    googleAnalyticsParameters {
        source = "orkut"
        medium = "social"
        campaign = "example-promo"
    }
    itunesConnectAnalyticsParameters {
        providerToken = "123456"
        campaignToken = "example-promo"
    }
    socialMetaTagParameters {
        title = "Example of a Dynamic Link"
        description = "This link works whether the app is installed or not!"
    }
}

Java

DynamicLink dynamicLink = FirebaseDynamicLinks.getInstance().createDynamicLink()
        .setLink(Uri.parse("https://www.example.com/"))
        .setDomainUriPrefix("https://example.page.link")
        .setAndroidParameters(
                new DynamicLink.AndroidParameters.Builder("com.example.android")
                        .setMinimumVersion(125)
                        .build())
        .setIosParameters(
                new DynamicLink.IosParameters.Builder("com.example.ios")
                        .setAppStoreId("123456789")
                        .setMinimumVersion("1.0.1")
                        .build())
        .setGoogleAnalyticsParameters(
                new DynamicLink.GoogleAnalyticsParameters.Builder()
                        .setSource("orkut")
                        .setMedium("social")
                        .setCampaign("example-promo")
                        .build())
        .setItunesConnectAnalyticsParameters(
                new DynamicLink.ItunesConnectAnalyticsParameters.Builder()
                        .setProviderToken("123456")
                        .setCampaignToken("example-promo")
                        .build())
        .setSocialMetaTagParameters(
                new DynamicLink.SocialMetaTagParameters.Builder()
                        .setTitle("Example of a Dynamic Link")
                        .setDescription("This link works whether the app is installed or not!")
                        .build())
        .buildDynamicLink();  // Or buildShortDynamicLink()

Параметры Dynamic Link можно задать следующими способами:

Параметры DynamicLink
setLink

Ссылка, которая будет открываться в приложении. Укажите URL, который может обрабатывать ваше приложение (обычно это контент или полезная нагрузка приложения), чтобы инициировать логику приложения (например, предоставить пользователю купон или показать экран приветствия). Ссылка должна быть правильно отформатированным URL, закодированным надлежащим образом, использовать протокол HTTP или HTTPS и не быть другой динамической ссылкой.

setDomainUriPrefix Префикс URL Dynamic Link, который можно найти в консоли Firebase. Примеры доменов Dynamic Link:
https://example.com/link
https://example.page.link
AndroidParameters
setFallbackUrl Ссылка, которая открывается, если приложение не установлено. Укажите это значение, если хотите, чтобы при отсутствии приложения выполнялось другое действие, например открывалась мобильная версия сайта или рекламная страница приложения.
setMinimumVersion versionCode минимальной версии приложения, в которой можно открыть ссылку. Если на устройстве установлена более ранняя версия приложения, пользователь будет перенаправлен в Google Play, чтобы обновить его.
IosParameters
setAppStoreId Идентификатор приложения в App Store, который используется для перенаправления пользователей в App Store, если приложение не установлено.
setFallbackUrl Ссылка, которая открывается, если приложение не установлено. Укажите это значение, чтобы при отсутствии приложения выполнялось другое действие, например открывалась мобильная версия контента или рекламная страница приложения.
setCustomScheme Специальная схема URL вашего приложения, если она отличается от идентификатора пакета приложения.
setIpadFallbackUrl Ссылка, которая будет открываться на iPad, если приложение не установлено. Укажите этот параметр, чтобы при отсутствии приложения, установленного из магазина приложений, выполнялось другое действие, например открывалась веб-версия контента или рекламная страница приложения.
setIpadBundleId Идентификатор пакета приложения для iOS, которое будет использоваться на устройствах iPad для открытия ссылки. Приложение должно быть подключено к вашему проекту на обзорной странице в консоли Firebase.
setMinimumVersion Номер минимальной версии приложения, которая может открыть ссылку. Этот флаг передается в приложение при его открытии, и приложение должно решить, что с ним делать.
NavigationInfoParameters
setForcedRedirectEnabled Если задано значение 1, то при открытии Dynamic Link страница предварительного просмотра приложения будет пропущена и пользователь будет перенаправлен в приложение или магазин. Страница предварительного просмотра приложения (включена по умолчанию) позволяет более надежно направлять пользователей в наиболее подходящее место назначения, когда они открывают Dynamic Links в приложениях. Однако если вы ожидаете, что Dynamic Link будет открываться только в приложениях, которые могут надежно открывать Dynamic Links без этой страницы, вы можете отключить ее с помощью этого параметра. Этот параметр влияет на поведение Dynamic Link только на устройствах iOS.
SocialMetaTagParameters
setTitle Заголовок, который будет использоваться, когда Dynamic Link будет опубликован в сообщении в социальной сети.
setDescription Описание, которое будет использоваться, когда Dynamic Link будет опубликовано в сообщении в социальной сети.
setImageUrl URL изображения, связанного с этой ссылкой. Размер изображения должен быть не менее 300 x 200 пикселей, а размер файла – не более 300 КБ.
GoogleAnalyticsParameters
setSource
setMedium
setCampaign
setTerm
setContent
Параметры аналитики Google Play. Эти параметры (utm_source, utm_medium, utm_campaign, utm_term, utm_content) передаются в Google Play и добавляются в полезную нагрузку ссылки.
ItunesConnectAnalyticsParameters
setProviderToken
setAffiliateToken
setCampaignToken
Параметры аналитики iTunes Connect. Эти параметры (pt, at, ct) передаются в магазин приложений.

Чтобы сократить длинный Dynamic Link, укажите его URL Dynamic Link с помощью setLongLink вместо того, чтобы задавать параметры другими методами компоновщика:

Kotlin

val shortLinkTask = Firebase.dynamicLinks.shortLinkAsync {
    longLink = Uri.parse(
        "https://example.page.link/?link=" +
            "https://www.example.com/&apn=com.example.android&ibn=com.example.ios",
    )
}.addOnSuccessListener { (shortLink, flowChartLink) ->
    // You'll need to import com.google.firebase.dynamiclinks.component1 and
    // com.google.firebase.dynamiclinks.component2

    // Short link created
    processShortLink(shortLink, flowChartLink)
}.addOnFailureListener {
    // Error
    // ...
}

Java

Task<ShortDynamicLink> shortLinkTask = FirebaseDynamicLinks.getInstance().createDynamicLink()
        .setLongLink(Uri.parse("https://example.page.link/?link=https://www.example.com/&apn=com.example.android&ibn=com.example.ios"))
        .buildShortDynamicLink()
        .addOnCompleteListener(this, new OnCompleteListener<ShortDynamicLink>() {
            @Override
            public void onComplete(@NonNull Task<ShortDynamicLink> task) {
                if (task.isSuccessful()) {
                    // Short link created
                    Uri shortLink = task.getResult().getShortLink();
                    Uri flowchartLink = task.getResult().getPreviewLink();
                } else {
                    // Error
                    // ...
                }
            }
        });