Переход с динамических ссылок на ссылки на приложения & Универсальные ссылки

Данное руководство по миграции посвящено использованию App Links и Universal Links , а также, при необходимости, Firebase Hosting для размещения файлов ассоциации приложений и сайтов.

Данная миграция заменяет следующие функции Firebase Dynamic Links:

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

Предположим, у вас есть динамическая ссылка Firebase, которая выглядит следующим образом:

Цель данного руководства по миграции — заменить динамические ссылки Firebase следующим образом:

https://example.page.link/m9Mm

При использовании App Link / Universal Link прямые ссылки выглядят следующим образом:

https:// your-project-domain .web.app/welcome

Обратите внимание, что прямая ссылка на приложение/универсальная ссылка предоставит вашим пользователям следующие возможности:

• Прямая ссылка, по которой они смогут перейти и которая откроет ваше приложение, если оно уже установлено.
• Продолжение пользовательского пути, позволяющее пользователю перейти к определенному разделу вашего приложения при его открытии.

Однако глубокая ссылка App Link / Universal Link не будет предоставлять пользователям следующие возможности (которые ранее предоставляла функция Firebase Dynamic Links):

• Направляя пользователей в нужный магазин приложений для их устройств, чтобы они могли загрузить и установить ваше приложение.
• Обеспечение продолжения пользовательского пути после загрузки, установки и первого открытия приложения.

Обратите внимание на различия в поведении и функциональности этих ссылок на приложения / универсальных ссылок по сравнению с динамическими ссылками Firebase, указанными в таблице выше.

Прежде чем начать

Firebase Dynamic Links использует App Links (на Android) и Universal Links (на iOS) в своей базовой реализации для обеспечения функциональности глубоких ссылок после установки вашего приложения.

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

Для завершения миграции вам потребуется следующая информация:

• Динамические ссылки Firebase, которые вы планируете перенести.
• Параметры URL-адресов глубоких ссылок, включенные в ваши динамические ссылки.
• Домен, который вы планируете использовать для замены предыдущего домена Firebase Dynamic Links (если применимо).

Вы можете воспользоваться руководством по экспорту метаданных динамических ссылок , чтобы экспортировать существующие метаданные ссылок и получить указанную выше информацию.

Обзор этапов миграции

1. Создайте новый домен (если у вас его еще нет) для размещения файлов конфигурации App Link / Universal Link с помощью Firebase Hosting.

2. Создайте и разместите файлы конфигурации App Link / Universal Link на своем хостинговом домене.

3. Создавайте новые ссылки приложений / универсальные ссылки, соответствующие схеме глубоких ссылок, используемой в ваших динамических ссылках Firebase.

4. Обновите код своих приложений для Android/iOS, чтобы получать прямые ссылки.

5. Тестирование интеграции ссылок на приложения / универсальных ссылок.

6. Замените опубликованные или доступные динамические ссылки Firebase на ссылки приложений и универсальные ссылки.

Первый шаг будет общим для обоих способов миграции: через App Links или Universal Link. Остальные шаги будут различаться в зависимости от платформы, поэтому перейдите к разделу руководства ниже в зависимости от того, какую платформу вы хотите мигрировать в первую очередь.

• Этапы миграции для Android-приложения (ссылки)
• Этапы миграции для универсальных ссылок на iOS

Создайте новый домен для размещения файлов конфигурации App Link / Universal Link с помощью Firebase Hosting.

Выберите домен

Первый шаг — выбрать домен, который вы хотели бы использовать для ссылок вашего приложения / универсальных ссылок. Именно этот домен будет использоваться для новых ссылок, которыми вы будете делиться со своими пользователями.

При использовании Firebase Hosting автоматически и бесплатно создаются поддомены проекта в формате your-project-domain .web.app или your-project-domain .firebaseapp.com . Также вы можете использовать собственный домен с Firebase Hosting или без него для размещения файлов конфигурации App Link / Universal Link.

Настройка Firebase Hosting

Далее вам потребуется настроить и сконфигурировать ваш экземпляр Firebase Hosting .

После завершения настройки вашего экземпляра Firebase Hosting у вас будет домен, похожий на your-project-domain .web.app , или, если хотите, собственный домен .

Этапы миграции для ссылок на Android-приложения

Создайте и разместите файлы конфигурации App Link на вашем новом хостинге.

Для использования App Links необходимо разместить конфигурационный файл, который помогает установить безопасную связь между доменом, используемым в ваших ссылках, и вашим приложением. Для App Links это файл assetlinks.json .

Шаги по созданию и размещению файла assetlinks.json

Файл assetlinks.json позволяет нам указать список авторизованных приложений, которые могут обрабатывать содержимое веб-домена, используемого для наших ссылок на приложения. Сам файл assetlinks.json должен располагаться в корне веб-домена по пути: /.well-known .

Для завершения настройки выполните следующие действия:

1. Создайте папку .well-known внутри папки public в корневом каталоге вашего Firebase Hosting.

2. Создайте файл с именем assetlinks.json в папке .well-known .

3. Скопируйте следующее содержимое в файл assetlinks.json, обратив внимание на значение каждого поля ниже:

   [{
     "relation": ["delegate_permission/common.handle_all_urls"],
     "target": {
       "namespace": "android_app",
       "package_name": "com.example.android",
       "sha256_cert_fingerprints":
         ["01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF"]
     }
   }]
   

   • namespace — указывает на имя приложения, которое вы хотите предоставить.
   • package_name — это идентификатор приложения, указанный в файле build.gradle приложения.
   • sha256_cert_fingerprints — это отпечаток SHA256 файла хранилища ключей, используемого для подписи приложения.

   Для отладки можно использовать файл debug.keystore, который генерирует запись sha256_cert_fingerprints в Android Studio. Этот файл находится по адресу /Users/<username>/.android/debug.keystore на Mac и Linux, и C:\Users\<username>\.android\debug.keystore на Windows.

   Из этого хранилища ключей вы можете получить значение SHA256 с помощью инструмента keytool.

   Для получения более подробных инструкций по выполнению этого шага обратитесь к данному разделу документации App Links .

   В качестве альтернативы вы также можете использовать App Links Assistant в Android Studio для генерации содержимого файла assetlinks.json и настройки вашего приложения для обработки ссылок на приложения.

4. Обновите файл firebase.json, чтобы проиндексировать его для хостинга.

   "headers": [
     {
       "source": "/.well-known/assetlinks.json",
       "headers": [
         {
           "key": "Content-Type",
           "value": "application/json"
         }
       ]
     }
   ]
   

5. Теперь, когда у нас есть файл assetlinks.json, запустите firebase deploy , чтобы разместить изменения.

   Обратите внимание, что для выполнения указанной выше команды развертывания вам потребуется установить Firebase CLI .

   firebase deploy --only hosting
   

6. Проверьте файл assetlinks.json, перейдя по https:// your-project-domain .web.app/.well-known/assetlinks.json

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

На этом этапе вы воссоздадите прямые ссылки из ваших динамических ссылок Firebase, используя обычные URL-адреса прямых ссылок, соответствующие новому домену, который вы создали для ссылок вашего приложения.

Например, предположим, у вас есть следующая динамическая ссылка Firebase:

В этом случае вам нужно будет извлечь параметр глубокой ссылки — например, https://example.web.app/welcome — и использовать его в качестве параметра ссылки приложения.

Вам потребуется повторить этот процесс для каждой динамической ссылки Firebase, на которую вы хотите перейти, используя ссылки приложений / универсальные ссылки, и воспроизвести схему глубоких ссылок, которую вы использовали ранее.

Например, ознакомьтесь со следующим набором коротких ссылок, параметров глубоких ссылок и перенесенных значений глубоких ссылок Firebase Dynamic Links:

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

Обновите код своего Android-приложения, чтобы получать прямые ссылки.

Следующим шагом после выбора домена, схемы глубоких ссылок и переноса динамических ссылок Firebase в ссылки приложения является обновление кода вашего Android-приложения и самого приложения для получения новых глубоких ссылок.

Мы рекомендуем следовать полной документации по App Links, доступной здесь , или же руководству Android Studio по настройке вашего приложения для обработки прямых ссылок, но основные шаги включают в себя:

1. Определение того, какие действия должны обрабатывать соответствующие глубокие ссылки.
2. Добавление фильтра намерений для этих действий в файл AndroidManifest.xml
3. Получение прямой ссылки в коде приложения ваших действий.

Допустим, вы хотите использовать MainActivity для обработки некоторых прямых ссылок. Для этого вам потребуется добавить следующий фильтр Intent в MainActivity в файле AndroidManifest.xml:

<activity android:name=".MainActivity"
   android:exported="true">
   <intent-filter>
       <action android:name="android.intent.action.MAIN" />
       <category android:name="android.intent.category.LAUNCHER" />
   </intent-filter>
   <intent-filter android:autoVerify="true">
       <action android:name="android.intent.action.VIEW" />
       <category android:name="android.intent.category.DEFAULT" />
       <category android:name="android.intent.category.BROWSABLE" />
       <data android:host="example.web.app" android:scheme="http"
           android:pathPrefix="/welcome" />
       <data android:host="example.web.app" android:scheme="https"
           android:pathPrefix="/welcome" />
   </intent-filter>
</activity>

На этом шаге вы указываете, что MainActivity является местом назначения для обработки прямых ссылок из домена wxample.web.app, включая префикс пути /welcome. Обратите внимание, что вам также потребуется указать атрибут android:autoVerify="true", который позволяет назначить ваше приложение обработчиком по умолчанию для данного типа ссылок.

Наконец, вам потребуется добавить код в ваш MainActivity для получения данных о глубоких ссылках и использования их для управления взаимодействием с этими ссылками в вашем приложении. Это похоже на логику, которую вы, возможно, уже запрограммировали в своем приложении при интеграции с Firebase Dynamic Links.

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.main)

  val  data: Uri? = intent?.data

  val toast = Toast.makeText(this, data, duration)
  toast.show()
}

Тестирование ссылок приложения

Вы можете протестировать созданные вами ссылки на приложения, запустив их либо на физическом устройстве, либо в эмуляторе Android .

Вам потребуется создать кликабельную ссылку, используя домен, настроенный для ссылок вашего приложения, а затем щелкнуть по этой ссылке, чтобы убедиться, что она открывается в вашем приложении и перенаправляет вас к нужному действию.

В качестве альтернативы вы также можете протестировать интеграцию App Links с помощью App Links Assistant в Android Studio или использовать следующую команду для URL-адреса App Link, который вы настроили, чтобы убедиться, что он корректно запускает соответствующее действие:

adb shell am start -a android.intent.action.VIEW -d <your_deep_link_url>

Замените опубликованные или доступные динамические ссылки Firebase на ссылки приложений.

Заключительным этапом миграции станет замена опубликованных или совместно используемых динамических ссылок Firebase на ссылки приложений (App Links) везде, где это возможно, и дальнейшее использование ссылок приложений.

Выполнение этого шага будет зависеть от того, где и как вы опубликовали свои динамические ссылки Firebase, но чтобы отслеживать, какие из них существуют, вы можете экспортировать имеющиеся метаданные динамических ссылок Firebase. См. руководство по экспорту метаданных динамических ссылок .

Этапы миграции для универсальных ссылок на iOS

Создайте и разместите файлы конфигурации универсальных ссылок на вашем новом хостинге.

Для использования универсальных ссылок необходимо разместить конфигурационный файл, который помогает установить безопасную связь между доменом, используемым в ваших ссылках, и вашим приложением. Для универсальных ссылок это файл apple-app-site-association (также известный как файл AASA).

Шаги по созданию и размещению файла apple-app-site-association

Файл AASA позволяет нам предоставить список авторизованных приложений, которые могут обрабатывать содержимое веб-домена, который мы будем использовать для наших универсальных ссылок. Сам файл AASA должен быть размещен в корне веб-домена по пути: /.well-known.

Для завершения настройки выполните следующие действия:

1. Создайте папку " .well-known " в корневом каталоге вашего Firebase Hosting, в папке public.

2. Создайте файл с именем " apple-app-site-association " в папке ".well-known".

3. Скопируйте следующее содержимое в файл apple-app-site-association, обратив внимание на значение каждого поля ниже:

   {
     "applinks": {
       "apps": [],
       "details": [
         {
           "appID": "$TEAM_ID.com.firebase.UniversalLinks",
           "paths": [
             "NOT /_/*",
             "/*"
           ]
         }
       ]
     }
   }
   

   • $TEAM_ID.BundleId — полное имя приложения, уполномоченного обрабатывать ссылки.

4. Обновите файл firebase.json, чтобы проиндексировать его для хостинга.

   "headers": [
     {
       "source": "/.well-known/apple-app-site-association",
       "headers": [
         {
           "key": "Content-Type",
           "value": "application/json"
         }
       ]
     }
   ]
   

5. Теперь, когда у нас есть файл AASA, выполните команду `firebase deploy`, чтобы разместить изменения.

6. Проверьте файл AASA, перейдя по ссылке your-project-domain

Создайте новые универсальные ссылки, соответствующие схеме глубоких ссылок, используемой в ваших динамических ссылках Firebase.

На этом этапе вы воссоздадите прямые ссылки из ваших динамических ссылок Firebase, используя обычные URL-адреса прямых ссылок, соответствующие новому домену, который вы создали для своих универсальных ссылок.

Например, предположим, у вас есть следующая динамическая ссылка Firebase:

В этом случае вам нужно будет извлечь параметр глубокой ссылки — например, https://example.web.app/welcome — и использовать его в качестве параметра универсальной ссылки для вашего приложения.

Вам потребуется повторить этот процесс для каждой динамической ссылки Firebase, на которую вы хотите перейти, используя ссылки приложений / универсальные ссылки, и воспроизвести схему глубоких ссылок, которую вы использовали ранее.

Например, ознакомьтесь со следующим набором коротких ссылок, параметров глубоких ссылок и перенесенных значений глубоких ссылок Firebase Dynamic Links:

Далее вам потребуется заменить все опубликованные или предоставленные другим пользователям динамические ссылки Firebase новыми перенесенными ссылками, чтобы пользователи переходили по этим универсальным ссылкам вместо прежних динамических ссылок Firebase.

Обновите код своего iOS-приложения, чтобы получать прямые ссылки.

Следующим шагом после выбора домена, схемы глубоких ссылок и миграции ваших динамических ссылок Firebase на универсальные ссылки является обновление вашего iOS-приложения и кода приложения для получения новых глубоких ссылок.

Мы рекомендуем следовать полной документации по универсальным ссылкам, доступной здесь, для настройки вашего приложения на обработку прямых ссылок, но основные шаги включают в себя:

1. Обновите конфигурацию проекта, чтобы ваше приложение могло обрабатывать прямые ссылки с вашего недавно созданного домена.

2. Получите прямую ссылку в коде вашего приложения.

Чтобы обновить конфигурацию проекта и включить поддержку прямых ссылок в приложении, вам потребуется добавить в проект в xcode дополнительный связанный домен для домена, который вы планируете использовать для размещения файла apple-app-site-associate.

Это можно сделать следующим образом:

1. Открытие Xcode
2. Выбор проекта в файловом навигаторе
3. Перейдите на вкладку «Подписание и возможности» в настройках проекта.
4. Прокрутите вниз до раздела «Связанные домены».
5. Нажмите на кнопку «+», чтобы добавить дополнительный домен к вашему проекту в формате «applinks: «.

Наконец, вам необходимо обновить код вашего приложения, чтобы оно могло принимать входящие прямые ссылки.

Для этого сначала обновите файл AppDelegate.swift, добавив следующий код, чтобы он реагировал на универсальную ссылку:

func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  AppDelegate.showReceivedUrl(userActivity: userActivity);
  return true
}

static func showReceivedUrl(userActivity: NSUserActivity) {
  if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
    let url = userActivity.webpageURL!
    print(url.absoluteString)
}

Приведённый выше код переопределяет метод обратного вызова Universal Link и выводит в лог URL-адрес прямой ссылки, если он присутствует.

Теперь мы вызовем тот же метод showReceivedUrl из класса SceneDelegate, поскольку, если приложение уже открыто к моменту, когда пользователь нажал на универсальную ссылку, будет вызван именно обратный вызов универсальной ссылки внутри SceneDelegate .

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  AppDelegate.showReceivedUrl(userActivity: userActivity)
}

Тестирование универсальных ссылок

Вы можете протестировать созданные вами универсальные ссылки, запустив приложение на физическом устройстве или симуляторе .

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

Поддержка баннеров Smart App

Мы настоятельно рекомендуем использовать Smart App Banners , чтобы предоставить пользователям опыт, аналогичный Firebase Dynamic Links.

Используя «умные» баннеры приложений, пользователи будут перенаправлены в App Store на страницу вашего приложения, если оно еще не установлено на их устройстве. Вы также можете дополнительно настроить параметр, который будет передан в ваше приложение после его загрузки и установки, чтобы обеспечить пользователям продолжение их взаимодействия с приложением. Если ваше приложение уже установлено, оно откроет возможность передачи параметра, чтобы помочь пользователю перейти к соответствующему контенту в зависимости от «умного» баннера приложения, на который он нажал.

Замените опубликованные или доступные динамические ссылки Firebase на ссылки приложений.

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

Выполнение этого шага будет зависеть от того, где и как вы опубликовали свои динамические ссылки Firebase.

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