Migracja z łączy dynamicznych do łączy aplikacji & Linki uniwersalne

W tym przewodniku po migracji skupiono się na korzystaniu z łączy aplikacji i łączy uniwersalnych oraz opcjonalnie przy użyciu hostingu Firebase do hostowania plików skojarzeń aplikacji z witryną.

Ta migracja zastępuje następujące funkcje łączy dynamicznych Firebase:

Funkcja Linki dynamiczne Firebase Linki do aplikacji / Linki uniwersalne
Przekieruj użytkowników do sklepu odpowiedniego dla ich urządzenia za pomocą jednego kliknięcia linku
Zapewnij użytkownikom kontynuację podróży po pobraniu i zainstalowaniu aplikacji, korzystając z odroczonego głębokiego linku
Zapewnij użytkownikom kontekstowe środowisko, korzystając z treści z głębokimi linkami w Twojej aplikacji (jeśli jest już zainstalowana)
Dostarczaj dane analityczne związane ze zdarzeniami kliknięcia linku dynamicznego
Zapewnij możliwość tworzenia krótkich adresów URL linków

Jeśli w dalszym ciągu potrzebujesz do migracji innych funkcji Firebase Dynamic Link, które nie są obsługiwane w tym przewodniku, zapoznaj się z innymi scenariuszami migracji w dokumentacji Często zadawane pytania dotyczące wycofywania łączy dynamicznych .

Załóżmy, że masz łącze dynamiczne Firebase, które wygląda tak:

Przykład łącza dynamicznego
Nazwa łącza Witamy w witrynie example.com
Głęboki link https://example.web.app/welcome
Aplikacja na Androida com.example.android
Aplikacja Apple com.example.ios
Długie łącze dynamiczne https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Krótki link dynamiczny https://example.page.link/m9Mm

Celem tego przewodnika po migracji jest zastąpienie linków dynamicznych Firebase w następujący sposób:

https://example.page.link/m9Mm

Z precyzyjnymi linkami App Link/Universal Link, które wyglądają tak:

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

Pamiętaj, że precyzyjny link App Link / Universal Link zapewni użytkownikom następujące informacje:

  • Głęboki link, który mogą kliknąć, i który otworzy Twoją aplikację, gdy jest już zainstalowana
  • Kontynuacja podróży użytkownika, prowadząca go do określonej części aplikacji po jej otwarciu

Jednak precyzyjny link App Link / Universal Link nie zapewni użytkownikom następujących zachowań (co wcześniej zapewniało Firebase Dynamic Links):

  • Kierowanie użytkowników do odpowiedniego sklepu dla ich urządzenia w celu pobrania i zainstalowania aplikacji
  • Zapewnienie kontynuacji podróży użytkownika po pobraniu, zainstalowaniu i otwarciu aplikacji po raz pierwszy

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

Zanim zaczniesz

Firebase Dynamic Links wykorzystuje App Links (na Androidzie) i Universal Links (na iOS) w swojej własnej implementacji, aby zapewnić funkcję głębokiego linkowania po już zainstalowaniu aplikacji.

W tym przewodniku opisano, jak tworzyć własne linki aplikacji i linki uniwersalne przy użyciu Firebase Hosting, aby zastąpić tę część funkcjonalności zapewnianej przez linki dynamiczne Firebase podczas migracji łączy dynamicznych Firebase do nowego rozwiązania do migracji łączy aplikacji / łączy uniwersalnych.

Aby ukończyć migrację, potrzebne będą następujące informacje:

  • Linki dynamiczne Firebase, które chcesz przenieść
  • Parametry adresu URL głębokiego linku zawarte w linkach dynamicznych
  • Domena, której planujesz użyć do zastąpienia poprzedniej domeny Firebase Dynamic Links (jeśli dotyczy)

Możesz skorzystać z przewodnika Eksportuj metadane linków dynamicznych, aby wyeksportować istniejące metadane linków i uzyskać informacje wymienione powyżej.

Omówienie etapów migracji

  1. Udostępnij nową domenę (jeśli jeszcze jej nie masz, której chcesz używać) do hostowania plików konfiguracyjnych App Link/Universal Link za pomocą Firebase Hosting.

  2. Utwórz i hostuj pliki konfiguracyjne App Link / Universal Link w swojej domenie hostingowej.

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

  4. Zaktualizuj swoje aplikacje i kod aplikacji na Androida/iOS, aby otrzymywać głębokie linki.

  5. Testowanie integracji łączy aplikacji / łączy uniwersalnych.

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

Pierwszy krok będzie wspólny dla procesów migracji App Links i Universal Link. Pozostała część będzie się różnić w zależności od platformy, więc przejdź do sekcji poniższego przewodnika w zależności od platformy, którą chcesz najpierw przeprowadzić migrację.

Wybierz domenę

Pierwszym krokiem jest wybranie domeny, której chcesz używać dla łączy aplikacji/linków uniwersalnych. Będzie to domena, która będzie używana dla nowych linków udostępnianych 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ć również pliki konfiguracyjne App Link / Universal Link.

Skonfiguruj hosting Firebase

Następnie musisz skonfigurować instancję Firebase Hosting .

Zanim skończysz konfigurować instancję Firebase Hosting, będziesz mieć domenę podobną do your-project-domain .web.app ` lub domenę niestandardową , jeśli wolisz.

Aby móc korzystać z łączy aplikacji, musisz hostować plik konfiguracyjny, który pomoże ustanowić bezpieczne powiązanie między domeną używaną w Twoich łączach a Twoją aplikacją. W przypadku łączy aplikacji jest to plik assetlinks.json .

Kroki tworzenia i hostowania pliku aktywówlinks.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 naszych łączy aplikacji. Sam plik aktywówlinks.json musi znajdować się w katalogu głównym domeny internetowej pod ścieżką: /.well-known .

Aby dokończyć tę konfigurację, wykonaj poniższe czynności:

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

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

  3. Skopiuj poniższą treść do pliku aktywówlinks.json, zwracając uwagę na znaczenie każdego pola poniżej:

    [{
      "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 udostępnić
    • package_name — odnosi się do identyfikatora aplikacji zadeklarowanego w pliku build.gradle aplikacji
    • sha256_cert_fingerprints — odnosi się do odcisku palca SHA256 pliku magazynu kluczy używanego do podpisywania aplikacji.

    Możesz użyć pliku debug.keystore używanego przez Android Studio do wygenerowania rekordu sha256_cert_fingerprints na potrzeby debugowania. Plik można znaleźć pod /Users/<username>/.android/debug.keystore >/.android/debug.keystore na komputerach Mac i Linux oraz C:\Users\<username>\.android\debug.keystore w systemie Windows.

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

    Więcej instrukcji dotyczących wykonania tego kroku można znaleźć w tej sekcji dokumentacji łączy aplikacji .

    Alternatywnie możesz także użyć Asystenta łączy aplikacji w Android Studio, aby wygenerować zawartość pliku aktywówlinks.json i skonfigurować aplikację do obsługi łączy aplikacji.

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

    "headers": [
      {
        "source": "/.well-known/assetlinks.json",
        "headers": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ]
      }
    ]
    
  5. Teraz, gdy mamy już plik aktywówlinks.json, uruchom firebase deploy , aby hostować zmiany.

    Pamiętaj, że aby uruchomić powyższe polecenie wdrażania, musisz mieć zainstalowany interfejs CLI Firebase .

    firebase deploy --only hosting
    
  6. Zweryfikuj plik aktywówlinks.json, przechodząc do https:// your-project-domain .web.app/.well-known/assetlinks.json

Na tym etapie odtworzysz głębokie 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 aplikacji.

Załóżmy na przykład, że masz następujące łącze dynamiczne Firebase:

Przykład łącza dynamicznego
Nazwa łącza Witamy w witrynie example.com
Głęboki link https://example.web.app/welcome
Aplikacja na Androida com.example.android
Aplikacja Apple com.example.ios
Długie łącze dynamiczne https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Krótki link dynamiczny https://example.page.link/m9Mm

W takim przypadku wyodrębnisz parametr głębokiego linku, tj. https://example.web.app/welcome i użyjesz go teraz jako parametru App Link dla swojej aplikacji.

Będziesz chciał powtórzyć ten proces dla każdego łącza dynamicznego Firebase, do którego chcesz przeprowadzić migrację za pomocą łączy aplikacji/linków uniwersalnych, i zreplikować zastosowany schemat głębokiego linkowania.

Na przykład zapoznaj się z następującym zestawem krótkich linków, parametrów precyzyjnych linków i przeniesionych wartości precyzyjnych linków Firebase:

Krótki link Parametr głębokiego linku Przeniesiony precyzyjny link
twojaaplikacja.strona.link/welcome https://example.com/welcome twojaaplikacja.web.app/welcome
twojaaplikacja.strona.link/c7sn https://example.com/main/?p=23&t=1 twojaaplikacja.web.app/main/?p=23&t=1
twojaaplikacja.strona.link/social https://example.com/zaproszenie do znajomego/?add=1 twojaaplikacja.web.app/friendinvite/?add=1

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 aplikacji zamiast poprzednich linków dynamicznych Firebase.

Następnym krokiem po wybraniu domeny, wybraniu schematu głębokiego linkowania i migracji linków dynamicznych Firebase do linków aplikacji jest aktualizacja aplikacji na Androida i kodu aplikacji, aby otrzymać nowe precyzyjne linki.

Zalecamy zapoznanie się z pełną dokumentacją dotyczącą łączy aplikacji tutaj lub alternatywnie z przewodnikiem Android Studio dotyczącym konfigurowania aplikacji do obsługi precyzyjnych linków, ale główne kroki obejmują:

  1. Identyfikacja, które działania powinny obsługiwać odpowiednie głębokie linki
  2. Dodanie filtra intencji dla tych działań w pliku AndroidManifest.xml
  3. Otrzymanie głębokiego linku w kodzie aplikacji Twoich działań

Załóżmy, że chcesz użyć MainActivity do obsługi niektórych precyzyjnych linków. Aby to zrobić, musisz dodać następujący filtr intencji do MainActivity w pliku 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>

W tym kroku określasz, że MainActivity jest miejscem docelowym do obsługi precyzyjnych linków z domeny wxample.web.app i zawiera prefiks ścieżki /welcome. Pamiętaj, że będziesz musiał także określić atrybut android:autoVerify="true", który pozwala wyznaczyć aplikację jako domyślną procedurę obsługi dla danego typu łącza.

Na koniec musisz dodać kod do swojej MainActivity, aby pobrać dane głębokiego linku i użyć ich do obsługi precyzyjnego linku w swojej aplikacji. Jest to podobne do logiki, którą mogłeś już zakodować w swojej aplikacji podczas integracji z 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()
}

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

Musisz utworzyć klikalny link, korzystając z domeny skonfigurowanej dla łączy aplikacji, a następnie kliknąć ten link, aby mieć pewność, że otworzy się on w Twojej aplikacji i przekieruje Cię do zamierzonego działania.

Alternatywnie możesz także przetestować integrację łączy aplikacji za pomocą Asystenta łączy aplikacji w Android Studio lub użyć następującego polecenia dla skonfigurowanego adresu URL łącza aplikacji, aby upewnić się, że poprawnie uruchamia pasujące działanie:

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

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

Wykonanie tego kroku będzie się różnić w zależności od tego, gdzie i w jaki sposób opublikowano linki dynamiczne Firebase, ale aby ułatwić śledzenie, które z nich istnieją, możesz wyeksportować istniejące metadane łącza dynamicznego Firebase. Zobacz przewodnik Eksportuj metadane łączy dynamicznych .

Aby móc korzystać z Universal Links, musisz udostępnić plik konfiguracyjny, który pomoże ustanowić bezpieczne powiązanie między domeną używaną w Twoich linkach a Twoją aplikacją. W przypadku Universal Links jest to plik apple-app-site-association (znany również jako plik AASA).

Kroki tworzenia i hostowania pliku skojarzenia witryny z aplikacją Apple

Plik AASA umożliwia nam udostępnienie listy autoryzowanych aplikacji, które obsługują zawartość domeny internetowej, której będziemy używać w przypadku naszych łączy uniwersalnych. Sam plik AASA musi znajdować się w katalogu głównym domeny internetowej pod ścieżką: /.well-known.

Aby dokończyć tę konfigurację, wykonaj poniższe czynności:

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

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

  3. Skopiuj poniższą treść do pliku skojarzenia witryny z aplikacją Apple, zwracając uwagę na znaczenie każdego pola poniżej:

    {
      "applinks": {
        "apps": [],
        "details": [
          {
            "appId": "$TEAM_ID.com.firebase.UniversalLinks",
            "paths": [
              "NOT /_/*",
              "/*"
            ]
          }
        ]
      }
    }
    
    • $TEAM_ID.BundleId - pełna nazwa aplikacji autoryzowanej do obsługi łączy
  4. Zaktualizuj plik firebase.json, aby zaindeksować plik na potrzeby hostingu.

    "headers": [
      {
        "source": "/.well-known/apple-app-site-association",
        "headers": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ]
      }
    ]
    
  5. Teraz, gdy mamy już plik AASA, wykonaj wdrożenie Firebase, aby hostować zmiany.

  6. Zweryfikuj plik AASA, przechodząc na stronę https:// your-project-domain .web.app/.well-known/app-app-site-association

Na tym etapie odtworzysz głębokie 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 uniwersalnych.

Załóżmy na przykład, że masz następujące łącze dynamiczne Firebase:

Przykład łącza dynamicznego
Nazwa łącza Witamy w witrynie example.com
Głęboki link https://example.web.app/welcome
Aplikacja na Androida com.example.android
Aplikacja Apple com.example.ios
Długie łącze dynamiczne https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Krótki link dynamiczny https://example.page.link/m9Mm

W takim przypadku wyodrębniłbyś parametr głębokiego linku - tj. https://example.web.app/welcome i użył go teraz jako parametru Universal Link dla swojej aplikacji.

Będziesz chciał powtórzyć ten proces dla każdego łącza dynamicznego Firebase, do którego chcesz przeprowadzić migrację za pomocą łączy aplikacji/linków uniwersalnych, i zreplikować zastosowany schemat głębokiego linkowania.

Na przykład zapoznaj się z następującym zestawem krótkich linków, parametrów precyzyjnych linków i przeniesionych wartości precyzyjnych linków Firebase:

Krótki link Parametr głębokiego linku Przeniesiony precyzyjny link
twojaaplikacja.strona.link/welcome https://example.com/welcome twojaaplikacja.web.app/welcome
twojaaplikacja.strona.link/c7sn https://example.com/main/?p=23&t=1 twojaaplikacja.web.app/main/?p=23&t=1
twojaaplikacja.strona.link/social https://example.com/zaproszenie do znajomego/?add=1 twojaaplikacja.web.app/friendinvite/?add=1

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 uniwersalne zamiast poprzednich linków dynamicznych Firebase.

Następnym krokiem po wybraniu domeny, wybraniu schematu głębokiego linkowania i migracji linków dynamicznych Firebase do linków uniwersalnych jest aktualizacja aplikacji na iOS i kodu aplikacji, aby otrzymać nowe precyzyjne linki.

Zalecamy zapoznanie się z pełną dokumentacją Universal Links dotyczącą konfigurowania aplikacji do obsługi precyzyjnych linków, ale główne kroki obejmują:

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

  2. Otrzymaj precyzyjny link w kodzie aplikacji

Aby zaktualizować konfigurację projektu, aby umożliwić aplikacji obsługę precyzyjnych linków, musisz dodać dodatkową powiązaną domenę do swojego projektu w xCode dla domeny, której teraz planujesz używać do hostowania witryny aplikacji Apple- plik skojarzony.

Można tego dokonać poprzez:

  1. Otwieranie Xcode
  2. Wybór projektu w nawigatorze plików
  3. Przejście do karty Podpisywanie i możliwości w ustawieniach projektu
  4. Przejdź do sekcji Powiązane domeny
  5. Kliknięcie przycisku + powoduje dodanie dodatkowej domeny do projektu w formacie „applinks”: „.

Na koniec musisz zaktualizować kod aplikacji, aby móc odbierać przychodzące głębokie linki.

Aby to osiągnąć, najpierw zaktualizuj plik AppDelegate.swift, aby odpowiadał na łącze uniwersalne, dodając następujący 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 Universal Link i rejestruje adres URL precyzyjnego linku, jeśli istnieje.

Teraz wywołamy tę samą metodę showReceivedUrl z klasy SceneDelegate, ponieważ jeśli aplikacja jest już otwarta w momencie kliknięcia łącza uniwersalnego, wywołane zostanie wywołanie zwrotne łącza uniwersalnego w SceneDelegate .

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

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

Musisz utworzyć klikalny link, korzystając z domeny skonfigurowanej dla łączy uniwersalnych, a następnie kliknąć ten link, aby mieć pewność, że otworzy się on w Twojej aplikacji i przeniesie Cię do zamierzonego ekranu w aplikacji.

Obsługa inteligentnych banerów aplikacji

Zdecydowanie zalecamy używanie inteligentnych banerów aplikacji , aby zapewnić użytkownikom wrażenia podobne do łączy dynamicznych Firebase.

Dzięki inteligentnym banerom aplikacji użytkownicy zostaną przeniesieni do sklepu App Store w celu zapoznania się z listą aplikacji, jeśli nie są one jeszcze zainstalowane na ich urządzeniach. Opcjonalnie możesz także skonfigurować parametr przekazywany do aplikacji po jej pobraniu i zainstalowaniu, aby zapewnić użytkownikom kontynuację podróży. Jeśli Twoja aplikacja jest już zainstalowana, otworzy się możliwość przekazania parametru do Twojej aplikacji, aby pomóc użytkownikowi w skierowaniu użytkownika do odpowiedniej treści na podstawie klikniętego banera aplikacji inteligentnej.

Ostatnim krokiem migracji będzie zastąpienie opublikowanych lub udostępnionych linków dynamicznych Firebase linkami uniwersalnymi, jeśli 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 w jaki sposób opublikowano linki dynamiczne Firebase.

Aby pomóc Ci w śledzeniu migracji istniejących linków dynamicznych Firebase, opublikujemy przewodnik na temat eksportowania metadanych krótkich linków z linków dynamicznych Firebase. Więcej aktualizacji znajdziesz w naszym dokumencie z często zadawanymi pytaniami na temat wycofywania łączy dynamicznych .