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

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

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

Funkcja Linki dynamiczne Firebase Linki aplikacji / uniwersalne linki
Przekierowywanie użytkowników do odpowiedniego sklepu na ich urządzeniu za pomocą jednego kliknięcia linku ★
zapewnić użytkownikom kontynuację ścieżki po pobraniu i zainstalowaniu aplikacji za pomocą odroczonego precyzyjnego linku; ★
Zapewnij użytkownikom kontekstowe wrażenia dzięki treściom z precyzyjnych linków w aplikacji (jeśli jest już zainstalowana).
Przekazywanie danych analitycznych związanych ze zdarzeniami kliknięcia linku dynamicznego
Umożliwia tworzenie krótkich adresów URL.

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 FAQ dotyczących wycofania Linków dynamicznych.

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

Przykład linku dynamicznego
Nazwa linku Witamy w Example.com
Precyzyjny link https://example.web.app/welcome
Aplikacja na Androida com.example.android
Aplikacja Apple com.example.ios
Długi link dynamiczny 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 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 aplikacji lub uniwersalny link 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, aby mogli pobrać i zainstalować aplikację na swoim urządzeniu;
  • zapewnienie kontynuacji ś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 / 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 do 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 do aplikacji i linki uniwersalne za pomocą Hostingu Firebase, aby zastąpić tę część funkcjonalności zapewnianej przez Linki dynamiczne Firebase podczas migracji Linków dynamicznych Firebase do nowego rozwiązania do migracji linków do aplikacji i linków uniwersalnych.

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 stosownych przypadkach);

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

Omówienie etapó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 / linków uniwersalnych w domenie hostingu.

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

  6. Zastąp opublikowane lub udostępnione Linki dynamiczne Firebase linkami 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 będą się różnić w zależności od platformy, więc przejdź do odpowiedniej sekcji przewodnika poniżej, aby dowiedzieć się, jak przenieść dane z wybranej platformy.

Wybierz domenę

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

Jeśli korzystasz z Firebase Hosting, 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.

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 internetowej 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ą poniż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 do https://your-project-domain.web.app/.well-known/assetlinks.json

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 ten link dynamiczny Firebase:

Przykład linku dynamicznego
Nazwa linku Witamy w Example.com
Precyzyjny link https://example.web.app/welcome
Aplikacja na Androida com.example.android
Aplikacja Apple com.example.ios
Długi link dynamiczny 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 precyzyjnego linku, czyli https://example.web.app/welcome, i użyjesz go jako parametru linku do 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 zapoznaj się z tym zestawem krótkich linków usługi Linki dynamiczne Firebase, parametrami precyzyjnych linków i przeniesionymi wartościami precyzyjnych linków:

Krótki link Parametr precyzyjnego linku Przeniesiony precyzyjny link
yourapp.page.link/welcome https://example.com/welcome yourapp.web.app/welcome
yourapp.page.link/c7sn https://example.com/main/?p=23&t=1 yourapp.web.app/main/?p=23&t=1
yourapp.page.link/social https://example.com/friendinvite/?add=1 yourapp.web.app/friendinvite/?add=1

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

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. Dodanie 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 MainActivity:

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

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 aplikacji w Android Studio lub użyć tego polecenia w przypadku skonfigurowanego adresu URL linku aplikacji, aby sprawdzić, czy prawidłowo uruchamia on pasującą aktywność:

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 do aplikacji wszędzie tam, gdzie jest 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 ułatwić sobie śledzenie, które z nich istnieją, możesz wyeksportować metadane istniejących Linków dynamicznych Firebase. Zapoznaj się z przewodnikiem po eksportowaniu metadanych linków dynamicznych.

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

Procedura 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

W tym kroku odtworzysz linki do konkretnych miejsc w aplikacji z Linków dynamicznych Firebase za pomocą zwykłych adresów URL linków do konkretnych miejsc w aplikacji, które pasują do nowej domeny utworzonej na potrzeby linków uniwersalnych.

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

Przykład linku dynamicznego
Nazwa linku Witamy w Example.com
Precyzyjny link https://example.web.app/welcome
Aplikacja na Androida com.example.android
Aplikacja Apple com.example.ios
Długi link dynamiczny 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 tym przypadku wyodrębnisz parametr precyzyjnego linku, czyli https://example.web.app/welcome, i użyjesz go jako parametru linku uniwersalnego 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 zapoznaj się z tym zestawem krótkich linków usługi Linki dynamiczne Firebase, parametrami precyzyjnych linków i przeniesionymi wartościami precyzyjnych linków:

Krótki link Parametr precyzyjnego linku Przeniesiony precyzyjny link
yourapp.page.link/welcome https://example.com/welcome yourapp.web.app/welcome
yourapp.page.link/c7sn https://example.com/main/?p=23&t=1 yourapp.web.app/main/?p=23&t=1
yourapp.page.link/social https://example.com/friendinvite/?add=1 yourapp.web.app/friendinvite/?add=1

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

Po wybraniu domeny, schematu precyzyjnych linków 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 dotyczącą konfigurowania 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. Otrzymywanie 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ć 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 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 obecny.

Teraz wywołamy tę samą metodę showReceivedUrl z klasy SceneDelegate, ponieważ jeśli aplikacja jest już otwarta, 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)
}

Utworzone właśnie linki uniwersalne możesz przetestować, uruchamiając aplikację na fizycznym urządzeniu 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 Twojej 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.

Ostatnim krokiem migracji będzie zastąpienie opublikowanych lub udostępnionych linków dynamicznych Firebase linkami uniwersalnymi wszędzie tam, gdzie jest 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 publikujesz 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.