Von dynamischen Links zu App-Links und universellen Links migrieren

In diesem Migrationsleitfaden liegt der Schwerpunkt auf der Verwendung von App-Links und universellen Links. Optional können Sie Firebase Hosting zum Hosten Ihrer App-Website-Verknüpfungsdateien verwenden.

Durch diese Migration werden die folgenden Firebase Dynamic Links-Funktionen ersetzt:

Funktion Firebase Dynamic Links App-Links / Universelle Links
Nutzer mit nur einem Linkklick zum richtigen Store für ihr Gerät weiterleiten
Nutzer nach dem Herunterladen und Installieren Ihrer App mit einem verzögerten Deeplink weiterleiten
Nutzern mit Deeplinks in Ihrer App (sofern bereits installiert) eine kontextbezogene Nutzung ermöglichen
Analysedaten zu Klickereignissen für dynamische Links bereitstellen
Möglichkeit zum Erstellen von Kurz-URLs

Wenn Sie für Ihre Migration weitere Firebase Dynamic Link-Funktionen benötigen, die in diesem Leitfaden nicht unterstützt werden, finden Sie in den häufig gestellten Fragen zur Einstellung von Dynamic Links weitere Migrationsszenarien.

Angenommen, Sie haben einen Firebase Dynamic Link, der so aussieht:

Beispiel für einen dynamischen Link
Linkname Willkommen bei beispiel.de
Deeplink https://example.web.app/welcome
Android-App com.example.android
Apple-App com.example.ios
Langer dynamischer Link https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Kurzer dynamischer Link https://example.page.link/m9Mm

In diesem Migrationsleitfaden erfahren Sie, wie Sie Firebase Dynamic Links so ersetzen:

https://example.page.link/m9Mm

Mit App-Link-/Universal-Link-Deeplinks, die so aussehen:

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

Der Deeplink des App-Links bzw. des universellen Links bietet Ihren Nutzern Folgendes:

  • Ein Deeplink, auf den Nutzer klicken können, um Ihre App zu öffnen, falls sie bereits installiert ist
  • Eine Fortsetzung der User Journey, die Nutzer zu einem bestimmten Teil Ihrer App weiterleitet, wenn sie geöffnet wird

Der Deeplink von App-Links / universellen Links bietet Ihren Nutzern jedoch nicht die folgenden Funktionen, die zuvor mit Firebase Dynamic Links möglich waren:

  • Nutzer zum richtigen Store für ihr Gerät weiterleiten, um Ihre App herunterzuladen und zu installieren
  • Die User Journey nach dem Herunterladen, Installieren und erstmaligen Öffnen der App fortsetzen

Beachten Sie die Unterschiede im Verhalten und in der Funktionalität dieser App-Links / universellen Links im Vergleich zu Firebase Dynamic Links, die in der Tabelle oben aufgeführt sind.

Hinweis

Firebase Dynamic Links nutzt App-Links (unter Android) und universelle Links (unter iOS) in der zugrunde liegenden Implementierung, um Deeplink-Funktionen bereitzustellen, nachdem Ihre App bereits installiert wurde.

In diesem Leitfaden erfahren Sie, wie Sie mit Firebase Hosting eigene App-Links und Universal-Links erstellen, um diesen Teil der von Firebase Dynamic Links bereitgestellten Funktionen zu ersetzen. Außerdem erfahren Sie, wie Sie Ihre Firebase Dynamic Links zur neuen Migrationslösung für App-Links / Universal-Links migrieren.

Für die Migration benötigen Sie die folgenden Informationen:

  • Die Firebase Dynamic Links, die Sie migrieren möchten
  • Die Deeplink-URL-Parameter in Ihren dynamischen Links
  • Die Domain, mit der Sie Ihre vorherige Firebase Dynamic Links-Domain ersetzen möchten (falls zutreffend)

Im Leitfaden zum Exportieren von Metadaten für dynamische Links erfahren Sie, wie Sie Ihre vorhandenen Linkmetadaten exportieren und die oben aufgeführten Informationen abrufen.

Migrationsschritte – Übersicht

  1. Stellen Sie eine neue Domain bereit (falls Sie noch keine haben, die Sie verwenden möchten), um Ihre App-Link-/Universal-Link-Konfigurationsdateien mit Firebase Hosting zu hosten.

  2. Erstellen und hosten Sie Ihre App-Link-/Universal-Link-Konfigurationsdateien auf Ihrer Hostingdomain.

  3. Erstellen Sie neue App-Links / Universal-Links, die dem Deeplink-Schema entsprechen, das in Ihren Firebase Dynamic Links verwendet wird.

  4. Aktualisieren Sie Ihre Android-/iOS-Apps und den Anwendungscode, damit Deeplinks empfangen werden können.

  5. Integrationen von App-Links / Universal-Links testen

  6. Ersetzen Sie Ihre veröffentlichten oder freigegebenen Firebase Dynamic Links durch App-Links und Universal-Links.

Der erste Schritt ist sowohl für die Migration von App-Links als auch für die Migration von Universal-Links identisch. Der Rest hängt von der Plattform ab. Rufen Sie daher den Abschnitt des Leitfadens auf, der der Plattform entspricht, die Sie zuerst migrieren möchten.

Domain auswählen

Wählen Sie zuerst eine Domain aus, die Sie für Ihre App-Links/Universal-Links verwenden möchten. Diese Domain wird für die neuen Links verwendet, die Sie für Ihre Nutzer freigeben.

Wenn Sie Firebase Hosting verwenden, werden Projektsubdomains im Format your-project-domain.web.app oder your-project-domain.firebaseapp.com automatisch und kostenlos bereitgestellt. Optional können Sie auch eine benutzerdefinierte Domain mit oder ohne Firebase Hosting verwenden, um Ihre App-Link-/Universal-Link-Konfigurationsdateien zu hosten.

Firebase Hosting einrichten

Als Nächstes müssen Sie Ihre Firebase Hosting-Instanz einrichten und konfigurieren.

Wenn Sie die Einrichtung Ihrer Firebase Hosting-Instanz abgeschlossen haben, haben Sie eine Domain wie your-project-domain.web.app oder eine benutzerdefinierte Domain.

Wenn Sie App-Links verwenden möchten, müssen Sie eine Konfigurationsdatei hosten, mit der eine sichere Verknüpfung zwischen der in Ihren Links verwendeten Domain und Ihrer App hergestellt werden kann. Bei App-Links ist dies die Datei assetlinks.json.

Schritte zum Erstellen und Hosten der Datei „assetlinks.json“

In der Datei assetlinks.json können wir eine Liste der autorisierten Apps angeben, die den Inhalt der Webdomain verarbeiten können, die wir für unsere App-Links verwenden. Die Datei „assetlinks.json“ selbst muss im Stammverzeichnis der Webdomain unter dem Pfad /.well-known gehostet werden.

Führen Sie die folgenden Schritte aus, um diese Konfiguration abzuschließen:

  1. Erstellen Sie den Ordner .well-known im öffentlichen Ordner im Stammverzeichnis von Firebase Hosting.

  2. Erstellen Sie im Ordner .well-known eine Datei mit dem Namen assetlinks.json.

  3. Kopieren Sie den folgenden Inhalt in die Datei „assetlinks.json“. Beachten Sie dabei die Bedeutung der einzelnen Felder unten:

    [{
      "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: Der Name der Anwendung, die Sie bereitstellen möchten.
    • package_name: bezieht sich auf die applicationId, die in der build.gradle-Datei der App deklariert ist
    • sha256_cert_fingerprints: Der SHA256-Fingerabdruck der Keystore-Datei, die Sie zum Signieren der Anwendung verwenden.

    Sie können die von Android Studio verwendete Datei „debug.keystore“ verwenden, um einen sha256_cert_fingerprints-Eintrag zu generieren. Unter Mac und Linux befindet sie sich unter /Users/<username>/.android/debug.keystore, unter Windows unter C:\Users\<username>\.android\debug.keystore.

    Aus diesem Schlüsselspeicher können Sie den SHA256-Wert mit dem Keytool abrufen.

    Eine ausführliche Anleitung zu diesem Schritt finden Sie in diesem Abschnitt der App Links-Dokumentation.

    Alternativ können Sie auch den App Links Assistant in Android Studio verwenden, um den Inhalt der Datei „assetlinks.json“ zu generieren und Ihre Anwendung für die Verarbeitung von App-Links zu konfigurieren.

  4. Aktualisieren Sie die Datei „firebase.json“, um die Datei für das Hosting zu indexieren.

    "headers": [
      {
        "source": "/.well-known/assetlinks.json",
        "headers": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ]
      }
    ]
    
  5. Nachdem wir die assetlinks.json-Datei erstellt haben, führen wir firebase deploy aus, um die Änderungen zu hosten.

    Die Firebase CLI muss installiert sein, damit Sie den oben genannten Bereitstellungsbefehl ausführen können.

    firebase deploy --only hosting
    
  6. Prüfen Sie die assetlinks.json-Datei unter https://your-project-domain.web.app/.well-known/assetlinks.json.

In diesem Schritt erstellen Sie die Deeplinks aus Ihren Firebase Dynamic Links mithilfe regulärer Deeplink-URLs, die mit der neuen Domain übereinstimmen, die Sie für Ihre App-Links erstellt haben.

Angenommen, Sie haben den folgenden Firebase Dynamic Link:

Beispiel für einen dynamischen Link
Linkname Willkommen bei beispiel.de
Deeplink https://example.web.app/welcome
Android-App com.example.android
Apple-App com.example.ios
Langer dynamischer Link https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Kurzer dynamischer Link https://example.page.link/m9Mm

In diesem Fall würden Sie den Deeplink-Parameter extrahieren, also https://beispiel.web.app/welcome, und diesen dann als App-Link-Parameter für Ihre App verwenden.

Wiederholen Sie diesen Vorgang für jeden Firebase-dynamischen Link, den Sie zu App-Links / universellen Links migrieren möchten, und replizieren Sie das verwendete Deeplink-Schema.

Sehen Sie sich beispielsweise die folgenden Firebase Dynamic Links-Kurzlinks, Deeplink-Parameter und migrierten Deeplink-Werte an:

Kurzlink Deeplink-Parameter Migrierter Deeplink
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

Als Nächstes müssen Sie alle Instanzen von Firebase Dynamic Links, die veröffentlicht oder freigegeben wurden, durch die neuen migrierten Deeplinks ersetzen, damit Nutzer auf diese App-Links statt auf die vorherigen Firebase Dynamic Links klicken.

Nachdem Sie eine Domain und ein Deeplink-Schema ausgewählt und Ihre Firebase Dynamic Links zu App-Links migriert haben, müssen Sie Ihre Android-App und den Anwendungscode aktualisieren, damit die neuen Deeplinks empfangen werden.

Wir empfehlen, die vollständige App-Links-Dokumentation oder alternativ den Android Studio-Leitfaden zur Konfiguration Ihrer App für die Verarbeitung von Deeplinks zu lesen. Die wichtigsten Schritte sind jedoch:

  1. Festlegen, für welche Aktivitäten die jeweiligen Deeplinks verwendet werden sollen
  2. Fügen Sie in der Datei „AndroidManifest.xml“ einen Intent-Filter für diese Aktivitäten hinzu.
  3. Deeplink im Anwendungscode Ihrer Aktivitäten empfangen

Angenommen, Sie möchten einige Ihrer Deeplinks über Ihre MainActivity verarbeiten. Dazu müssen Sie der MainActivity in der Datei „AndroidManifest.xml“ den folgenden Intent-Filter hinzufügen:

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

In diesem Schritt geben Sie an, dass die MainActivity das Ziel für die Verarbeitung von Deeplinks aus der Domain „beispiel.web.app“ ist, einschließlich des Pfadpräfixes „/welcome“. Sie müssen auch das Attribut „android:autoVerify="true"“ angeben, damit Sie Ihre App als Standard-Handler für diesen Linktyp festlegen können.

Fügen Sie abschließend den Code in Ihrer MainActivity hinzu, um die Deeplink-Daten abzurufen und die Deeplink-Funktion in Ihrer App zu optimieren. Diese Logik ähnelt der Logik, die Sie möglicherweise bereits in Ihre App codiert haben, als Sie Firebase Dynamic Links eingebunden haben.

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

Sie können die gerade erstellten App-Links testen, indem Sie Ihre App entweder auf einem physischen Gerät oder im Android-Emulator ausführen.

Sie müssen einen anklickbaren Link mit der für Ihre App-Links konfigurierten Domain erstellen und dann auf diesen Link klicken, um sicherzustellen, dass er in Ihrer App geöffnet wird und Sie zur gewünschten Aktivität weiterleitet.

Alternativ können Sie die App-Links-Integration auch mit dem App Links Assistant in Android Studio testen oder den folgenden Befehl für eine von Ihnen konfigurierte App-Link-URL verwenden, um sicherzustellen, dass die entsprechende Aktivität richtig gestartet wird:

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

Der letzte Schritt bei der Migration besteht darin, Ihre veröffentlichten oder freigegebenen Firebase-Dynamic-Links nach Möglichkeit durch App-Links zu ersetzen und diese in Zukunft weiter zu verwenden.

Wie Sie diesen Schritt ausführen, hängt davon ab, wo und wie Sie Ihre Firebase Dynamic Links veröffentlicht haben. Sie können Ihre vorhandenen Firebase Dynamic Link-Metadaten exportieren, um zu sehen, welche vorhanden sind. Weitere Informationen finden Sie im Leitfaden zum Exportieren von Dynamic Links-Metadaten.

Wenn Sie universelle Links verwenden möchten, müssen Sie eine Konfigurationsdatei hosten, mit der eine sichere Verknüpfung zwischen der in Ihren Links verwendeten Domain und Ihrer App hergestellt werden kann. Bei universellen Links ist dies die Datei apple-app-site-association (auch als AASA-Datei bezeichnet).

Schritte zum Erstellen und Hosten der Datei „apple-app-site-association“

Mit der AASA-Datei können wir eine Liste der autorisierten Apps angeben, die den Inhalt der Webdomain verarbeiten können, die wir für unsere universellen Links verwenden. Die AASA-Datei selbst muss im Stammverzeichnis der Webdomain unter dem Pfad /.well-known gehostet werden.

Führen Sie die folgenden Schritte aus, um diese Konfiguration abzuschließen:

  1. Erstellen Sie im Stammverzeichnis von Firebase Hosting im Ordner „public“ den Ordner .well-known.

  2. Erstellen Sie im Ordner „.well-known“ eine Datei mit dem Namen apple-app-site-association.

  3. Kopieren Sie den folgenden Inhalt in die Datei „apple-app-site-association“. Beachten Sie dabei die Bedeutung der einzelnen Felder unten:

    {
      "applinks": {
        "apps": [],
        "details": [
          {
            "appId": "$TEAM_ID.com.firebase.UniversalLinks",
            "paths": [
              "NOT /_/*",
              "/*"
            ]
          }
        ]
      }
    }
    
    • $TEAM_ID.BundleId: der vollqualifizierte Name der Anwendung, die zum Verwalten der Links berechtigt ist
  4. Aktualisieren Sie die Datei „firebase.json“, um die Datei für das Hosting zu indexieren.

    "headers": [
      {
        "source": "/.well-known/apple-app-site-association",
        "headers": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ]
      }
    ]
    
  5. Jetzt, da wir die AASA-Datei haben, führen Sie ein Firebase-Bereitstellen aus, um die Änderungen zu hosten.

  6. Verifiziere die AASA-Datei unter https://your-project-domain.web.app/.well-known/apple-app-site-association.

In diesem Schritt erstellen Sie die Deeplinks aus Ihren Firebase Dynamic Links mithilfe regulärer Deeplink-URLs, die mit der neuen Domain übereinstimmen, die Sie für Ihre Universal Links erstellt haben.

Angenommen, Sie haben den folgenden Firebase Dynamic Link:

Beispiel für einen dynamischen Link
Linkname Willkommen bei beispiel.de
Deeplink https://example.web.app/welcome
Android-App com.example.android
Apple-App com.example.ios
Langer dynamischer Link https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Kurzer dynamischer Link https://example.page.link/m9Mm

In diesem Fall würden Sie den Deeplink-Parameter extrahieren, z.B.https://beispiel.web.app/welcome, und diesen dann als Universal Link-Parameter für Ihre App verwenden.

Wiederholen Sie diesen Vorgang für jeden Firebase-dynamischen Link, den Sie zu App-Links / universellen Links migrieren möchten, und replizieren Sie das verwendete Deeplink-Schema.

Sehen Sie sich beispielsweise die folgenden Firebase Dynamic Links-Kurzlinks, Deeplink-Parameter und migrierten Deeplink-Werte an:

Kurzlink Deeplink-Parameter Migrierter Deeplink
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

Als Nächstes müssen Sie alle Instanzen von Firebase Dynamic Links, die veröffentlicht oder freigegeben wurden, durch die neuen migrierten Deeplinks ersetzen, damit Nutzer auf diese universellen Links statt auf die vorherigen Firebase Dynamic Links klicken.

Nachdem Sie eine Domain und ein Deeplink-Schema ausgewählt und Ihre Firebase Dynamic Links zu Universal Links migriert haben, müssen Sie Ihre iOS-App und den Anwendungscode aktualisieren, damit die neuen Deeplinks empfangen werden.

Wir empfehlen Ihnen, die vollständige Dokumentation zu universellen Links zu lesen, um Ihre App für die Verarbeitung von Deeplinks zu konfigurieren. Die wichtigsten Schritte sind:

  1. Aktualisieren Sie die Projektkonfiguration, damit Ihre App Deeplinks von Ihrer neu erstellten Domain verarbeiten kann.

  2. Deeplink im Anwendungscode empfangen

Um Ihre Projektkonfiguration so zu aktualisieren, dass Ihre App Deeplinks verarbeiten kann, müssen Sie Ihrem Projekt in Xcode eine zusätzliche verknüpfte Domain für die Domain hinzufügen, die Sie jetzt zum Hosten Ihrer apple-app-site-associate-Datei verwenden möchten.

Dazu haben Sie folgende Möglichkeiten:

  1. Xcode öffnen
  2. Projekt im Datei-Navigator auswählen
  3. Rufen Sie in den Projekteinstellungen den Tab „Signatur und Funktionen“ auf.
  4. Scrollen Sie nach unten zum Abschnitt „Verknüpfte Domains“.
  5. Klicken Sie auf die Schaltfläche „+“, um dem Projekt die zusätzliche Domain im Format „applinks:“ hinzuzufügen.

Abschließend müssen Sie Ihren Anwendungscode aktualisieren, damit eingehende Deeplinks empfangen werden können.

Aktualisieren Sie dazu zuerst die Datei „AppDelegate.swift“, damit auf einen Universallink geantwortet wird. Fügen Sie dazu den folgenden Code hinzu:

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

Im obigen Code wird die Callback-Methode für Universal Links überschrieben und die Deeplink-URL wird protokolliert, sofern vorhanden.

Jetzt rufen wir dieselbe showReceivedUrl-Methode auch aus der Klasse „SceneDelegate“ auf. Wenn die App bereits geöffnet ist, wenn der Nutzer auf den universellen Link klickt, wird der universelle Link-Callback in SceneDelegate aufgerufen.

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

Sie können die gerade erstellten Universal Links testen, indem Sie Ihre App entweder auf einem physischen Gerät oder einem Simulator ausführen.

Sie müssen einen anklickbaren Link mit der für Ihre Universal-Links konfigurierten Domain erstellen und dann auf diesen Link klicken, um sicherzustellen, dass er in Ihrer App geöffnet wird und Sie zum gewünschten Bildschirm in Ihrer App weitergeleitet werden.

Smart App-Banner unterstützen

Wir empfehlen Ihnen dringend, Smart App-Banner zu verwenden, um Ihren Nutzern eine ähnliche Funktion wie mit Firebase-dynamischen Links zu bieten.

Wenn Sie Smart App-Banner verwenden, werden Nutzer zum App Store-Eintrag Ihrer App weitergeleitet, wenn Ihre App noch nicht auf ihrem Gerät installiert ist. Optional können Sie einen Parameter konfigurieren, der an Ihre App übergeben wird, nachdem sie heruntergeladen und installiert wurde, um Ihren Nutzern eine Weiterleitung zu ermöglichen. Wenn Ihre App bereits installiert ist, wird sie geöffnet und der Parameter wird an Ihre App übergeben, damit Nutzer anhand des Smart App-Banners, auf das sie geklickt haben, zu den entsprechenden Inhalten weitergeleitet werden.

Im letzten Schritt der Migration ersetzen Sie Ihre veröffentlichten oder freigegebenen Firebase Dynamic Links nach Möglichkeit durch universelle Links und verwenden diese in Zukunft weiter.

Wie Sie diesen Schritt ausführen, hängt davon ab, wo und wie Sie Ihre Firebase-Dynamic Links veröffentlicht haben.

Damit Sie bestehende Firebase Dynamic Links, die migriert werden müssen, im Blick behalten können, veröffentlichen wir eine Anleitung zum Exportieren Ihrer Kurzlink-Metadaten aus Firebase Dynamic Links. Weitere Informationen finden Sie in unserem Dokument häufig gestellte Fragen zur Einstellung von dynamischen Links.