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

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

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

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

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

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

https://example.page.link/m9Mm

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

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

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

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

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

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

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

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

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

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

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

• Динамические ссылки 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

Далее вам необходимо настроить и настроить экземпляр 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 — относится к applicationId, объявленному в файле build.gradle приложения.
   • sha256_cert_fingerprints — относится к отпечатку SHA256 файла хранилища ключей, который вы используете для подписи приложения.

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

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

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

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

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, и теперь будете использовать его в качестве параметра App Link для вашего приложения.

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

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

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

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

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

Мы рекомендуем следовать полной документации по ссылкам приложений здесь или руководству 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) везде, где это возможно, и продолжение использования ссылок приложений (App Links) в дальнейшем.

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

Действия по переходу на универсальные ссылки на iOS

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

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

Действия по созданию и размещению файла ассоциации apple-app-site-association

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

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

1. Создайте папку « .well-known » в общедоступной папке корневого каталога вашего Firebase Hosting.

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 для размещения изменений.

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

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

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

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

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

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

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

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

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

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

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

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 Banners , чтобы предоставить вашим пользователям возможности, аналогичные Firebase Dynamic Links.

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

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

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

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

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