Comment corriger une incompatibilité entre l'ID de bundle et l'ID d'application des liens universels iOS

Pourquoi une incompatibilité de Bundle ID rompt-elle les liens universels iOS ? Une incompatibilité de Bundle ID rompt les liens universels lorsque l'identifiant d'application signé ne correspond pas à l'entrée correspondante AASA appID/appIDs pour le domaine associé, ce qui provoque l'échec de la vérification du domaine associé.

Un Bundle ID (CFBundleIdentifier) est une chaîne unique qui identifie une application iOS individuelle au sein de l'écosystème Apple. Dans les architectures de liens universels, le Bundle ID est concaténé avec le préfixe d'identifiant d'application pour former l'identifiant d'application, que le système d'exploitation valide par rapport au fichier apple-app-site-association hébergé pour autoriser la gestion native des URL.

Chaîne de diagnostic canonique

Le diagramme ci-dessous illustre la séquence de vérification à plusieurs niveaux exécutée lors de l'installation de l'application et de la validation du domaine :

Layer 1: Signed App Binary
       │
       ├── application-identifier (<Prefix>.<BundleID>)
       ├── com.apple.developer.team-identifier
       └── com.apple.developer.associated-domains (applinks:example.com)
                    │
                    ▼
Layer 2: AASA Delivery & CDN Ingestion
       │ (Apple-managed infrastructure retrieves origin AASA)
                    ▼
Layer 3: AASA Schema & Pattern Matching
       │ (Validates appIDs array and components/paths routing rules)
                    ▼
Layer 4: Device Association State
       │ (Operating system registers verified domains in local database)
                    ▼
Layer 5: Application Routing Execution
       │ (System routes matching URLs to application lifecycle handlers)

Liste de contrôle de correction rapide : Routine de diagnostic en 30 secondes

Lorsque les liens universels reviennent de manière inattendue à la gestion Web, vérifiez ces éléments dans l'ordre :

• Extraire l'identifiant signé : Inspectez l'habilitation intégrée du binaire compilé pour obtenir l'exact application-identifier (<Prefix>.<BundleID>).
• Vérifier le format des habilitations : Confirmez que com.apple.developer.associated-domains contient le nom d'hôte exact (par ex., applinks:subdomain.domain.com) sans chemins inutiles, chaînes de requête ou barres obliques de fin.
• Auditer l'AASA d'origine : Récupérez https://subdomain.domain.com/.well-known/apple-app-site-association et assurez-vous que l'identifiant d'application signé est répertorié textuellement dans appIDs.
• Valider la correspondance des chemins : Confirmez que l'URL cible correspond aux modèles components ou paths définis dans la configuration AASA.
• Vérifier la portée du domaine : Assurez-vous que l'habilitation du domaine associé couvre le nom d'hôte cible et que la configuration AASA correspondante est disponible pour ce nom d'hôte. Pour les sous-domaines, utilisez un nom d'hôte explicite ou le format de caractère générique *. pris en charge, le cas échéant.
• Isoler les modes de développement : Utilisez ?mode=developer sur les builds signés pour le développement afin de contourner la mise en cache CDN d'Apple pendant l'itération.

Pourquoi la précision du Bundle ID et de l'identifiant d'application est importante

L'anatomie d'un identifiant d'application

La vérification des liens universels n'évalue pas le nom d'affichage de l'application, le schéma d'URL interne ou le nom du bundle. Selon la documentation Apple sur applinks.Details, le modèle de sécurité repose strictement sur l'identifiant d'application pleinement qualifié, structuré comme suit :

Où :

• ApplicationIdentifierPrefix : Le préfixe d'ID d'application attribué dans la configuration de votre compte Développeur Apple (par ex., 9JA723G82S). Pour de nombreux comptes de développeur modernes, cette valeur correspond à l'ID d'équipe à 10 caractères, mais les ingénieurs doivent vérifier le préfixe réel dans leur portail Développeur Apple plutôt que de supposer que les deux sont interchangeables.
• CFBundleIdentifier (Bundle ID) : La chaîne DNS inversée sensible à la casse définie dans les paramètres de build de la cible (par ex., com.example.mobileapp).

Dans le fichier JSON apple-app-site-association (AASA) hébergé, cette chaîne composite apparaît dans le tableau appIDs ou les entrées de dictionnaire appID (par ex., 9JA723G82S.com.example.mobileapp). S'il existe une divergence de caractères, une différence de casse ou un espace de fin entre l'habilitation intégrée du binaire compilé et l'entrée AASA hébergée, la vérification du domaine échoue.

Une incompatibilité de Bundle ID est l'une des causes les plus prioritaires à vérifier lors du triage de l'intégration, mais ce n'est pas la seule raison pour laquelle un lien universel peut basculer vers le Web.

Comment les domaines associés et l'AASA établissent une association bilatérale

Contrairement aux schémas d'URL personnalisés, que toute application installée peut déclarer sans vérification de domaine, les liens universels établissent une association bilatérale sécurisée :

• Déclaration de l'application au domaine : L'application iOS compilée déclare qu'elle revendique la propriété d'un domaine Web spécifique en incluant l'habilitation com.apple.developer.associated-domains dans sa signature de code.
• Autorisation du domaine à l'application : Le domaine Web confirme qu'il accorde l'autorisation de routage à des applications spécifiques en hébergeant le fichier JSON AASA sur https://<domain>/.well-known/apple-app-site-association ou https://<domain>/apple-app-site-association.

Lors de l'installation ou des mises à jour de l'application, le système d'exploitation vérifie l'habilitation des domaines associés signés de l'application par rapport à la configuration AASA récupérée pour le domaine. L'identifiant d'application utilisé pour l'association d'application doit correspondre à l'identifiant correspondant déclaré dans la configuration AASA. Une fois que l'identifiant correspond, l'URL demandée doit également satisfaire aux règles components ou paths configurées.

Le symptôme d'échec : Pourquoi des identifiants incompatibles forcent des replis Web

Lorsqu'une incompatibilité d'identifiant d'application se produit, iOS n'affiche généralement pas d'incompatibilité d'identifiant d'application comme une exception d'exécution fatale. L'échec se reflète plutôt dans l'état de vérification du domaine associé, les diagnostics de l'appareil ou le comportement de repli Web résultant :

• Gestion du système : Lorsque l'association de domaine échoue, le système n'invoque pas l'application via le chemin de lien universel vérifié. Selon la manière dont l'URL a été ouverte et le contexte du navigateur environnant, l'URL reste dans la gestion Web ou y revient au lieu d'être transmise à l'application native.
• Impact sur l'expérience utilisateur : Lorsqu'un utilisateur appuie sur un lien Web correspondant dans Messages, Mail ou Safari, le système ne parvient pas à reconnaître un mappage d'application native autorisé et ouvre l'URL Web dans le navigateur.

Voir aussi : Bundle ID ──> Architecture des liens universels

Comment le CDN d'Apple récupère et met en cache les fichiers AASA

La liaison d'installation et la mécanique du CDN d'Apple

Lorsqu'une application contenant l'habilitation com.apple.developer.associated-domains est installée ou mise à jour, le système établit ou actualise une relation de domaine associé :

• Scrapeur géré par le CDN : Lorsque le système établit ou actualise une relation de domaine associé, il obtient les données AASA du domaine via l'infrastructure de domaines associés d'Apple et utilise ces données pour vérifier l'association.
• Cycle de vie de mise en cache indépendant : Le CDN géré par Apple contrôle son propre cycle de vie d'actualisation et de mise en cache, de sorte qu'il ne faut pas supposer qu'une mise à jour d'origine devient immédiatement visible via le CDN. Lors du test des modifications, utilisez le mode alternatif de développement documenté le cas échéant et inspectez l'état d'association de l'appareil.
• Exigences du serveur d'origine : Le serveur Web d'origine doit diffuser le fichier AASA via HTTPS avec un certificat TLS valide et de confiance (les certificats auto-signés sont rejetés), en utilisant le type MIME application/json. L'hébergement AASA ne doit pas dépendre de redirections HTTP ; le point de terminaison AASA doit renvoyer le fichier directement avec un code HTTP 200 OK.

Cohérence du format JSON AASA

Les versions iOS modernes prennent en charge la syntaxe granulaire du dictionnaire components tout en maintenant la rétrocompatibilité avec les tableaux paths hérités.

Selon la note technique TN3155 d'Apple Developer sur le débogage des liens universels, dans une entrée details donnée, les développeurs doivent utiliser soit la structure moderne appIDs + components, soit la structure héritée appID + paths ; ne mélangez pas les deux structures dans la même entrée, car des configurations mixtes peuvent produire un comportement de vérification inattendu.

Les anciens exemples AASA incluaient couramment "apps": []. Pour les déploiements ciblant les versions modernes du système d'exploitation Apple, cette clé n'est pas requise ; ne la conservez que lors de la prise en charge de versions de systèmes d'exploitation hérités qui l'attendent spécifiquement.

Protocole de diagnostic : Flux de travail de résolution étape par étape

Étape 1 : Inspecter les habilitations d'applications signées avec codesign

Pour déterminer si un fichier IPA exporté ou un build de debug contient l'identifiant d'application et les domaines associés exacts attendus, inspectez directement la signature de code du binaire à l'aide de l'utilitaire de ligne de commande macOS codesign. Vérifiez application-identifier, com.apple.developer.team-identifier et com.apple.developer.associated-domains ensemble.

Le profil de provisioning indique les fonctionnalités et les domaines autorisés par le profil ; l'exécutable signé (codesign) montre ce que contient réellement le binaire livré.

Étape 2 : Auditer le schéma JSON AASA hébergé

Vérifiez que le serveur d'origine héberge un fichier AASA valide qui est accessible publiquement sans authentification ni redirection. Notez que les anciens exemples AASA incluaient couramment "apps": [], tandis que les configurations modernes ciblant les versions iOS contemporaines omettent cette clé.

Le schéma JSON AASA standard ci-dessous illustre un routage de chemin correct utilisant la structure moderne appIDs et components :

```json
{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "9JA723G82S.com.example.mobileapp",
          "9JA723G82S.com.example.mobileapp.staging"
        ],
        "components": [
          {
            "/": "/product/*",
            "comment": "Matches product detail routes"
          },
          {
            "/": "/invite/*",
            "?": { "ref": "?*" },
            "comment": "Matches referral links with custom query parameters"
          },
          {
            "/": "/help/*",
            "exclude": true,
            "comment": "Excludes customer support URLs from native routing"
          }
        ]
      }
    ]
  }
}

Étape 3 : Exécuter des outils CLI de diagnostic (codesign, swcutil, curl)

Sur les versions de macOS qui fournissent des diagnostics swcutil, utilisez l'outil pour inspecter ou valider les données de domaine associé. Étant donné que les options de commande peuvent varier selon le système d'exploitation et les versions de la chaîne d'outils, confirmez les options disponibles avec swcutil --help avant d'exécuter les flux de travail de diagnostic ci-dessous :

# 0. Confirm available options (syntax may vary by OS and toolchain release)
swcutil --help

# 1. Unpack the exported IPA archive
unzip -q YourApp.ipa -d UnpackedApp

# 2. Extract and inspect signed entitlements directly from the executable binary
codesign -d --entitlements :- "UnpackedApp/Payload/YourApp.app" > signed-entitlements.plist 2>/dev/null
/usr/libexec/PlistBuddy -c "Print" signed-entitlements.plist

# 3. Check whether the AASA data can be downloaded for the domain using swcutil (macOS diagnostic tool)
sudo swcutil dl -d custom.opwakeup.com

# 4. Validate AASA pattern matching against a specific URL using swcutil
sudo swcutil verify -d custom.opwakeup.com -j ./apple-app-site-association -u https://custom.opwakeup.com/product/123

# 5. Query the Apple-managed Associated Domains CDN diagnostic endpoint directly
curl -i https://app-site-association.cdn-apple.com/a/v1/custom.opwakeup.com

Inspectez le point de terminaison CDN des domaines associés géré par Apple lors du dépannage des données AASA livrées en périphérie. Traitez ce point de terminaison comme une infrastructure de diagnostic plutôt que comme un contrat d'API publique.

Étape 4 : Utiliser le mode développeur des domaines associés pour les tests AASA

Selon la documentation Apple sur la configuration des domaines associés, Apple propose un mode alternatif pour le développement. Le mode developer (?mode=developer) permet aux appareils de développement éligibles de contourner le CDN géré par Apple et de récupérer le fichier AASA directement à partir du domaine associé via HTTPS.

La configuration ci-dessous montre comment déclarer le mode développeur dans des configurations d'habilitations Xcode distinctes :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>applinks:custom.opwakeup.com</string>
    </array>
</dict>
</plist>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>applinks:custom.opwakeup.com?mode=developer</string>
    </array>
</dict>
</plist>

Une fois que le système d'exploitation établit l'association de domaine, le routage au niveau de l'application gère les charges utiles d'URL entrantes à l'aide des délégués de cycle de vie UIKit ou SwiftUI standard :

import UIKit

// ----------------------------------------------------------------------------
// 1. UIKit AppDelegate Implementation
// ----------------------------------------------------------------------------
@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        return true
    }

    // Standard Apple Universal Link Continuation Callback
    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
              let incomingURL = userActivity.webpageURL else {
            return false
        }
        
        print("Handling verified Universal Link: \(incomingURL.absoluteString)")
        
        // Dispatch incomingURL to internal router or SDK layer for parameter extraction
        return handleIncomingRoute(incomingURL)
    }

    private func handleIncomingRoute(_ url: URL) -> Bool {
        // Application-level destination routing logic
        // Note: Returning true indicates the app handled the activity, not that URL parsing succeeded.
        return true
    }
}

// ----------------------------------------------------------------------------
// 2. SceneDelegate Lifecycle Implementation (iOS 13+)
// ----------------------------------------------------------------------------
class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        if let userActivity = connectionOptions.userActivities.first(where: { $0.activityType == NSUserActivityTypeBrowsingWeb }),
           let incomingURL = userActivity.webpageURL {
            print("Cold-launch Universal Link: \(incomingURL.absoluteString)")
        }
    }

    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        if userActivity.activityType == NSUserActivityTypeBrowsingWeb,
           let incomingURL = userActivity.webpageURL {
            print("Foreground Universal Link: \(incomingURL.absoluteString)")
        }
    }
}

Pour activer le mode développeur côté client sur un matériel physique :

1. Sur iOS 16+, accédez à Réglages > Confidentialité et sécurité > Mode développeur et activez-le (redémarrage de l'appareil requis).
2. Accédez à Réglages > Développeur > Développement des domaines associés et activez l'interrupteur.
3. Installez le build de développement signé avec un profil de provisioning de développement contenant l'habilitation ?mode=developer.
4. Remarque de production : Gardez ?mode=developer restreint aux configurations de développement et de test interne, et ne l'incluez pas dans l'habilitation des domaines associés de production à moins que votre déploiement ne nécessite et ne prenne explicitement en charge cette configuration.

Arbre de décision des causes profondes

Universal Link falls back to web handling
        │
        ├── Does signed application-identifier match AASA appIDs?
        │       ├── NO ──> Correct App ID Prefix or Bundle ID in AASA
        │       └── YES
        │
        ├── Does associated-domains entitlement list the exact domain?
        │       ├── NO ──> Add applinks:<domain> to target entitlements
        │       └── YES
        │
        ├── Does sudo swcutil dl -d <domain> succeed?
        │       ├── NO ──> Fix origin HTTPS, TLS certificates, or 301/302 redirects
        │       └── YES
        │
        ├── Does sudo swcutil verify match the target URL path?
        │       ├── NO ──> Correct components or paths syntax in AASA
        │       └── YES
        │
        └── Check device association state and internal application routing handlers

Matrice de diagnostic : Causes profondes des pannes de liens universels

Mise en œuvre d'une configuration à double environnement dans Xcode

Gestion de plusieurs configurations de build (Debug, Staging, Production)

Les pipelines de développement d'entreprise gèrent fréquemment des Bundle ID distincts selon les environnements de build (par ex., com.example.app.debug, com.example.app.staging, com.example.app).

Pour maintenir des liens universels fonctionnels dans toutes les configurations de build :

• Déclarations AASA explicites : Le fichier AASA hébergé doit explicitement lister l'identifiant d'application pleinement qualifié de chaque environnement dans son tableau appIDs :

  "appIDs": [
    "9JA723G82S.com.example.app",
    "9JA723G82S.com.example.app.staging",
    "9JA723G82S.com.example.app.debug"
  ]
  
  

• Habilitations spécifiques à la cible : Utilisez les paramètres de configuration de build Xcode pour lier des fichiers .entitlements distincts par configuration de build, garantissant ainsi que les domaines de production ne sont pas interrogés par les builds de debug internes.

Gestion des identifiants cibles

Pour le dépannage des liens universels, utilisez le Bundle ID exact et le préfixe d'identifiant d'application du build signé plutôt que de vous fier à des identifiants génériques. Traitez chaque nom d'hôte explicitement : si l'application revendique example.com et www.example.com, configurez les entrées de domaine associé correspondantes et assurez-vous que chaque nom d'hôte dessert les données AASA appropriées. Assurez-vous que l'habilitation est configurée sur la cible qui gère réellement les liens universels, et vérifiez séparément toutes les extensions d'application ou cibles watchOS le cas échéant.

Validation des profils de provisioning intégrés et des binaires signés dans CI/CD

Automatisez la vérification des habilitations et de l'identifiant d'application dans les scripts de build d'intégration continue avant de télécharger les binaires sur TestFlight :

# Automated CI validation script
security cms -D -i /path/to/embedded.mobileprovision > provision.plist

# 1. Inspect profile entitlements for allowed Associated Domains
/usr/libexec/PlistBuddy -c "Print :Entitlements:com.apple.developer.associated-domains" provision.plist

# 2. Extract actual signed entitlements from the compiled executable binary
codesign -d --entitlements :- "UnpackedApp/Payload/YourApp.app" > signed-entitlements.plist 2>/dev/null
SIGNED_APP_ID=$(/usr/libexec/PlistBuddy -c "Print :application-identifier" signed-entitlements.plist)
echo "Extracted Signed Application Identifier: $SIGNED_APP_ID"

# 3. Validate that signed Associated Domains match the target domain
/usr/libexec/PlistBuddy -c "Print :com.apple.developer.associated-domains" signed-entitlements.plist

# 4. Verify that the signed App ID exists in the hosted AASA file via Python
python3 -c "
import json, sys
signed_id = sys.argv[1]
data = json.load(open('apple-app-site-association'))
app_ids = [app for detail in data.get('applinks', {}).get('details', []) for app in detail.get('appIDs', [])]
if signed_id not in app_ids:
    print(f'AASA mismatch: {signed_id} not found in AASA appIDs: {app_ids}')
    sys.exit(1)
print(f'AASA consistency check passed: {signed_id} registered')
" "$SIGNED_APP_ID"

Si le script de vérification se termine par un code d'erreur, abandonnez le pipeline de build pour éviter d'expédier en production des binaires de deep linking non fonctionnels.

Critères de correspondance des liens universels

Pour garantir un routage fiable, les conditions suivantes doivent être remplies simultanément :

Signed App Configuration:
application-identifier = <ApplicationIdentifierPrefix>.<CFBundleIdentifier>
com.apple.developer.associated-domains = applinks:<hostname>

AASA Configuration:
appIDs = [..., "<ApplicationIdentifierPrefix>.<CFBundleIdentifier>", ...]
components / paths = Matching target URL paths and query parameters

System Eligibility:
1. Associated Domains entitlement explicitly contains the target hostname.
2. The signed Application Identifier matches an authorized entry in the domain's AASA appIDs.
3. The incoming URL satisfies the AASA routing patterns.
4. Device association state and user/browser context permit native application delegation.

Même lorsque l'habilitation, l'association AASA et le modèle d'URL correspondent tous, le routage observé peut toujours dépendre de l'état de l'appareil et du contexte de l'utilisateur ou du navigateur. Par exemple, lorsqu'un utilisateur appuie sur un lien universel alors qu'il navigue déjà sur le même domaine dans Safari, le système d'exploitation peut respecter l'intention de l'utilisateur de rester dans Safari.

Résumé et cadre de décision

La fiabilité du routage des liens universels dépend d'un alignement précis, au niveau des caractères, entre trois nœuds : la configuration de l'ID d'application du portail Développeur Apple, l'habilitation Xcode com.apple.developer.associated-domains et le fichier JSON apple-app-site-association hébergé. Un SDK tiers ou un framework de routage ne peut pas réparer une association de domaine de système d'exploitation défaillante ; il ne peut traiter l'URL qu'après qu'iOS a livré avec succès le lien universel à l'application. Si les liens universels sont correctement associés au niveau du système d'exploitation mais que l'extraction des paramètres échoue, inspectez la couche de routage au niveau de l'application séparément de la couche d'association de domaine.

Si votre application nécessite également la restauration de paramètres de liens dynamiques et le routage d'intégration après le succès de l'association de liens universels, OpoInstall fournit une couche SDK optionnelle pour ce flux de travail au niveau de l'application.

Pour en savoir plus sur les modèles de configuration de domaine et l'intégration du deep linking, consultez la documentation sur le deep linking d'OpoInstall.

Matériel connexe

• Concepts : Vérification de l'identifiant d'application, Validation du schéma AASA, Mise en cache CDN d'Apple, Extraction des habilitations

• Technologies : Liens universels iOS, Habilitations Xcode, Portail Développeur Apple, Identifiants Web partagés

• Normes : IETF RFC 8259 (Échange de données JSON), Spécification TLS 1.3

• Outils de diagnostic : Outil CLI codesign d'Apple, Outil macOS swcutil, Requête de cache CDN géré par Apple

Documentation officielle

• Documentation Apple Developer sur la prise en charge des domaines associés

• Documentation Apple Developer sur la configuration des habilitations de domaines associés

• Note technique Apple Developer TN3155 : Débogage des liens universels

• Documentation Apple Developer sur la prise en charge des liens universels dans votre application