Von dynamischen Links zu App-Links und universellen Links migrieren

In dieser Migrationsanleitung liegt der Schwerpunkt auf der Verwendung von App-Links und Universal-Links. Optional können Sie Firebase Hosting zum Hosten der Verknüpfungsdateien der App-Website 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 in Bezug auf Klickereignisse für dynamische Links bereitstellen
Möglichkeit zum Erstellen von Kurzlink-URLs bereitstellen

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

Über den Deeplink für App-Links bzw. universelle Links erhalten Nutzer Folgendes:

  • Ein Deeplink, auf den Nutzer klicken können, um Ihre App zu öffnen, wenn sie bereits installiert ist
  • Eine Fortsetzung der User Journey, die Nutzer beim Öffnen zu einem bestimmten Bereich Ihrer App führt

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

In Firebase Dynamic Links werden App-Links (unter Android) und universelle Links (unter iOS) in einer zugrunde liegenden Implementierung verwendet, um Deeplinks zur Verfügung zu stellen, nachdem Ihre App bereits installiert wurde.

In diesem Leitfaden wird beschrieben, wie Sie mit Firebase Hosting eigene App-Links und universelle Links erstellen, um diesen Teil der von Firebase Dynamic Links bereitgestellten Funktionen zu ersetzen, während Sie Ihre Firebase Dynamic Links zur neuen Migrationslösung für App Links / universelle 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, die in Ihren dynamischen Links enthalten sind
  • 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. Einbindung von App-Links / universellen Links testen

  6. Ersetzen Sie Ihre veröffentlichten oder freigegebenen Firebase Dynamic Links durch App-Links und universelle 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 an Ihre Nutzer weitergeben.

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 Anwendungs-ID, die in der Datei build.gradle der App deklariert wurde
    • 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 Fehlerbehebungszwecken zu generieren. Sie finden die Datei unter /Users/<username>/.android/debug.keystore für Mac und Linux bzw. unter C:\Users\<username>\.android\debug.keystore für Windows.

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

    Weitere Informationen zum Ausführen dieses Schritts finden Sie in diesem Abschnitt der Dokumentation zu App-Links.

    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 obigen 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
ihreapp.seite.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. Intent-Filter für diese Aktivitäten in der Datei AndroidManifest.xml hinzufügen
  3. Deeplink im Anwendungscode Ihrer Aktivitäten erhalten

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 „wxample.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>

Im letzten Schritt der Migration ersetzen Sie Ihre veröffentlichten oder freigegebenen Firebase-Dynamic-Links nach Möglichkeit durch App-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. 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 dynamischen 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 voll qualifizierte 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. Prüfen Sie die AASA-Datei. Rufen Sie dazu https://your-project-domain.web.app/.well-known/app-app-site-association auf

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
ihreapp.seite.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 ausgewählt, ein Deeplink-Schema ausgewählt und Ihre Firebase Dynamic Links zu universellen Links migriert haben, müssen Sie Ihre iOS-App und Ihren Anwendungscode so aktualisieren, dass sie die neuen Deeplinks erhalten.

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 erhalten

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. Tab „Signing &Capabilities“ (Signatur und Funktionen) in Ihren Projekteinstellungen aufrufen
  4. Gehen 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 aus der SceneDelegate-Klasse auf. Wenn die Anwendung bereits geöffnet ist, als der Nutzer auf den universellen Link geklickt hat, wird der Callback für den universellen Link in SceneDelegate aufgerufen.

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

Sie können die soeben erstellten universellen Links testen, indem Sie Ihre App entweder auf einem physischen Gerät oder 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.

Unterstützung von Smart App-Bannern

Wir empfehlen dringend, Smart App-Banner zu verwenden, um Ihren Nutzern eine ähnliche Erfahrung wie Firebase Dynamic 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 vorhandene Firebase Dynamic Links verfolgen können, die migriert werden sollen, veröffentlichen wir einen Leitfaden 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.