Passer des liens dynamiques aux liens vers une application Liens universels

Ce guide de migration se concentre sur l'utilisation des liens vers une application et des liens universels, en utilisant éventuellement Firebase Hosting pour héberger vos fichiers d'association application-site.

Cette migration remplace les fonctionnalités Firebase Dynamic Links suivantes :

Fonctionnalité Firebase Dynamic Links Liens vers une application/Liens universels
Redirigez les utilisateurs vers la plate-forme de téléchargement d'applications adaptée à leur appareil en un seul clic. ★
Proposez aux utilisateurs de poursuivre leur parcours après avoir téléchargé et installé votre application à l'aide d'un lien profond différé. ★
Offrez aux utilisateurs une expérience contextuelle en utilisant des liens profonds vers du contenu dans votre application (si elle est déjà installée).
Fournir des données analytiques liées aux événements de clic sur les liens dynamiques
Permettre de créer des URL courtes

Si vous avez toujours besoin d'autres fonctionnalités Firebase Dynamic Links pour votre migration qui ne sont pas prises en charge dans ce guide, consultez les autres scénarios de migration dans la documentation Questions fréquentes sur l'abandon de Dynamic Links.

Supposons que vous disposiez d'un lien dynamique Firebase qui ressemble à ceci :

Exemple de lien dynamique
Nom du lien Bienvenue sur Example.com
Lien profond https://example.web.app/welcome
Application Android com.example.android
Application Apple com.example.ios
Lien dynamique long https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Lien dynamique court https://example.page.link/m9Mm

L'objectif de ce guide de migration est de remplacer les liens dynamiques Firebase comme celui-ci :

https://example.page.link/m9Mm

Avec des liens profonds App Link/Universal Link qui ressemblent à ceci :

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

Notez que le lien profond vers une application ou le lien universel fournira les éléments suivants à vos utilisateurs :

  • Un lien profond sur lequel ils peuvent cliquer pour ouvrir votre application si elle est déjà installée
  • Une continuation de leur parcours utilisateur, qui les redirige vers une partie spécifique de votre application lorsqu'elle est ouverte

Toutefois, le lien profond App Link/Universal Link n'offrira pas les comportements suivants à vos utilisateurs (ce que Firebase Dynamic Links faisait auparavant) :

  • Rediriger les utilisateurs vers le magasin d'applications adapté à leur appareil pour qu'ils puissent télécharger et installer votre application
  • en leur permettant de poursuivre leur parcours utilisateur après avoir téléchargé, installé et ouvert l'application pour la première fois.

Notez les différences de comportement et de fonctionnalité de ces liens vers une application/liens universels par rapport aux Firebase Dynamic Links, indiquées dans le tableau ci-dessus.

Avant de commencer

Firebase Dynamic Links utilise des liens d'application (sur Android) et des liens universels (sur iOS) dans sa propre implémentation sous-jacente afin de fournir une fonctionnalité de liens profonds une fois votre application installée.

Ce guide explique comment créer vos propres liens d'application et liens universels à l'aide de Firebase Hosting pour remplacer cette partie des fonctionnalités fournies par Firebase Dynamic Links tout en migrant vos liens Firebase Dynamic Links vers la nouvelle solution de migration des liens d'application/liens universels.

Vous aurez besoin des informations suivantes pour effectuer la migration :

  • Les liens dynamiques Firebase que vous souhaitez migrer
  • Paramètres d'URL de lien profond inclus dans vos liens dynamiques
  • Le domaine que vous prévoyez d'utiliser pour remplacer votre ancien domaine Firebase Dynamic Links (le cas échéant)

Vous pouvez utiliser le guide Exporter les métadonnées des liens dynamiques pour exporter les métadonnées de vos liens existants et obtenir les informations listées ci-dessus.

Présentation des étapes de migration

  1. Provisionnez un nouveau domaine (si vous n'en avez pas déjà un que vous souhaitez utiliser) pour héberger vos fichiers de configuration App Link/Universal Link à l'aide de Firebase Hosting.

  2. Créez et hébergez vos fichiers de configuration App Link/Universal Link sur votre domaine d'hébergement.

  3. Créez des liens d'application/liens universels correspondant au schéma de lien profond utilisé dans vos Firebase Dynamic Links.

  4. Mettez à jour vos applications Android/iOS et le code de l'application pour recevoir des liens profonds.

  5. Tester vos intégrations App Links/Universal Links

  6. Remplacez vos liens Firebase Dynamic Links publiés ou partagés par des liens d'application et des liens universels.

La première étape est commune aux flux de migration vers les liens d'application et les liens universels. Le reste varie en fonction de la plate-forme. Accédez donc à la section du guide ci-dessous en fonction de la plate-forme vers laquelle vous souhaitez migrer en premier.

Choisir un domaine

La première étape consiste à choisir un domaine que vous souhaitez utiliser pour vos liens d'application/liens universels. Il s'agit du domaine qui sera utilisé pour les nouveaux liens que vous partagerez avec vos utilisateurs.

Si vous utilisez Firebase Hosting, les sous-domaines de projet au format your-project-domain.web.app ou your-project-domain.firebaseapp.com sont automatiquement provisionnés sans frais. Vous pouvez éventuellement utiliser un domaine personnalisé avec ou sans Firebase Hosting pour héberger également vos fichiers de configuration App Link/Universal Link.

Configurer Firebase Hosting

Vous devez ensuite configurer votre instance Firebase Hosting.

Une fois que vous aurez terminé de configurer votre instance Firebase Hosting, vous disposerez d'un domaine semblable à your-project-domain.web.app ou d'un domaine personnalisé si vous préférez.

Pour utiliser les liens d'application, vous devez héberger un fichier de configuration qui permet d'établir une association sécurisée entre le domaine utilisé dans vos liens et votre application. Pour les liens d'application, il s'agit du fichier assetlinks.json.

Procédure de création et d'hébergement du fichier assetlinks.json

Le fichier assetlinks.json nous permet de fournir une liste d'applications autorisées pouvant gérer le contenu du domaine Web que nous utiliserons pour nos liens d'application. Le fichier assetlinks.json lui-même doit être hébergé à la racine du domaine Web, sous le chemin d'accès /.well-known.

Suivez les étapes ci-dessous pour effectuer cette configuration :

  1. Créez le dossier .well-known sous le dossier public dans le répertoire racine de Firebase Hosting.

  2. Créez un fichier nommé assetlinks.json dans le dossier .well-known.

  3. Copiez le contenu suivant dans votre fichier assetlinks.json, en tenant compte de la signification de chaque champ ci-dessous :

    [{
      "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 : nom de l'application que vous souhaitez fournir.
    • package_name : fait référence à l'applicationId déclaré dans le fichier build.gradle de l'application.
    • sha256_cert_fingerprints : fait référence à l'empreinte SHA256 du fichier keystore que vous utilisez pour signer l'application.

    Vous pouvez utiliser le fichier debug.keystore utilisé par Android Studio pour générer un enregistrement sha256_cert_fingerprints à des fins de débogage. Vous trouverez le fichier à l'emplacement /Users/<username>/.android/debug.keystore sur Mac et Linux, et à l'emplacement C:\Users\<username>\.android\debug.keystore sur Windows.

    À partir de ce keystore, vous pouvez récupérer la valeur SHA256 à l'aide de l'outil keytool.

    Pour en savoir plus sur cette étape, consultez cette section de la documentation sur les liens d'application.

    Vous pouvez également utiliser l'assistant pour les liens vers des applications dans Android Studio pour générer le contenu du fichier assetlinks.json et configurer votre application pour qu'elle gère les liens vers des applications.

  4. Mettez à jour votre fichier firebase.json pour indexer le fichier pour l'hébergement.

    "headers": [
      {
        "source": "/.well-known/assetlinks.json",
        "headers": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ]
      }
    ]
    
  5. Maintenant que le fichier assetlinks.json est en place, exécutez firebase deploy pour héberger les modifications.

    Notez que vous devez avoir installé la CLI Firebase pour exécuter la commande de déploiement ci-dessus.

    firebase deploy --only hosting
    
  6. Vérifiez le fichier assetlinks.json en accédant à https://your-project-domain.web.app/.well-known/assetlinks.json.

Au cours de cette étape, vous allez recréer les liens profonds à partir de vos liens dynamiques Firebase à l'aide d'URL de liens profonds standards correspondant au nouveau domaine que vous avez créé pour vos liens d'application.

Par exemple, supposons que vous disposiez du lien dynamique Firebase suivant :

Exemple de lien dynamique
Nom du lien Bienvenue sur Example.com
Lien profond https://example.web.app/welcome
Application Android com.example.android
Application Apple com.example.ios
Lien dynamique long https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Lien dynamique court https://example.page.link/m9Mm

Dans ce cas, vous devez extraire le paramètre de lien profond (par exemple, https://example.web.app/welcome) et l'utiliser comme paramètre de lien vers l'application.

Vous devrez répéter ce processus pour chaque lien dynamique Firebase que vous souhaitez migrer vers des liens d'application/liens universels, et répliquer le schéma de liens profonds que vous avez utilisé.

Par exemple, consultez l'ensemble suivant de liens courts Firebase Dynamic Links, de paramètres de liens profonds et de valeurs de liens profonds migrées :

Lien court Paramètre de lien profond Lien profond migré
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

Ensuite, vous devrez remplacer toutes les instances de Firebase Dynamic Links qui ont été publiées ou partagées par les nouveaux liens profonds migrés, afin que les utilisateurs cliquent sur ces liens d'application au lieu des liens Firebase Dynamic Links précédents.

Après avoir sélectionné un domaine, choisi un schéma de liens profonds et migré vos Firebase Dynamic Links vers des App Links, vous devez mettre à jour votre application Android et son code pour recevoir les nouveaux liens profonds.

Nous vous recommandons de suivre l'intégralité de la documentation sur les liens vers une application ou le guide Android Studio pour configurer votre application afin qu'elle gère les liens profonds. Voici les principales étapes à suivre :

  1. Identifier les activités qui doivent gérer les liens profonds respectifs
  2. Ajouter un filtre d'intent pour ces activités dans votre fichier AndroidManifest.xml
  3. Recevoir le lien profond dans le code d'application de vos activités

Supposons que vous souhaitiez utiliser votre MainActivity pour gérer certains de vos liens profonds. Pour ce faire, vous devez ajouter le filtre d'intent suivant à MainActivity dans votre fichier 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>

Au cours de cette étape, vous allez spécifier que MainActivity est la destination pour gérer les liens profonds du domaine wxample.web.app, qui inclut le préfixe de chemin d'accès /welcome. Notez que vous devez également spécifier l'attribut android:autoVerify="true", qui vous permet de désigner votre application comme gestionnaire par défaut pour ce type de lien.

Enfin, vous devrez ajouter le code dans votre MainActivity pour récupérer les données de lien profond et les utiliser pour générer l'expérience de lien profond dans votre application. Cela est semblable à la logique que vous avez peut-être déjà codée dans votre application lorsque vous l'avez intégrée à 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()
}

Vous pouvez tester les liens d'application que vous venez de créer en exécutant votre application sur un appareil physique ou dans l'émulateur Android.

Vous devez créer un lien cliquable à l'aide du domaine configuré pour vos liens d'application, puis cliquer sur ce lien pour vous assurer qu'il s'ouvre dans votre application et vous redirige vers l'activité prévue.

Vous pouvez également tester l'intégration de vos liens vers l'application à l'aide de l'assistant pour les liens vers des applications dans Android Studio, ou utiliser la commande suivante pour une URL de lien vers l'application que vous avez configurée afin de vous assurer qu'elle lance correctement l'activité correspondante :

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

La dernière étape de votre migration consistera à remplacer vos Firebase Dynamic Links publiés ou partagés par des liens d'application dans la mesure du possible, et à continuer à utiliser des liens d'application à l'avenir.

La procédure à suivre pour effectuer cette étape varie en fonction de l'emplacement et de la manière dont vous avez publié vos Firebase Dynamic Links. Toutefois, pour vous aider à suivre les liens existants, vous pouvez exporter les métadonnées de lien de vos Firebase Dynamic Links existants. Consultez le guide Exporter les métadonnées des liens dynamiques.

Pour utiliser les liens universels, vous devez héberger un fichier de configuration qui permet d'établir une association sécurisée entre le domaine utilisé dans vos liens et votre application. Pour les liens universels, il s'agit du fichier apple-app-site-association (également appelé fichier AASA).

Procédure de création et d'hébergement du fichier apple-app-site-association

Le fichier AASA nous permet de fournir une liste d'applications autorisées à gérer le contenu du domaine Web que nous utiliserons pour nos liens universels. Le fichier AASA lui-même doit être hébergé à la racine du domaine Web, sous le chemin d'accès /.well-known.

Suivez les étapes ci-dessous pour effectuer cette configuration :

  1. Créez le dossier ".well-known" sous le dossier public dans le répertoire racine de Firebase Hosting.

  2. Créez un fichier nommé apple-app-site-association dans le dossier ".well-known".

  3. Copiez le contenu suivant dans votre fichier apple-app-site-association, en tenant compte de la signification de chaque champ ci-dessous :

    {
      "applinks": {
        "apps": [],
        "details": [
          {
            "appID": "$TEAM_ID.com.firebase.UniversalLinks",
            "paths": [
              "NOT /_/*",
              "/*"
            ]
          }
        ]
      }
    }
    
    • $TEAM_ID.BundleId : nom complet de l'application autorisée à gérer les liens
  4. Mettez à jour votre fichier firebase.json pour indexer le fichier pour l'hébergement.

    "headers": [
      {
        "source": "/.well-known/apple-app-site-association",
        "headers": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ]
      }
    ]
    
  5. Maintenant que le fichier AASA est en place, exécutez firebase deploy pour héberger les modifications.

  6. Validez le fichier AASA en accédant à https://your-project-domain.web.app/.well-known/app-app-site-association.

Au cours de cette étape, vous allez recréer les liens profonds à partir de vos liens dynamiques Firebase à l'aide d'URL de liens profonds standards correspondant au nouveau domaine que vous avez créé pour vos liens universels.

Par exemple, supposons que vous disposiez du lien dynamique Firebase suivant :

Exemple de lien dynamique
Nom du lien Bienvenue sur Example.com
Lien profond https://example.web.app/welcome
Application Android com.example.android
Application Apple com.example.ios
Lien dynamique long https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Lien dynamique court https://example.page.link/m9Mm

Dans ce cas, vous devez extraire le paramètre de lien profond (par exemple, https://example.web.app/welcome) et l'utiliser comme paramètre de lien universel pour votre application.

Vous devrez répéter ce processus pour chaque lien dynamique Firebase que vous souhaitez migrer vers des liens d'application/liens universels, et répliquer le schéma de liens profonds que vous avez utilisé.

Par exemple, consultez l'ensemble suivant de liens courts Firebase Dynamic Links, de paramètres de liens profonds et de valeurs de liens profonds migrées :

Lien court Paramètre de lien profond Lien profond migré
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

Ensuite, vous devrez remplacer toutes les instances de Firebase Dynamic Links qui ont été publiées ou partagées par les nouveaux liens profonds migrés, afin que les utilisateurs cliquent sur ces liens universels au lieu des liens Firebase Dynamic Links précédents.

Après avoir sélectionné un domaine, choisi un schéma de liens profonds et migré vos liens dynamiques Firebase vers des liens universels, vous devez mettre à jour votre application iOS et son code pour recevoir les nouveaux liens profonds.

Nous vous recommandons de suivre l'intégralité de la documentation sur les liens universels pour configurer votre application afin qu'elle gère les liens profonds. Les principales étapes sont les suivantes :

  1. Mettez à jour la configuration de votre projet pour permettre à votre application de gérer les liens profonds de votre nouveau domaine.

  2. Recevoir le lien profond dans le code de votre application

Pour mettre à jour la configuration de votre projet afin que votre application puisse gérer les liens profonds, vous devez ajouter un domaine associé supplémentaire à votre projet dans xCode pour le domaine que vous prévoyez d'utiliser pour héberger votre fichier apple-app-site-associate.

Pour cela, vous pouvez :

  1. Ouverture de Xcode…
  2. Sélectionner votre projet dans le navigateur de fichiers
  3. Accéder à l'onglet "Signing & Capabilities" (Signature et capacités) des paramètres de votre projet
  4. Accédez à la section "Domaines associés".
  5. Cliquez sur le bouton + pour ajouter le domaine supplémentaire à votre projet au format "applinks:".

Enfin, vous devez mettre à jour le code de votre application pour pouvoir recevoir les liens profonds entrants.

Pour ce faire, commencez par modifier le fichier AppDelegate.swift afin de répondre à un lien universel en ajoutant le code suivant :

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

Le code ci-dessus remplace la méthode de rappel du lien universel et consigne l'URL du lien profond, le cas échéant.

Nous allons maintenant appeler la même méthode showReceivedUrl à partir de la classe SceneDelegate, car si l'application est déjà ouverte lorsque l'utilisateur clique sur le lien universel, le rappel de lien universel dans SceneDelegate sera celui qui sera appelé.

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

Vous pouvez tester les liens universels que vous venez de créer en exécutant votre application sur un appareil physique ou un simulateur.

Vous devez créer un lien cliquable à l'aide du domaine configuré pour vos liens universels, puis cliquer sur ce lien pour vous assurer qu'il s'ouvre dans votre application et vous redirige vers l'écran prévu.

Compatibilité avec les bannières d'application intelligentes

Nous vous recommandons vivement d'utiliser les bannières d'application intelligentes pour offrir à vos utilisateurs une expérience similaire à celle de Firebase Dynamic Links.

Grâce aux bannières d'application intelligentes, vos utilisateurs seront redirigés vers l'App Store pour accéder à la fiche de votre application si celle-ci n'est pas déjà installée sur leur appareil. Vous pouvez également configurer un paramètre à transmettre à votre application une fois qu'elle a été téléchargée et installée, afin de permettre à vos utilisateurs de poursuivre leur parcours. Si votre application est déjà installée, elle s'ouvrira en transmettant le paramètre à votre application pour aider l'utilisateur à accéder au contenu approprié en fonction de la bannière d'application intelligente sur laquelle il a cliqué.

La dernière étape de votre migration consistera à remplacer vos liens Firebase Dynamic Links publiés ou partagés par des liens universels dans la mesure du possible, et à continuer à utiliser des liens universels à l'avenir.

La procédure à suivre pour effectuer cette étape varie en fonction de l'emplacement et de la méthode de publication de vos liens dynamiques Firebase.

Pour vous aider à suivre les liens dynamiques Firebase existants à migrer, nous publierons un guide sur l'exportation des métadonnées de vos liens courts depuis Firebase Dynamic Links. Pour en savoir plus, consultez notre document de questions fréquentes sur l'abandon des liens dynamiques.