Vérifier le fichier Universal Links depuis un Mac cloud

Le lien vers un produit fonctionne dans le navigateur, mais ouvre systématiquement une page web lorsqu’on le teste avec l’application installée sur un appareil. Modifier d’emblée le code de navigation de l’app risque de faire passer à côté de la véritable cause : l’appareil doit d’abord récupérer le fichier d’association publié par le domaine, puis vérifier que celui-ci autorise l’app à prendre en charge les chemins concernés. Un Mac cloud permet de contrôler la livraison du fichier avant de refaire le test sur l’appareil. Consigner séparément les résultats côté serveur et côté appareil est plus utile que de cliquer plusieurs fois sur le lien.

Isoler un cas d’échec reproductible

Notez l’URL complète, l’app qui devrait s’ouvrir, ce qui s’ouvre réellement, la version du système de l’appareil et celle du build de l’app. Préparez au moins deux liens : l’un que l’app devrait prendre en charge, l’autre qui devrait rester dans le navigateur. Ne vous contentez pas d’indiquer que « tous les liens échouent » : selon le domaine, le chemin et les paramètres de requête, les règles applicables peuvent être très différentes.

Précisez aussi la façon dont le test est effectué. Cliquer sur un lien et saisir manuellement son URL dans la barre d’adresse du navigateur ne constituent pas le même test. Toute l’équipe doit reprendre le même point de départ. Si la production et la préproduction utilisent des domaines différents, créez une fiche pour chacun : le fichier d’un domaine ne permet pas d’expliquer le comportement de l’autre.

Consignez dans deux colonnes « ce que renvoie actuellement le serveur » et « la façon dont cet appareil ouvre actuellement le lien ». Le premier résultat peut être revérifié immédiatement ; le second peut dépendre de l’installation et du cache.

Vérifier que le fichier est servi directement

Dans le terminal du Mac cloud, renseignez le domaine réellement contrôlé par l’équipe, et non l’identifiant du paquet de l’app. Le fichier d’association doit être accessible directement à l’adresse /.well-known/apple-app-site-association. Ne laissez pas la commande suivre automatiquement les redirections : une réponse correcte obtenue après redirection pourrait alors être prise à tort pour un accès direct au fichier.

export APP_DOMAIN='填入团队实际控制的域名'
test "$APP_DOMAIN" != '填入团队实际控制的域名' || exit 1
curl -sS -D aasa-headers.txt \
  -o aasa-body.json \
  "https://${APP_DOMAIN}/.well-known/apple-app-site-association"
cat aasa-headers.txt
wc -c aasa-body.json
plutil -lint -- aasa-body.json

Vérifiez que le statut HTTP est 200, qu’aucun en-tête Location ne pointe vers une page de connexion ou un autre chemin, que le corps n’est pas une page d’erreur HTML et que le Content-Type est application/json. Un résultat positif de plutil prouve seulement que la syntaxe est analysable, pas que les règles sont correctes. Si la commande échoue à cause d’une erreur réseau, vérifiez d’abord la résolution du domaine et la connectivité TLS ; ne prenez pas un ancien fichier aasa-body.json présent sur le disque pour le résultat du test. Au besoin, supprimez l’ancien fichier avant de relancer la commande et conservez ensemble les en-têtes et le corps de la réponse.

Comparer plusieurs points d’accès au réseau

Si le fichier passe par un cache ou un proxy inverse, demandez la même adresse depuis le réseau habituellement utilisé par l’équipe et depuis le Mac cloud. Comparez le contenu du corps ainsi que les informations de cache dans les en-têtes. Si les résultats diffèrent, examinez d’abord le chemin de publication, la clé de cache et la procédure de purge. N’assouplissez pas toutes les règles de cache pour masquer le problème : l’objectif est que le fichier d’association d’un même domaine renvoie de façon fiable le contenu attendu.

Vérifier les identifiants et les règles de chemin

Repérez l’entrée correspondante dans applinks.details du JSON et comparez caractère par caractère son appID, composé de l’identifiant d’équipe et de l’identifiant du paquet de l’app. Vérifiez ensuite chaque chemin des URL qui échouent par rapport aux règles. La sensibilité à la casse, la présence d’une barre oblique finale et l’effet éventuel d’une règle d’exclusion avant une règle plus large doivent être examinés selon le format de règles réellement utilisé par le fichier. Le fait qu’un chemin soit accessible sur le site ne signifie pas nécessairement que l’app peut le prendre en charge.

Les paramètres de requête peuvent aider l’app à retrouver le contenu après son ouverture, mais ils ne remplacent pas la vérification de la correspondance du chemin de l’URL. Si l’équipe migre de l’ancien format paths vers components, assurez-vous d’abord que le système cible des appareils prend en charge la syntaxe choisie, puis validez-la avec de vrais liens de test. Ne modifiez pas simultanément les identifiants, les règles et le code de l’app sans cas témoin.

Contrôler ensuite le build et l’appareil

Une fois le fichier côté serveur vérifié, contrôlez la configuration des domaines associés utilisée pour construire l’app. Chaque entrée doit désigner le nom d’hôte qui sert réellement le fichier ; ne considérez pas des sous-domaines comme interchangeables par défaut. Assurez-vous que le build installé sur l’appareil est bien celui que vous venez de vérifier, et non un paquet issu d’une autre branche de publication. Après une modification de configuration, il faut reconstruire et réinstaller l’app : rafraîchir le seul fichier côté serveur ne change pas la configuration de l’app déjà installée.

Conservez sur l’appareil de test une trace du comportement « avant modification », puis installez le nouveau build et cliquez sur le même lien depuis la même source. Si le serveur renvoie les nouvelles règles mais que l’appareil conserve l’ancien comportement, réinstallez l’app avant de recommencer et notez les deux résultats. Ne supposez pas que la récupération et la validation du fichier d’association sont instantanées ; un seul clic ne suffit pas à conclure qu’une modification du serveur est sans effet.

Isoler la couche en cause plutôt que tout retester à la fois

Si le fichier est inaccessible ou renvoie une redirection, corrigez sa livraison. S’il est accessible mais que les identifiants ou les chemins ne correspondent pas, corrigez les règles ou la configuration du build. Si tout correspond et qu’un seul appareil échoue, comparez son historique d’installation, sa version système et la provenance du clic. Ne modifiez qu’une couche à la fois et conservez, avant et après chaque changement, les en-têtes de réponse, le contenu du fichier, l’identifiant du build et les observations sur l’appareil. Vous pourrez ainsi déterminer quelle modification a produit l’effet observé.

Intégrer le contrôle au processus de publication

Ajoutez éventuellement une vérification légère à la procédure de publication : demander le fichier d’association sur le domaine de production, exiger une réponse sans redirection avec le bon statut et un JSON analysable, puis contrôler les règles à l’aide d’un chemin que l’app doit prendre en charge et d’un autre qu’elle ne doit pas prendre en charge. Un contrôle automatisé ne couvre que le serveur et la configuration statique ; il faut encore valider sur un appareil, avec le build installé, quelle application s’ouvre après un clic.

Enfin, réunissez dans une même fiche le cas d’échec, la réponse obtenue, la règle correspondante et le résultat du nouveau test sur l’appareil. La prochaine fois qu’un lien s’ouvrira sur le web mais pas dans l’app, la personne d’astreinte pourra reprendre l’enquête à partir de la dernière étape validée, sans devoir commencer par deviner si le code des liens ou le cache est en cause.

Questions fréquentes