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ępuje 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:

Ten przewodnik po migracji ma zastąpić Linki dynamiczne Firebase w ten sposób:

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 zapewni użytkownikom:

• Klikalny precyzyjny link, który otwiera aplikację po jej zainstalowaniu.
• Kontynuacja ścieżki użytkownika, która prowadzi go do określonej części aplikacji po jej otwarciu

Jednak precyzyjny link aplikacji lub precyzyjny link nie będzie dawać użytkownikom takich efektów (które wcześniej dotyczyły Linków dynamicznych Firebase):

• Kierowanie użytkowników do sklepu, w którym mogą pobrać i zainstalować aplikację na danym urządzeniu
• 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 Dynamic Links w Firebase (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 pliki konfiguracji linku aplikacji lub uniwersalnego linku i przechowuj je w swojej domenie hostingowej.

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łe wartości mogą się różnić w zależności od platformy, przejdź więc do sekcji przewodnika poniżej w zależności od platformy, którą chcesz przenieść w pierwszej kolejności.

• 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 w nowych linkach, 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

Tworzenie i przechowywanie plików konfiguracji linku aplikacji w nowej domenie hostingowej

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.

Etapy tworzenia i hostowania pliku assetlinks.json

Plik assetlinks.json umożliwia nam udostępnienie listy autoryzowanych aplikacji, które mogą obsługiwać zawartość domeny internetowej, której będziemy używać w linkach 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 folderze 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 Android Studio możesz wykorzystać do wygenerowania rekordu sha256_cert_fingerprints na potrzeby debugowania. Znajdziesz go pod adresem /Users/<username>/.android/debug.keystore na urządzeniach z systemem macOS i Linux oraz C:\Users\<username>\.android\debug.keystore w systemie Windows.

   Z tego magazynu kluczy możesz pobrać wartość SHA256 za pomocą narzędzia do obsługi kluczy.

   Więcej informacji o tym, jak to zrobić, znajdziesz w tej sekcji w dokumentacji dotyczącej linków aplikacji.

   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 go zindeksować na potrzeby hostingu.

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

5. Po utworzeniu pliku assetlinks.json uruchom polecenie firebase deploy, aby hostować zmiany.

   Aby wykonać podane powyżej polecenie wdrażania, musisz mieć zainstalowany interfejs wiersza poleceń Firebase.

   firebase deploy --only hosting
   

6. Zweryfikuj plik assetlinks.json na stronie https://your-project-domain.web.app/.well-known/assetlinks.json

Utwórz nowe linki aplikacji pasujące do schematu precyzyjnych linków używanego 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 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 parametru linku 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

Następnym krokiem po wybraniu domeny, wybraniu schematu precyzyjnych linków i przeniesieniu Linków dynamicznych Firebase do linków aplikacji jest zaktualizowanie aplikacji na Androida i jej kodu, tak aby otrzymywały nowe precyzyjne linki.

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ć elementu MainActivity do obsługi niektórych precyzyjnych linków. 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 dla obsługi linków głębokich z domeny wxample.web.app i że 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 w MainActivity, by pobierać dane precyzyjnych linków i używać go do obsługi precyzyjnych linków w Twojej aplikacji. Przypomina to logikę zakodowaną w aplikacji po integracji z Linkami dynamicznymi 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 testować utworzone linki 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).

Procedura 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ższą treść 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. Plik AASA jest już gotowy, więc możemy wdrożyć Firebase, aby hostować zmiany.

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

Utwórz nowe uniwersalne linki pasujące do schematu precyzyjnych linków używanego 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, ż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 istniejące 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 skorzystanie z pełnej dokumentacji dotyczącej uniwersalnych linków dotyczących konfigurowania aplikacji pod kątem obsługi precyzyjnych linków. Najważniejsze czynności to:

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

2. Odbierz precyzyjny link 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. Klika przycisk +, aby dodać do projektu dodatkową domenę w formacie „applinks:”.

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

W tym celu najpierw zaktualizuj plik AppDelegate.swift w taki sposób, aby odpowiadał na link uniwersalny, dodając 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 linki uniwersalne, uruchamiając aplikację na urządzeniu fizycznym lub 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 miejsca i sposobu publikowania linków dynamicznych 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.