Migracja z linków dynamicznych na linki aplikacji i linki uniwersalne

Ten przewodnik po migracji skupia się na korzystaniu z linków aplikacji i linków uniwersalnych oraz opcjonalnie z usługi Firebase Hosting do hostowania plików powiązań aplikacji i witryny.

Ta migracja zastąpi te funkcje Linków dynamicznych Firebase:

Jeśli nadal potrzebujesz innych funkcji Firebase Dynamic Link, które nie są obsługiwane w tym przewodniku, zapoznaj się z innymi scenariuszami migracji w dokumentacji Dynamic Links – często zadawane pytania.

Załóżmy, że masz link dynamiczny Firebase, który wygląda tak:

Celem tego przewodnika jest zastąpienie Linków dynamicznych Firebase, które wyglądają tak:

https://example.page.link/m9Mm

W przypadku precyzyjnych linków aplikacji lub uniwersalnych linków wyglądających tak:

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

Pamiętaj, że precyzyjny link do aplikacji lub uniwersalny link zapewnia użytkownikom:

• klikalny precyzyjny link, który otwiera aplikację, jeśli jest już zainstalowana;
• Kontynuacja ścieżki użytkownika, która prowadzi go do określonej części aplikacji po jej otwarciu

Precyzyjny link do aplikacji lub uniwersalny link nie zapewnia jednak użytkownikom tych zachowań, które były dostępne w przypadku linków dynamicznych Firebase:

• Przekierowywanie użytkowników do odpowiedniego sklepu, aby mogli pobrać i zainstalować aplikację
• kontynuowanie podróży użytkownika po pobraniu, zainstalowaniu i pierwszym uruchomieniu aplikacji;

Zwróć uwagę na różnice w zachowaniu i funkcjonalności tych linków aplikacji / uniwersalnych w porównaniu z linkami dynamicznymi Firebase wymienionymi w tabeli powyżej.

Zanim zaczniesz

Linki dynamiczne Firebase korzystają z linków aplikacji (na Androidzie) i linków uniwersalnych (na iOS) w ramach własnej implementacji, aby zapewnić funkcjonalność precyzyjnych linków po zainstalowaniu aplikacji.

Z tego przewodnika dowiesz się, jak utworzyć własne linki do aplikacji i linki uniwersalne za pomocą Hostingu Firebase, aby zastąpić część funkcji Linków dynamicznych Firebase podczas migracji Linków dynamicznych Firebase do nowego rozwiązania do migracji Linków do aplikacji / Linków uniwersalnych.

Aby dokończyć migrację, musisz podać te informacje:

• Linki dynamiczne Firebase, które chcesz przenieść
• Parametry adresów URL precyzyjnych linków zawarte w linkach dynamicznych
• Domena, której chcesz użyć do zastąpienia poprzedniej domeny Firebase Dynamic Links (jeśli dotyczy)

Aby wyeksportować istniejące metadane linku oraz uzyskać wymienione powyżej informacje, możesz skorzystać z przewodnika po eksportowaniu metadanych Dynamic Links.

Omówienie kroków migracji

1. Zarezerwuj nową domenę (jeśli nie masz jeszcze takiej, której chcesz używać), aby hostować pliki konfiguracji linku do aplikacji lub linku uniwersalnego za pomocą Hostingu Firebase.

2. Utwórz i hostuj pliki konfiguracji linków do aplikacji lub linków uniwersalnych w swojej domenie hostującej.

3. Utwórz nowe linki aplikacji lub uniwersalne linki, które pasują do schematu precyzyjnych linków używanego w linkach dynamicznych Firebase.

4. Zaktualizuj aplikacje na Androida i iOS oraz kod aplikacji, aby otrzymywać precyzyjne linki.

5. Testowanie integracji linków aplikacji lub linków uniwersalnych.

6. Zastąp opublikowane lub udostępnione linki dynamiczne Firebase linkami aplikacji i uniwersalnymi linkami.

Pierwszy krok będzie taki sam w przypadku migracji z linków aplikacji i uniwersalnych linków. Pozostała część instrukcji będzie się różnić w zależności od platformy. Przejdź do odpowiedniej sekcji poniżej, aby dowiedzieć się, jak przeprowadzić migrację na danej platformie.

• Instrukcje migracji dotyczące linków aplikacji na Androida
• Procedura migracji uniwersalnych linków na iOS

Za pomocą Hostingu Firebase zarezerwuj nową domenę, aby hostować pliki konfiguracji Linku do aplikacji lub Linku uniwersalnego

Wybierz domenę

Najpierw wybierz domenę, której chcesz używać do obsługi App Links lub Universal Links. Ta domena będzie używana do nowych linków, które udostępnisz użytkownikom.

Jeśli korzystasz z hostingu Firebase, subdomeny projektu w formacie your-project-domain.web.app lub your-project-domain.firebaseapp.com są automatycznie udostępniane bezpłatnie. Opcjonalnie możesz użyć domeny niestandardowej z Hostingiem Firebase lub bez niego, aby hostować pliki konfiguracji App Link lub linków uniwersalnych.

Konfigurowanie Hostingu Firebase

Następnie musisz skonfigurować instancję Hostingu Firebase.

Po skonfigurowaniu instancji Hostingu Firebase będziesz mieć domenę podobną do your-project-domain.web.app lub domenę niestandardową.

Etapy migracji linków aplikacji na Androida

Utwórz i hostuj pliki konfiguracji App Link w nowej domenie hostingu.

Aby korzystać z usług App Links, musisz hostować plik konfiguracji, który pomoże Ci ustanowić bezpieczne powiązanie między domeną używaną w linkach a Twoją aplikacją. W przypadku App Links jest to plik assetlinks.json.

Tworzenie i hostowanie pliku assetlinks.json

Plik assetlinks.json pozwala nam podać listę autoryzowanych aplikacji, które mogą obsługiwać zawartość domeny internetowej, której będziemy używać do obsługi Linków do aplikacji. Plik assetlinks.json musi być hostowany w korzenia domeny internetowej pod ścieżką: /.well-known.

Aby dokończyć tę konfigurację, wykonaj te czynności:

1. Utwórz folder .well-known w katalogu publicznym w katalogu głównym Hostingu Firebase.

2. W folderze .well-known utwórz plik o nazwie assetlinks.json.

3. Skopiuj ten tekst do pliku assetlinks.json, zwracając uwagę na znaczenie poszczególnych pól:

   [{
     "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 – odnosi się do nazwy aplikacji, którą chcesz podać;
   • package_name – odnosi się do identyfikatora applicationId zadeklarowanego w pliku build.gradle aplikacji.
   • sha256_cert_fingerprints – odnosi się do odcisku cyfrowego SHA-256 pliku klucza, którego używasz do podpisywania aplikacji.

   Plik debug.keystore używany przez Androida Studio możesz wykorzystać do wygenerowania rekordu sha256_cert_fingerprints na potrzeby debugowania. Plik znajdziesz w folderze /Users/<username>/.android/debug.keystore na komputerze Mac i Linux oraz w folderze C:\Users\<username>\.android\debug.keystore na komputerze z systemem Windows.

   Z tego klucza możesz pobrać wartość SHA256 za pomocą narzędzia keytool.

   Więcej instrukcji dotyczących tego kroku znajdziesz w tej sekcji dokumentacji dotyczącej połączeń z aplikacjami.

   Możesz też użyć Asystenta linków aplikacji w Android Studio, aby wygenerować zawartość pliku assetlinks.json i skonfigurować aplikację do obsługi linków aplikacji.

4. Zaktualizuj plik firebase.json, aby zindeksować go pod kątem hostingu.

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

5. Teraz, gdy plik assetlinks.json jest już dostępny, uruchom polecenie firebase deploy, aby zapisać zmiany.

   Aby uruchomić powyższe polecenie wdrażania, musisz mieć zainstalowany wiersz poleceń Firebase.

   firebase deploy --only hosting
   

6. Aby zweryfikować plik assetlinks.json, otwórz: https://your-project-domain.web.app/.well-known/assetlinks.json

Utwórz nowe Linki do aplikacji dopasowane do schematu linków głębokich użytego w Linkach dynamicznych Firebase.

W tym kroku ponownie utwórz precyzyjne linki z Linków dynamicznych Firebase, używając zwykłych adresów URL precyzyjnych linków pasujących do nowej domeny utworzonej dla Linków do aplikacji.

Załóżmy, że masz taki link dynamiczny Firebase:

W tym przypadku wyodrębnij parametr precyzyjnego linku, np. https://example.web.app/welcome, i użyj go jako parametr linku do aplikacji w swojej aplikacji.

Powtórz ten proces w przypadku każdego dynamicznego linku Firebase, który chcesz przenieść na linki aplikacji lub uniwersalne linki, i powtórz schemat precyzyjnych linków, którego używasz.

Poniżej znajdziesz przykładowy zestaw krótkich linków, parametrów precyzyjnych linków i przeniesionych wartości precyzyjnych linków usługi Linki dynamiczne Firebase:

Następnie musisz zastąpić wszystkie wystąpienia linków dynamicznych Firebase, które zostały opublikowane lub udostępnione, nowymi przeniesionymi precyzyjnymi linkami, aby użytkownicy klikali te linki z aplikacji zamiast poprzednich linków dynamicznych Firebase.

Aktualizowanie aplikacji na Androida i jej kodu, aby otrzymywać precyzyjne linki

Po wybraniu domeny, schematu precyzyjnych linków i przekształceniu linków dynamicznych Firebase w linki do aplikacji musisz zaktualizować aplikację na Androida i jej kod, aby zaczęła ona używać nowych precyzyjnych linków.

Zalecamy zapoznanie się z pełną dokumentacją dotyczącą linków do aplikacji lub przewodnikiem po Android Studio, aby skonfigurować aplikację do obsługi precyzyjnych linków. Główne kroki to:

1. Określanie, które działania powinny obsługiwać odpowiednie precyzyjne linki
2. Dodaj filtr intencji dla tych działań w pliku AndroidManifest.xml.
3. Odbieranie precyzyjnego linku w kodzie aplikacji aktywności

Załóżmy, że chcesz użyć MainActivity do obsługi niektórych linków wewnętrznych. Aby to zrobić, dodaj do elementu MainActivity w pliku AndroidManifest.xml ten filtr intencji:

<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>

W tym kroku określasz, że MainActivity jest miejscem docelowym do obsługi linków głębokich z domeny wxample.web.app i zawiera prefiks ścieżki /welcome. Pamiętaj, że musisz też określić atrybut android:autoVerify="true", który pozwala wyznaczyć Twoją aplikację jako domyślny moduł obsługi dla danego typu linku.

Na koniec musisz dodać kod do MainActivity, aby pobrać dane linku głębokiego i wykorzystać je do wyświetlania linków głębokich w aplikacji. Jest to podobna logika, jaką możesz mieć już zaimplementowaną w aplikacji po jej integracji z Dynamic Links Firebase.

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()
}

Testowanie linków aplikacji

Możesz przetestować utworzone właśnie linki do aplikacji, uruchamiając aplikację na urządzeniu fizycznym lub w emulatorze Androida.

Musisz utworzyć klikalny link za pomocą domeny skonfigurowanej dla Linków do aplikacji, a następnie kliknąć ten link, aby sprawdzić, czy otwiera się Twoja aplikacja i czy przekierowuje on do wybranej czynności.

Możesz też przetestować integrację z linkami aplikacji za pomocą asystenta linków aplikacji w Android Studio lub użyć tego polecenia w przypadku skonfigurowanego adresu URL linku aplikacji, aby mieć pewność, że prawidłowo uruchamia on odpowiednią aktywność:

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

Zastępowanie opublikowanych lub udostępnionych Linków dynamicznych Firebase za pomocą Linków do aplikacji

Ostatnim krokiem migracji jest zastąpienie opublikowanych lub udostępnionych linków dynamicznych Firebase linkami do aplikacji, o ile to możliwe, oraz dalsze korzystanie z linków do aplikacji.

Sposób wykonania tego kroku zależy od tego, gdzie i jak zostały opublikowane Linki dynamiczne Firebase. Aby śledzić, które z nich istnieją, możesz wyeksportować istniejące metadane Linków dynamicznych Firebase. Zapoznaj się z przewodnikiem po eksportowaniu metadanych linków dynamicznych.

Kroki migracji dotyczące linków uniwersalnych na iOS

Utwórz i hostuj pliki konfiguracji Universal Links w nowej domenie hostingu.

Aby korzystać z uniwersalnych linków, musisz hostować plik konfiguracji, który pomoże Ci ustanowić bezpieczne powiązanie między domeną używaną w linkach a Twoją aplikacją. W przypadku uniwersalnych linków jest to plik apple-app-site-association (zwany też plikiem AASA).

Instrukcje tworzenia i hostowania pliku apple-app-site-association

Plik AASA umożliwia nam podanie listy autoryzowanych aplikacji, które mogą obsługiwać zawartość domeny internetowej, której będziemy używać do uniwersalnych linków. Plik AASA musi być hostowany w katalogu głównym domeny internetowej pod ścieżką /.well-known.

Aby dokończyć tę konfigurację, wykonaj te czynności:

1. Utwórz folder „.well-known” w katalogu publicznym w katalogu głównym Hostingu Firebase.

2. Utwórz plik o nazwie „apple-app-site-association” w folderze „.well-known”.

3. Skopiuj poniższy tekst do pliku apple-app-site-association, zwracając uwagę na znaczenie poszczególnych pól:

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

   • $TEAM_ID.BundleId – pełna i jednoznaczna nazwa aplikacji upoważnionej do obsługi linków

4. Zaktualizuj plik firebase.json, aby zindeksować go pod kątem hostingu.

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

5. Teraz, gdy plik AASA jest już gotowy, wykonaj polecenie firebase deploy, aby wdrożyć zmiany.

6. Aby zweryfikować plik AASA, otwórz adres https://your-project-domain.web.app/.well-known/app-app-site-association.

Utwórz nowe linki Universal Links zgodne ze schematem precyzyjnych linków do aplikacji używanym w Linkach dynamicznych Firebase.

W tym kroku ponownie utwórz linki docelowe z Linków dynamicznych Firebase, używając zwykłych adresów URL linków docelowych pasujących do nowej domeny utworzonej na potrzeby Linków uniwersalnych.

Załóżmy na przykład, że masz taki link dynamiczny Firebase:

W tym przypadku wyodrębnisz parametr precyzyjnego linku, np. https://example.web.app/welcome, i użyjesz go jako parametr Universal Link w swojej aplikacji.

Powtórz ten proces w przypadku każdego dynamicznego linku Firebase, który chcesz przenieść na linki aplikacji lub uniwersalne linki, i powtórz schemat precyzyjnych linków, którego używasz.

Poniżej znajdziesz przykładowy zestaw krótkich linków, parametrów precyzyjnych linków i przeniesionych wartości precyzyjnych linków usługi Linki dynamiczne Firebase:

Następnie musisz zastąpić wszystkie wystąpienia linków dynamicznych Firebase, które zostały opublikowane lub udostępnione, nowymi przeniesionymi linkami głębokimi, aby użytkownicy klikali te linki uniwersalne zamiast poprzednich linków dynamicznych Firebase.

Zaktualizuj aplikację na iOS i jej kod, aby otrzymywać precyzyjne linki

Po wybraniu domeny, schematu precyzyjnych linków i przekształceniu linków dynamicznych Firebase w uniwersalne linki należy zaktualizować aplikację na iOS i jej kod, aby zaczęła ona używać nowych precyzyjnych linków.

Zalecamy zapoznanie się z pełną dokumentacją uniwersalnych linków, aby dowiedzieć się, jak skonfigurować aplikację do obsługi precyzyjnych linków. Główne kroki to:

1. Zaktualizuj konfigurację projektu, aby umożliwić aplikacji obsługę łączy wewnętrznych z nowo utworzonej domeny

2. Odbieranie precyzyjnego linku w kodzie aplikacji

Aby zaktualizować konfigurację projektu i zezwolić aplikacji na obsługę linków głębokich, musisz dodać do projektu w xCode dodatkową domenę powiązaną z domeną, której zamierzasz teraz używać do hostowania pliku apple-app-site-associate.

Aby to zrobić:

1. Otwieranie Xcode
2. Wybieranie projektu w nawigatorze plików
3. Otwórz kartę Podpisywanie i możliwości w ustawieniach projektu.
4. Przejdź do sekcji Powiązane domeny.
5. Kliknij przycisk +, aby dodać do projektu dodatkową domenę w formacie „applinks:".

Na koniec musisz zaktualizować kod aplikacji, aby móc odbierać przychodzące precyzyjne linki.

Aby to zrobić, najpierw zaktualizuj plik AppDelegate.swift, aby odpowiadał na żądania Universal Link. Aby to zrobić, dodaj ten kod:

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)
}

Powyższy kod zastępuje metodę wywołania uniwersalnego linku i zapisuje adres URL precyzyjnego linku, jeśli jest obecny.

Teraz wywołamy tę samą metodę showReceivedUrl z klasy SceneDelegate, ponieważ jeśli aplikacja jest już otwarta w momencie kliknięcia przez użytkownika uniwersalnego linku, wywoływana będzie funkcja wywołania zwrotnego uniwersalnego linku w metodie SceneDelegate.

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

Testowanie uniwersalnych linków

Możesz przetestować utworzone właśnie uniwersalne linki, uruchamiając aplikację na fizycznym urządzeniu lub w symulatorze.

Musisz utworzyć klikalny link za pomocą domeny skonfigurowanej pod kątem linków uniwersalnych, a potem kliknąć ten link, aby sprawdzić, czy otwiera się Twoja aplikacja i czy przenosi Cię on na odpowiedni ekran.

Obsługa banerów aplikacji mobilnych

Zdecydowanie zalecamy używanie inteligentnych banerów aplikacji, aby zapewnić użytkownikom podobne wrażenia jak w przypadku dynamicznych linków Firebase.

Dzięki inteligentnym banerom z aplikacjami użytkownicy będą przekierowywani do strony z informacjami o aplikacji w Sklepie Play, jeśli aplikacja nie jest jeszcze zainstalowana na ich urządzeniu. Możesz też opcjonalnie skonfigurować parametr, który zostanie przekazany do aplikacji po jej pobraniu i zainstalowaniu, aby umożliwić użytkownikom kontynuowanie ich podróży. Jeśli aplikacja jest już zainstalowana, otworzy się, przekazując parametr do aplikacji, aby pomóc użytkownikowi przejść do odpowiednich treści na podstawie klikniętego przez niego inteligentnego banera aplikacji.

Zastępowanie opublikowanych lub udostępnionych Linków dynamicznych Firebase za pomocą Linków do aplikacji

Ostatnim krokiem migracji będzie zastąpienie opublikowanych lub udostępnionych linków dynamicznych Firebase uniwersalnymi linkami (w miarę możliwości) i dalsze korzystanie z nich.

Sposób wykonania tego kroku zależy od tego, gdzie i jak publikujesz Linki dynamiczne Firebase.

Aby ułatwić Ci śledzenie dotychczasowych Linków dynamicznych Firebase, które mają zostać przeniesione, opublikujemy przewodnik, w którym wyjaśnimy, jak eksportować metadane krótkich linków z Linków dynamicznych Firebase. Więcej informacji znajdziesz w dokumentacji dotyczącej wycofania dynamicznych linków.