Synthèse sur les Liens Universels iOS et le Fichier AASA

Les Liens Universels (Universal Links) sont un mécanisme fondamental d’iOS qui permet une redirection transparente et sécurisée des utilisateurs d’un lien web vers un contenu spécifique au sein d’une application mobile installée, améliorant considérablement l’expérience utilisateur et les taux de conversion. Selon une étude de Branch, les utilisateurs d’applications mobiles convertissent trois fois mieux que les utilisateurs du web mobile.

La mise en œuvre de cette fonctionnalité repose sur une relation de confiance entre un site web et une application, établie principalement via le fichier apple-app-site-association (AASA). Ce fichier JSON, hébergé sur le serveur web du domaine, doit être configuré avec une précision absolue pour fonctionner correctement. Les erreurs de configuration sont fréquentes et peuvent entraîner des parcours utilisateur fragmentés, impactant directement les stratégies d’acquisition et d’engagement.

Les défis techniques majeurs incluent l’emplacement correct du fichier AASA, la validité de sa syntaxe JSON, une configuration serveur rigoureuse (HTTPS, en-têtes HTTP application/json, absence de redirections) et la correspondance exacte de l’identifiant de l’application (App ID). Depuis iOS 14, un obstacle supplémentaire est apparu : la mise en cache agressive du fichier AASA par le CDN d’Apple, qui retarde la propagation des modifications et complique considérablement le débogage et les tests en environnement de développement. Des solutions de contournement avancées, impliquant l’utilisation de proxys pour bloquer les requêtes CDN, sont souvent nécessaires.

Ce document synthétise l’ensemble des exigences techniques, les problèmes courants et les meilleures pratiques pour la configuration des Liens Universels, en s’appuyant sur la documentation officielle d’Apple, des guides de développeurs et des retours d’expérience concrets.

1. Fondements des Liens Universels

1.1. Définition et Avantages

Les Liens Universels sont une fonctionnalité d’iOS permettant aux utilisateurs d’ouvrir un contenu directement dans une application native en cliquant sur un lien web standard (HTTP/HTTPS). Si l’application n’est pas installée, le lien s’ouvre normalement dans Safari, garantissant une expérience utilisateur sans interruption.

Selon la documentation d’Apple, les Liens Universels offrent plusieurs avantages clés par rapport aux schémas d’URL personnalisés (Deep Links traditionnels) :

• Uniques : Ils utilisent des liens HTTP/HTTPS standards liés à un domaine, ce qui empêche d’autres applications de les revendiquer.
• Sécurisés : iOS vérifie le fichier apple-app-site-association sur le serveur web pour confirmer que le site autorise l’application à gérer ses URL, établissant une association sécurisée.
• Flexibles : Ils fonctionnent même si l’application n’est pas installée, en redirigeant l’utilisateur vers le site web correspondant dans Safari.
• Simples : Une seule et même URL fonctionne à la fois pour le site web et pour l’application.
• Privés : D’autres applications peuvent interagir avec l’application cible sans avoir besoin de savoir si elle est installée.

1.2. Comparaison avec les Deep Links traditionnels

Les Liens Universels (iOS) et les App Links (Android) sont une évolution des Deep Links, comblant plusieurs de leurs lacunes.

2. Le Fichier (AASA)

Le fichier AASA est la pierre angulaire de la configuration des Liens Universels. Il s’agit d’un fichier JSON qui établit la relation de confiance entre un site web et une application.

2.1. Configuration Côté Serveur

Une configuration serveur rigoureuse est impérative pour qu’iOS puisse récupérer et valider le fichier.

• Emplacement : Le fichier doit être accessible via HTTPS, sans aucune redirection, à l’une des deux adresses suivantes :
  • https://<votre-domaine>/apple-app-site-association
  • https://<votre-domaine>/.well-known/apple-app-site-association
• Nom du Fichier : Le nom doit être exactement apple-app-site-association, sans l’extension .json.
• En-tête HTTP : Le serveur doit retourner le fichier avec l’en-tête Content-Type: application/json. Pour les anciennes versions d’iOS (8 et inférieures), le type application/pkcs7-mime était requis car le fichier devait être signé, mais cette pratique est obsolète.
• Taille du Fichier : Pour iOS 9.3.1 et les versions ultérieures, la taille décompressée du fichier ne doit pas dépasser 128 Ko.
• Signature : Pour les applications ciblant iOS 9 et plus, et si le fichier est servi via HTTPS, il n’est plus nécessaire de signer le fichier.

2.2. Structure et Contenu du Fichier AASA

Le fichier AASA est un objet JSON dont la structure a évolué pour offrir plus de flexibilité.

Structure de base :

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAM_ID.com.votre.bundleID",
        "paths": [ "/wwdc/news/", "/videos/wwdc/2015/*", "NOT /videos/wwdc/2010/*" ]
      }
    ]
  },
  "webcredentials": {
    "apps": [ "TEAM_ID.com.votre.bundleID" ]
  }
}

Clés principales :

• applinks : L’objet principal contenant la configuration des Liens Universels.
• apps : Doit être présent et défini comme un tableau vide pour la compatibilité avec iOS 12 et versions antérieures.
• details : Un tableau de dictionnaires, où chaque dictionnaire représente une application supportée par le site. L’ordre est important car le système s’arrête à la première correspondance trouvée.
• appID (ou appIDs pour plusieurs) : Une chaîne de caractères composée de l’ID d’équipe (Team ID) ou du préfixe d’App ID (pour les anciens comptes développeur) suivi d’un point, puis de l’identifiant du bundle de l’application (ex: 9JA89QQLNQ.com.apple.wwdc).
• paths : Un tableau de chaînes de caractères qui spécifient les chemins du site web à associer (ou à exclure en préfixant avec NOT ). Les wildcards * (n’importe quelle sous-chaîne) et ? (n’importe quel caractère unique) sont autorisés. La correspondance est sensible à la casse.

Syntaxe avancée avec components (iOS 13+) :

Pour une configuration plus fine, notamment pour gérer les paramètres de requête et les fragments d’URL, la clé components est utilisée. Si components et paths sont présents, paths est ignoré par les versions d’iOS compatibles.

{
  "applinks": {
    "details": [
      {
        "appIDs": [ "ABCDE12345.com.example.app" ],
        "components": [
          {
            "/": "/help/*",
            "?": { "articleNumber": "????" },
            "comment": "Correspond aux URL commençant par /help/ avec un paramètre 'articleNumber' de 4 caractères."
          },
          {
            "#": "no_universal_links",
            "exclude": true,
            "comment": "Exclut toute URL contenant ce fragment."
          }
        ]
      }
    ]
  }
}

3. Configuration Côté Application

La deuxième partie de la relation de confiance est établie dans le projet Xcode de l’application.

1. Ajouter l’Entitlement Associated Domains : Dans Xcode, sous l’onglet « Signing & Capabilities » de la cible de l’application, il faut ajouter la capacité « Associated Domains ».
2. Spécifier les Domaines : Dans la section « Associated Domains », ajoutez une entrée pour chaque domaine supporté, préfixée par applinks:. Par exemple : applinks:www.mywebsite.com.
   • Les sous-domaines peuvent être ciblés avec un wildcard : applinks:*.mywebsite.com.
3. Gérer l’URL dans l’Application : Lorsqu’un Lien Universel lance l’application, le système envoie un objet NSUserActivity avec un activityType de NSUserActivityTypeBrowsingWeb. L’URL d’origine est accessible via la propriété webpageURL de cet objet. Le développeur doit implémenter la méthode application:continueUserActivity:restorationHandler: dans son AppDelegate pour recevoir et traiter cette activité.

4. Problèmes Courants et Dépannage

La mise en place des Liens Universels est sujette à des erreurs qui peuvent être difficiles à diagnostiquer.

4.1. Erreurs de Configuration Fréquentes

• Emplacement incorrect : Le fichier AASA n’est pas à la racine ou dans le répertoire .well-known.
• Format JSON invalide : Erreurs de syntaxe, virgules en trop, guillemets incorrects. L’utilisation d’un validateur JSON est recommandée.
• App ID incorrect : L’ID d’équipe ou l’identifiant du bundle ne correspond pas à ce qui est configuré sur le portail développeur Apple.
• Configuration des paths erronée : Les chemins ne correspondent pas précisément aux URL ciblées, ou l’ordre de priorité est incorrect.
• Problèmes de serveur : Le fichier n’est pas servi en HTTPS, il y a des redirections, ou l’en-tête Content-Type est incorrect.

4.2. Le Défi du CDN d’Apple et le Mode Développeur

Depuis iOS 14, un défi majeur est apparu : Apple met en cache les fichiers AASA sur ses propres serveurs CDN pour améliorer les performances.

• Le Problème : Lors de l’installation ou de la mise à jour d’une application, iOS interroge d’abord le CDN d’Apple. Si le fichier AASA y est présent, il ne sera pas téléchargé depuis le serveur d’origine. Cela signifie que les modifications apportées au fichier AASA sur le serveur d’un développeur peuvent ne pas être prises en compte immédiatement, rendant le développement et les tests très difficiles.
• La Solution Théorique : ?mode=developer : Pour contourner ce cache pendant le développement, Apple a introduit un paramètre de requête à ajouter au domaine dans l’entitlement « Associated Domains » : applinks:staging.my-domain.com?mode=developer. Cela est censé forcer l’appareil à ignorer le CDN et à télécharger le fichier directement depuis le domaine.
• Le Problème Pratique (Stack Overflow) : Des retours d’expérience de développeurs indiquent que depuis Xcode 14, le mode développeur est devenu peu fiable et ne fonctionne souvent plus, en particulier sur les simulateurs.
• Solution de Contournement Avancée :
  1. Tester sur un appareil physique : Le test sur simulateur est déconseillé.
  2. Activer « Associated Domains Development » dans les Réglages > Développeur sur l’iPhone.
  3. Utiliser un outil de proxy (ex: Proxyman, Charles) pour intercepter le trafic réseau de l’appareil.
  4. Bloquer les requêtes vers le CDN d’Apple (app-site-association.cdn-apple.com) pour forcer l’appareil à se rabattre sur le domaine d’origine.
  5. Supprimer et réinstaller l’application à chaque modification du fichier AASA. C’est une étape cruciale car le système ne vérifie le fichier qu’à l’installation/mise à jour.

5. Outils de Validation

Pour aider au diagnostic, plusieurs outils existent :

• Branch AASA Validator : Un outil tiers fréquemment mentionné qui teste un domaine par rapport aux exigences d’Apple et aux problèmes connus en production.
• Validateurs JSON génériques : Utiles pour s’assurer que la syntaxe du fichier AASA est correcte avant de le déployer.

Note : Les outils de validation officiels d’Apple (search.developer.apple.com/appsearch-validation-tool/) semblent ne plus être disponibles.

6. Contexte Android : Les App Links

L’écosystème Android possède un mécanisme équivalent appelé App Links.

• Fichier de configuration : assetlinks.json.
• Emplacement : https://<votre-domaine>/.well-known/assetlinks.json.
• Contenu : Le fichier assetlinks.json ne contient pas la configuration des chemins. Il spécifie principalement le package_name de l’application Android et les empreintes sha256_cert_fingerprints de son certificat de signature.
• Configuration des chemins : La logique de correspondance des chemins URL est entièrement gérée côté application, dans le fichier AndroidManifest.xml, via des intent-filter avec le schéma https et la propriété android:autoVerify="true".