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

Ten przewodnik migracji koncentruje się na używaniu linków aplikacji i uniwersalnych linków, a opcjonalnie także Hostingu Firebase do hostowania plików powiązania aplikacji z witryną.

Ta migracja zastępuje te funkcje Linków dynamicznych Firebase:

Jeśli do migracji nadal potrzebujesz innych funkcji Linków dynamicznych Firebase, które nie są obsługiwane w tym przewodniku, zapoznaj się z innymi scenariuszami migracji w dokumentacji najczęstszych pytań dotyczących wycofania Linków dynamicznych.

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

Celem tego przewodnika migracji jest zastąpienie Linków dynamicznych Firebase w ten sposób:

https://example.page.link/m9Mm

W przypadku precyzyjnych linków do aplikacji lub uniwersalnych linków, które wyglądają tak:

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

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

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

Jednak precyzyjny link w postaci linku aplikacji lub uniwersalnego linku nie będzie zapewniać użytkownikom tych funkcji (które wcześniej były dostępne w przypadku linków dynamicznych Firebase):

• kierowanie użytkowników do odpowiedniego sklepu na ich urządzeniu, aby mogli pobrać i zainstalować Twoją aplikację;
• umożliwienie kontynuowania ścieżki użytkownika po pobraniu, zainstalowaniu i pierwszym otwarciu aplikacji;

Zwróć uwagę na różnice w działaniu i funkcjonalności tych linków aplikacji i uniwersalnych linków w porównaniu z linkami dynamicznymi Firebase, które zostały wymienione w tabeli powyżej.

Zanim zaczniesz

Linki dynamiczne Firebase wykorzystują w swojej implementacji linki aplikacji (na Androidzie) i linki uniwersalne (na iOS), aby zapewnić funkcję precyzyjnego linkowania po zainstalowaniu aplikacji.

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

Aby przeprowadzić migrację, musisz podać te informacje:

• Linki dynamiczne Firebase, które chcesz przenieść
• Parametry adresu URL precyzyjnego linku zawarte w dynamicznych linkach
• domena, której zamierzasz użyć do zastąpienia poprzedniej domeny dynamicznych linków Firebase (w odpowiednich przypadkach);

Aby wyeksportować metadane istniejących linków i uzyskać wymienione powyżej informacje, możesz skorzystać z przewodnika po eksportowaniu metadanych linków dynamicznych.

Omówienie kroków migracji

1. Zarezerwuj nową domenę (jeśli nie masz jeszcze domeny, której chcesz użyć) do hostowania plików konfiguracyjnych linków do aplikacji lub linków uniwersalnych za pomocą Hostingu Firebase.

2. Utwórz i hostuj pliki konfiguracyjne linków do aplikacji lub uniwersalnych linków w domenie hostingu.

3. Utwórz nowe linki aplikacji lub linki uniwersalne pasujące do schematu precyzyjnego linku 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 do aplikacji / uniwersalnych linków.

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

Pierwszy krok będzie wspólny dla obu procesów migracji: linków aplikacji i linków uniwersalnych. Pozostałe kroki różnią się w zależności od platformy, więc przejdź do odpowiedniej sekcji przewodnika poniżej, aby dowiedzieć się, którą platformę chcesz przenieść w pierwszej kolejności.

• Kroki migracji linków do aplikacji na Androida
• Instrukcje migracji uniwersalnych linków na iOS

Udostępnij nową domenę do hostowania plików konfiguracyjnych linków do aplikacji lub linków uniwersalnych za pomocą Hostingu Firebase.

Wybierz domenę

Pierwszym krokiem jest wybranie domeny, której chcesz używać w przypadku linków do aplikacji lub uniwersalnych linków. Będzie to domena, która będzie używana w nowych linkach udostępnianych użytkownikom.

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

Konfigurowanie Hostingu Firebase

Następnie musisz skonfigurować instancję Hostingu Firebase.

Po zakończeniu konfigurowania instancji Hostingu Firebase będziesz mieć domenę podobną do your-project-domain.web.app lub domenę niestandardową, jeśli wolisz.

Kroki migracji linków aplikacji na Androida

Utwórz i hostuj pliki konfiguracyjne linków do aplikacji w nowej domenie hostingowej.

Aby korzystać z linków do aplikacji, musisz hostować plik konfiguracyjny, który pomaga nawiązać bezpieczne powiązanie między domeną używaną w linkach a aplikacją. W przypadku linków do aplikacji jest to plik assetlinks.json.

Kroki 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 przypadku linków do aplikacji. Sam plik assetlinks.json musi być hostowany w katalogu głównym domeny pod ścieżką: /.well-known.

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

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

2. Utwórz plik o nazwie assetlinks.json w folderze .well-known.

3. Skopiuj do pliku assetlinks.json podaną niżej treść, 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 – nazwa aplikacji, którą chcesz udostępnić
   • package_name – odnosi się do identyfikatora applicationId zadeklarowanego w pliku build.gradle aplikacji.
   • sha256_cert_fingerprints – odnosi się do odcisku cyfrowego SHA256 pliku magazynu kluczy, którego używasz do podpisywania aplikacji.

   Do wygenerowania rekordu sha256_cert_fingerprints na potrzeby debugowania możesz użyć pliku debug.keystore używanego przez Androida Studio. Plik znajdziesz w lokalizacji /Users/<username>/.android/debug.keystore na komputerach Mac i z systemem Linux oraz C:\Users\<username>\.android\debug.keystore na komputerach z systemem Windows.

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

   Więcej instrukcji dotyczących tego kroku znajdziesz w tej sekcji dokumentacji dotyczącej linków do aplikacji.

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

4. Zaktualizuj plik firebase.json, aby indeksować plik na potrzeby hostingu.

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

5. Teraz, gdy mamy już plik assetlinks.json, uruchom firebase deploy, aby hostować zmiany.

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

   firebase deploy --only hosting
   

6. Sprawdź plik assetlinks.json, przechodząc dohttps://your-project-domain.web.app/.well-known/assetlinks.json

Utwórz nowe linki do aplikacji pasujące do schematu linku do konkretnego miejsca używanego w Linkach dynamicznych Firebase.

W tym kroku odtworzysz precyzyjne linki z Linków dynamicznych Firebase za pomocą 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 takim przypadku wyodrębnisz parametr precyzyjnego linku, czyli https://example.web.app/welcome, i użyjesz go jako parametru linku aplikacji.

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

Na przykład zobacz ten zestaw krótkich linków usługi Linki dynamiczne Firebase, parametrów precyzyjnych linków i przeniesionych wartości precyzyjnych linków:

Następnie musisz zastąpić wszystkie opublikowane lub udostępnione linki dynamiczne Firebase nowymi, przeniesionymi precyzyjnymi linkami, aby użytkownicy klikali te linki do aplikacji zamiast poprzednich linków dynamicznych Firebase.

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

Po wybraniu domeny, schematu precyzyjnych linków i przeniesieniu Linków dynamicznych Firebase na linki do aplikacji musisz zaktualizować aplikację na Androida i kod aplikacji, aby otrzymywać nowe precyzyjne linki.

Zalecamy zapoznanie się z pełną dokumentacją linków do aplikacji lub przewodnikiem po Android Studio dotyczącym konfigurowania aplikacji do obsługi precyzyjnych linków. Główne kroki to:

1. określanie, które aktywności powinny obsługiwać poszczególne precyzyjne linki;
2. Dodawanie filtra intencji dla tych działań w pliku AndroidManifest.xml
3. Odbieranie precyzyjnego linku w kodzie aplikacji aktywności

Załóżmy, że chcesz użyć klasy MainActivity do obsługi niektórych linków do aplikacji. Aby to zrobić, musisz dodać ten filtr intencji do pliku AndroidManifest.xml w głównym działaniu:

<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 precyzyjnych linków z domeny wxample.web.app, które zawierają prefiks ścieżki /welcome. Pamiętaj, że musisz też określić atrybut android:autoVerify="true", który pozwala oznaczyć aplikację jako domyślny moduł do obsługi danego typu linku.

Na koniec musisz dodać do pliku MainActivity kod, który będzie pobierać dane linku bezpośredniego i wykorzystywać je do obsługi linków bezpośrednich w aplikacji. Jest to podobne do logiki, którą być może masz już w aplikacji, jeśli została ona zintegrowana z Dynamicznymi linkami 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

Utworzone linki do aplikacji możesz przetestować, uruchamiając aplikację na urządzeniu fizycznym lub w emulatorze Androida.

Musisz utworzyć klikalny link, używając domeny skonfigurowanej dla linków do aplikacji, a następnie kliknąć ten link, aby sprawdzić, czy otwiera się w aplikacji i przekierowuje do odpowiedniej aktywności.

Integrację linków aplikacji możesz też przetestować za pomocą Asystenta linków do aplikacji w Androidzie Studio lub użyć tego polecenia w przypadku skonfigurowanego adresu URL linku aplikacji, aby upewnić się, że 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 linkami do aplikacji

Ostatnim krokiem migracji będzie zastąpienie opublikowanych lub udostępnionych linków dynamicznych Firebase linkami do aplikacji wszędzie tam, gdzie to możliwe, i dalsze korzystanie z linków do aplikacji.

Wykonanie tego kroku będzie się różnić w zależności od tego, gdzie i jak opublikowano Linki dynamiczne Firebase, ale aby śledzić, które z nich istnieją, możesz wyeksportować metadane istniejących Linków dynamicznych Firebase. Zapoznaj się z przewodnikiem po eksportowaniu metadanych dynamicznych linków.

Czynności związane z migracją w przypadku uniwersalnych linków na iOS

Utwórz i hostuj pliki konfiguracyjne uniwersalnych linków w nowej domenie hostingowej.

Aby korzystać z uniwersalnych linków, musisz hostować plik konfiguracyjny, który pomaga nawiązać bezpieczne powiązanie między domeną używaną w linkach a aplikacją. W przypadku uniwersalnych linków jest to plik apple-app-site-association (znany też jako plik AASA).

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

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

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

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

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

3. Skopiuj do pliku apple-app-site-association te treści: zwróć uwagę na znaczenie poszczególnych pól poniżej:

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

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

4. Zaktualizuj plik firebase.json, aby indeksować plik na potrzeby hostingu.

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

5. Po utworzeniu pliku AASA wdróż zmiany za pomocą polecenia firebase deploy.

6. Sprawdź plik AASA, otwierając stronę https://your-project-domain.web.app/.well-known/app-app-site-association

Utwórz nowe linki uniwersalne pasujące do schematu precyzyjnych linków używanego w linkach dynamicznych Firebase.

W tym kroku odtworzysz precyzyjne linki z Linków dynamicznych Firebase za pomocą zwykłych adresów URL precyzyjnych linków pasujących do nowej domeny utworzonej na potrzeby uniwersalnych linków.

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

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

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

Na przykład zobacz ten zestaw krótkich linków usługi Linki dynamiczne Firebase, parametrów precyzyjnych linków i przeniesionych wartości precyzyjnych linków:

Następnie musisz zastąpić wszystkie opublikowane lub udostępnione Linki dynamiczne Firebase nowymi, przeniesionymi precyzyjnymi linkami, aby użytkownicy klikali te uniwersalne linki zamiast poprzednich Linków dynamicznych Firebase.

Aktualizowanie aplikacji na iOS i kodu aplikacji, aby otrzymywać precyzyjne linki

Po wybraniu domeny, schematu precyzyjnego linkowania i przeniesieniu linków dynamicznych Firebase na uniwersalne linki musisz zaktualizować aplikację na iOS i kod aplikacji, aby otrzymywać nowe precyzyjne linki.

Zalecamy zapoznanie się z pełną dokumentacją uniwersalnych linków, w której znajdziesz informacje o konfigurowaniu aplikacji do obsługi precyzyjnych linków. Główne kroki to:

1. Zaktualizuj konfigurację projektu, aby umożliwić aplikacji obsługę linków bezpośrednich z nowo utworzonej domeny.

2. Odbieranie precyzyjnego linku w kodzie aplikacji

Aby zaktualizować konfigurację projektu i umożliwić aplikacji obsługę linków bezpośrednich, musisz dodać do projektu w Xcode dodatkową powiązaną domenę dla domeny, której zamierzasz używać do hostowania pliku apple-app-site-associate.

Możesz to zrobić w jeden z tych sposobów:

1. Otwieranie Xcode
2. Wybieranie projektu w nawigatorze plików
3. Otwieranie karty Podpisywanie i możliwości w ustawieniach projektu
4. Przewiń w dół do sekcji Powiązane domeny.
5. Kliknij przycisk +, aby dodać dodatkową domenę do projektu w formacie „applinks:”.

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

Aby to zrobić, najpierw zaktualizuj plik AppDelegate.swift, 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 zwrotnego uniwersalnego linku i rejestruje adres URL precyzyjnego linku, jeśli jest on obecny.

Teraz wywołamy tę samą metodę showReceivedUrl z klasy SceneDelegate, ponieważ jeśli aplikacja jest już otwarta w momencie, gdy użytkownik kliknie uniwersalny link, wywołanie zwrotne uniwersalnego linku w klasie SceneDelegate zostanie wywołane.

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

Testowanie uniwersalnych linków

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

Musisz utworzyć klikalny link, używając domeny skonfigurowanej dla linków uniwersalnych, a następnie kliknąć ten link, aby sprawdzić, czy otwiera się w aplikacji i przenosi Cię do odpowiedniego ekranu w aplikacji.

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 aplikacji użytkownicy, którzy nie mają jeszcze zainstalowanej aplikacji, zostaną przekierowani do strony z informacjami o niej w App Store. Możesz też opcjonalnie skonfigurować parametr, który będzie przekazywany do aplikacji po jej pobraniu i zainstalowaniu, aby zapewnić użytkownikom kontynuację ich ścieżki. Jeśli aplikacja jest już zainstalowana, otworzy się, przekazując parametr do Twojej aplikacji, aby pomóc użytkownikowi przejść do odpowiednich treści na podstawie klikniętego inteligentnego banera aplikacji.

Zastępowanie opublikowanych lub udostępnionych Linków dynamicznych Firebase linkami do aplikacji

Ostatnim krokiem migracji będzie zastąpienie opublikowanych lub udostępnionych linków dynamicznych Firebase linkami uniwersalnymi wszędzie tam, gdzie to możliwe, i dalsze korzystanie z linków uniwersalnych.

Wykonanie tego kroku będzie się różnić w zależności od tego, gdzie i jak opublikowano Linki dynamiczne Firebase.

Aby ułatwić Ci śledzenie istniejących Linków dynamicznych Firebase, które mają zostać przeniesione, opublikujemy przewodnik po eksportowaniu metadanych krótkich linków z Linków dynamicznych Firebase. Więcej informacji znajdziesz w dokumencie z odpowiedziami na najczęstsze pytania dotyczące wycofania dynamicznych linków.