So beheben Sie Bundle-ID- und AASA-App-ID-Fehlanpassungen bei iOS Universal Links

Warum führt eine Bundle-ID-Fehlanpassung zum Fehlschlagen von iOS Universal Links? Eine Fehlanpassung der Bundle-ID führt dann zum Fehlschlagen von Universal Links, wenn die signierte Anwendungsbezeichnung der App nicht mit dem entsprechenden AASA-appID/appIDs-Eintrag für die zugehörige Domain übereinstimmt, wodurch die Überprüfung der verknüpften Domains fehlschlägt.

Eine Bundle-ID (CFBundleIdentifier) ist eine eindeutige Zeichenfolge, die eine einzelne iOS-Anwendung innerhalb des Apple-Ökosystems identifiziert. In Universal-Link-Architekturen wird die Bundle-ID mit dem Anwendungsbezeichnungs-Präfix verkettet, um die Anwendungsbezeichnung zu bilden, welche das Betriebssystem gegen die gehostete apple-app-site-association-Datei validiert, um die native URL-Verarbeitung zu autorisieren.

Kanonische Diagnosekette

Das folgende Diagramm veranschaulicht die mehrstufige Verifizierungssequenz, die bei der App-Installation und Domainvalidierung ausgeführt wird:

Ebene 1: Signiertes App-Binärdatei
       │
       ├── application-identifier (<Präfix>.<BundleID>)
       ├── com.apple.developer.team-identifier
       └── com.apple.developer.associated-domains (applinks:example.com)
                    │
                    ▼
Ebene 2: AASA-Bereitstellung & CDN-Erfassung
       │ (Von Apple verwaltete Infrastruktur ruft die Ursprungs-AASA ab)
                    ▼
Ebene 3: AASA-Schema & Mustervergleich
       │ (Validiert das appIDs-Array und die Routing-Regeln für components/paths)
                    ▼
Ebene 4: Gerätezuordnungsstatus
       │ (Das Betriebssystem registriert verifizierte Domains in der lokalen Datenbank)
                    ▼
Ebene 5: Ausführung des Anwendungs-Routings
       │ (Das System leitet übereinstimmende URLs an die App-Lebenszyklus-Handler weiter)

Schnellbehebungs-Checkliste: 30-Sekunden-Diagnoseroutine

Wenn Universal Links unerwartet auf die Web-Verarbeitung zurückfallen, überprüfen Sie diese Punkte in der folgenden Reihenfolge:

• Signierten Identifikator extrahieren: Untersuchen Sie die eingebettete Berechtigung der kompilierten Binärdatei, um das genaue application-identifier (<Präfix>.<BundleID>) zu ermitteln.
• Berechtigungsformat verifizieren: Bestätigen Sie, dass com.apple.developer.associated-domains den exakten Hostnamen (z. B. applinks:subdomain.domain.com) ohne unnötige Pfade, Abfragezeichenfolgen oder nachgestellte Schrägstriche enthält.
• Ursprungs-AASA prüfen: Rufen Sie https://subdomain.domain.com/.well-known/apple-app-site-association ab und stellen Sie sicher, dass die signierte Anwendungsbezeichnung wörtlich in appIDs aufgeführt ist.
• Pfadabgleich validieren: Bestätigen Sie, dass die Ziel-URL den in der AASA-Konfiguration definierten Mustern für components oder paths entspricht.
• Domain-Scoping prüfen: Stellen Sie sicher, dass die Berechtigung für verknüpfte Domains den Zielhostnamen abdeckt und dass die entsprechende AASA-Konfiguration für diesen Hostnamen verfügbar ist. Verwenden Sie für Subdomains einen expliziten Hostnamen oder die unterstützte *.-Platzhalterform, je nach Bedarf.
• Entwicklungsmodi isolieren: Verwenden Sie ?mode=developer bei entwicklungssignierten Builds, um das Apple-CDN-Caching während der Iteration zu umgehen.

Warum die Genauigkeit von Bundle-ID und Anwendungsbezeichnung wichtig ist

Die Anatomie einer Anwendungsbezeichnung

Bei der Universal-Link-Verifizierung werden weder der Anzeigename der Anwendung, das interne URL-Schema noch der Bundle-Name ausgewertet. Gemäß der Apple-Dokumentation zu applinks.Details stützt sich das Sicherheitsmodell strikt auf die voll qualifizierte Anwendungsbezeichnung, strukturiert als:

Wobei:

• ApplicationIdentifierPrefix: Das App-ID-Präfix, das in Ihrer Apple Developer-Kontokonfiguration zugewiesen wurde (z. B. 9JA723G82S). Bei vielen modernen Entwicklerkonten entspricht dieser Wert der 10-stelligen Team-ID, Entwickler sollten jedoch das tatsächliche Präfix in ihrem Apple Developer Portal überprüfen, anstatt anzunehmen, dass beide austauschbar sind.
• CFBundleIdentifier (Bundle-ID): Die groß-/kleinschreibungsabhängige Reverse-DNS-Zeichenfolge, die in den Buildeinstellungen des Ziels definiert ist (z. B. com.example.mobileapp).

In der gehosteten apple-app-site-association (AASA)-JSON-Datei erscheint diese zusammengesetzte Zeichenfolge innerhalb des appIDs-Arrays oder der appID-Wörterbucheinträge (z. B. 9JA723G82S.com.example.mobileapp). Wenn eine Zeichenabweichung, ein Unterschied in der Groß-/Kleinschreibung oder ein nachgestelltes Leerzeichen zwischen der eingebetteten Berechtigung der kompilierten Binärdatei und dem gehosteten AASA-Eintrag besteht, schlägt die Domain-Verifizierung fehl.

Eine Fehlanpassung der Bundle-ID gehört zu den Ursachen mit der höchsten Priorität bei der Integrationsprüfung, ist jedoch nicht der einzige Grund, warum ein Universal Link auf das Web zurückfallen kann.

Wie verknüpfte Domains und AASA eine zweiseitige Zuordnung herstellen

Im Gegensatz zu benutzerdefinierten URL-Schemata, die jede installierte Anwendung ohne Domainverifizierung deklarieren kann, stellen Universal Links eine sichere, zweiseitige Zuordnung her:

• App-zu-Domain-Deklaration: Die kompilierte iOS-Anwendung deklariert, dass sie den Anspruch auf eine bestimmte Web-Domain erhebt, indem sie die Berechtigung com.apple.developer.associated-domains in ihre Codesignatur einbindet.
• Domain-zu-App-Autorisierung: Die Web-Domain bestätigt, dass sie bestimmten Anwendungen die Routing-Autorisierung erteilt, indem sie die AASA-JSON-Datei unter https://<domain>/.well-known/apple-app-site-association oder https://<domain>/apple-app-site-association hostet.

Während der Installation oder von App-Updates überprüft das Betriebssystem die signierte Berechtigung für verknüpfte Domains der App anhand der für die Domain abgerufenen AASA-Konfiguration. Die für die App-Zuordnung verwendete Anwendungsbezeichnung muss mit der entsprechenden in der AASA-Konfiguration deklarierten Bezeichnung übereinstimmen. Nach der Übereinstimmung der Bezeichnung muss die angeforderte URL auch die konfigurierten components- oder paths-Regeln erfüllen.

Das Fehlersymptom: Warum nicht übereinstimmende Bezeichnungen Web-Fallbacks erzwingen

Wenn eine Fehlanpassung der Anwendungsbezeichnung auftritt, meldet iOS diese normalerweise nicht als schwerwiegenden Laufzeitfehler. Der Fehler spiegelt sich stattdessen im Verifizierungsstatus der verknüpften Domains, in der Gerätediagnose oder im resultierenden Web-Fallback-Verhalten wider:

• Systemverarbeitung: Wenn die Domain-Zuordnung fehlschlägt, ruft das System die App nicht über den verifizierten Universal-Link-Pfad auf. Abhängig davon, wie die URL geöffnet wurde und dem umgebenden Browserkontext, verbleibt die URL in der Web-Verarbeitung oder fällt auf diese zurück, anstatt an die native Anwendung übergeben zu werden.
• Auswirkung auf die Nutzererfahrung: Wenn ein Nutzer auf einen passenden Weblink in Nachrichten, Mail oder Safari tippt, erkennt das System keine autorisierte native App-Zuordnung und öffnet stattdessen die Web-URL im Browser.

Siehe auch: Bundle-ID ──> Universal-Links-Architektur

Wie das Apple-CDN AASA-Dateien abruft und zwischenspeichert

Der Installations-Handshake und die Apple-CDN-Mechanik

Wenn eine Anwendung, die die Berechtigung com.apple.developer.associated-domains enthält, installiert oder aktualisiert wird, richtet das System eine Beziehung für verknüpfte Domains ein oder aktualisiert diese:

• CDN-vermittelter Scraper: Wenn das System eine Beziehung für verknüpfte Domains einrichtet oder aktualisiert, ruft es die AASA-Daten der Domain über die Infrastruktur für verknüpfte Domains von Apple ab und verwendet diese Daten, um die Zuordnung zu verifizieren.
• Unabhängiger Caching-Lebenszyklus: Das von Apple verwaltete CDN steuert seinen eigenen Aktualisierungs- und Caching-Lebenszyklus, sodass nicht davon ausgegangen werden kann, dass eine Aktualisierung des Ursprungs sofort über das CDN sichtbar wird. Verwenden Sie zum Testen von Änderungen den dokumentierten alternativen Entwicklungsmodus, sofern angebracht, und überprüfen Sie den Gerätezuordnungsstatus.
• Anforderungen an den Ursprungsserver: Der Ursprungswebserver muss die AASA-Datei über HTTPS mit einem gültigen, vertrauenswürdigen TLS-Zertifikat (selbstsignierte Zertifikate werden abgelehnt) unter Verwendung des MIME-Typs application/json bereitstellen. Das AASA-Hosting darf sich nicht auf HTTP-Weiterleitungen verlassen; der AASA-Endpunkt sollte die Datei direkt mit einem HTTP 200 OK zurückgeben.

Konsistenz des AASA-JSON-Formats

Moderne iOS-Versionen unterstützen die granulare components-Wörterbuchsyntax bei gleichzeitiger Beibehaltung der Abwärtskompatibilität mit älteren paths-Arrays.

Gemäß der Apple Developer Technote TN3155 zum Debuggen von Universal Links sollten Entwickler innerhalb eines bestimmten details-Eintrags entweder die moderne appIDs + components-Struktur oder die ältere appID + paths-Struktur verwenden; mischen Sie die beiden Strukturen nicht im selben Eintrag, da gemischte Konfigurationen zu unerwartetem Verifizierungsverhalten führen können.

Ältere AASA-Beispiele enthielten häufig "apps": []. Für Bereitstellungen, die auf moderne Apple-Betriebssystemversionen abzielen, ist dieser Schlüssel nicht erforderlich; behalten Sie ihn nur bei, wenn ältere Betriebssystemversionen unterstützt werden, die dies ausdrücklich erwarten.

Diagnoseprotokoll: Schritt-für-Schritt-Workflow zur Behebung

Schritt 1: Untersuchen der signierten App-Berechtigungen mit codesign

Um festzustellen, ob ein exportiertes IPA oder ein Debug-Build die exakt erwartete Anwendungsbezeichnung und die verknüpften Domains enthält, untersuchen Sie die Codesignatur der Binärdatei direkt mit dem macOS-Befehlszeilendienstprogramm codesign. Überprüfen Sie application-identifier, com.apple.developer.team-identifier und com.apple.developer.associated-domains gemeinsam.

Das Bereitstellungsprofil zeigt, welche Funktionen und Domains das Profil zulässt; die signierte ausführbare Datei (codesign) zeigt, was das ausgelieferte Binärpaket tatsächlich enthält.

Schritt 2: Überprüfen des gehosteten AASA-JSON-Schemas

Stellen Sie sicher, dass der Ursprungsserver eine gültige AASA-Datei hostet, die öffentlich und ohne Authentifizierung oder Weiterleitungen zugänglich ist. Beachten Sie, dass ältere AASA-Beispiele häufig "apps": [] enthielten, während moderne Konfigurationen für aktuelle iOS-Versionen diesen Schlüssel weglassen.

Das folgende standardmäßige AASA-JSON-Schema veranschaulicht das ordnungsgemäße Pfad-Routing unter Verwendung der modernen appIDs- und components-Struktur:

```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"
          }
        ]
      }
    ]
  }
}

Schritt 3: Ausführen von CLI-Diagnosetools (codesign, swcutil, curl)

Verwenden Sie auf macOS-Versionen, die swcutil-Diagnosen bereitstellen, das Tool zum Überprüfen oder Validieren von Daten zu verknüpften Domains. Da Befehlsoptionen über Betriebssystem- und Toolchain-Releases hinweg variieren können, bestätigen Sie die verfügbaren Optionen mit swcutil --help, bevor Sie die folgenden Diagnose-Workflows ausführen:

# 0. Verfügbare Optionen bestätigen (Syntax kann je nach Betriebssystem und Toolchain-Release variieren)
swcutil --help

# 1. Exportiertes IPA-Archiv entpacken
unzip -q YourApp.ipa -d UnpackedApp

# 2. Signierte Berechtigungen direkt aus der ausführbaren Binärdatei extrahieren und untersuchen
codesign -d --entitlements :- "UnpackedApp/Payload/YourApp.app" > signed-entitlements.plist 2>/dev/null
/usr/libexec/PlistBuddy -c "Print" signed-entitlements.plist

# 3. Prüfen, ob die AASA-Daten für die Domain mit swcutil (macOS-Diagnosetool) heruntergeladen werden können
sudo swcutil dl -d custom.opwakeup.com

# 4. AASA-Musterabgleich gegen eine spezifische URL mit swcutil validieren
sudo swcutil verify -d custom.opwakeup.com -j ./apple-app-site-association -u https://custom.opwakeup.com/product/123

# 5. Den von Apple verwalteten Associated Domains CDN-Diagnoseendpunkt direkt abfragen
curl -i https://app-site-association.cdn-apple.com/a/v1/custom.opwakeup.com

Untersuchen Sie den von Apple verwalteten Associated Domains CDN-Endpunkt bei der Behebung von Problemen mit über Edge-Netzwerke bereitgestellten AASA-Daten. Betrachten Sie diesen Endpunkt eher als Diagnoseinfrastruktur denn als öffentlichen API-Vertrag.

Schritt 4: Verwenden des Entwicklermodus für verknüpfte Domains zum AASA-Testen

Gemäß der Apple-Dokumentation zum Konfigurieren verknüpfter Domains stellt Apple einen alternativen Modus für die Entwicklung bereit. Der developer-Modus (?mode=developer) ermöglicht es berechtigten Entwicklungsgeräten, das von Apple verwaltete CDN zu umgehen und die AASA-Datei direkt über HTTPS von der verknüpften Domain abzurufen.

Die folgende Konfiguration zeigt, wie der Entwicklermodus in separaten Xcode-Berechtigungskonfigurationen deklariert wird:

<?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>

Sobald das Betriebssystem die Domain-Zuordnung herstellt, verarbeitet das anwendungssubjektive Routing eingehende URL-Nutzlasten mithilfe von Standard-UIKit- oder SwiftUI-Lebenszyklus-Delegaten:

import UIKit

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

    var window: UIWindow?

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

    // Standard Apple Universal Link-Fortsetzungs-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("Verarbeite verifizierten Universal Link: \(incomingURL.absoluteString)")
        
        // Leite incomingURL zur Parameterextraktion an den internen Router oder die SDK-Ebene weiter
        return handleIncomingRoute(incomingURL)
    }

    private func handleIncomingRoute(_ url: URL) -> Bool {
        // Ziel-Routing-Logik auf Anwendungsebene
        // Hinweis: Die Rückgabe von true bedeutet, dass die App die Aktivität verarbeitet hat, nicht, dass das URL-Parsing erfolgreich war.
        return true
    }
}

// ----------------------------------------------------------------------------
// 2. SceneDelegate-Lebenszyklus-Implementierung (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("Kaltstart-Universal-Link: \(incomingURL.absoluteString)")
        }
    }

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

So aktivieren Sie den clientseitigen Entwicklermodus auf physischer Hardware:

1. Navigieren Sie unter iOS 16+ zu Einstellungen > Datenschutz & Sicherheit > Entwicklermodus und schalten Sie ihn EIN (Gerätenustart erforderlich).
2. Navigieren Sie zu Einstellungen > Entwickler > Entwicklung verknüpfter Domains (Associated Domains Development) und schalten Sie den Schalter EIN.
3. Installieren Sie den Entwicklungs-Build, der mit einem Entwicklungs-Bereitstellungsprofil signiert ist, das die ?mode=developer-Berechtigung enthält.
4. Produktionshinweis: Beschränken Sie ?mode=developer auf Entwicklungs- und interne Testkonfigurationen und fügen Sie ihn nicht in die Berechtigung für verknüpfte Domains für die Produktion ein, es sei denn, Ihre Bereitstellung erfordert und unterstützt diese Konfiguration ausdrücklich.

Entscheidungsbaum für Ursachenanalysen

Universal Link fällt auf Web-Verarbeitung zurück
        │
        ├── Stimmt die signierte Anwendungsbezeichnung mit den AASA-appIDs überein?
        │       ├── NEIN ──> App-ID-Präfix oder Bundle-ID in AASA korrigieren
        │       └── JA
        │
        ├── Listet die Berechtigung für verknüpfte Domains die exakte Domain auf?
        │       ├── NEIN ──> applinks:<domain> zu den Zielberechtigungen hinzufügen
        │       └── JA
        │
        ├── Ist sudo swcutil dl -d <domain> erfolgreich?
        │       ├── NEIN ──> Ursprungs-HTTPS, TLS-Zertifikate oder 301/302-Weiterleitungen korrigieren
        │       └── JA
        │
        ├── Stimmt sudo swcutil verify mit dem Ziel-URL-Pfad überein?
        │       ├── NEIN ──> Syntax von components oder paths in AASA korrigieren
        │       └── JA
        │
        └── Gerätezuordnungsstatus und interne Anwendungs-Routing-Handler überprüfen

Diagnosematrix: Ursachen für Universal-Link-Ausfälle

Implementierung einer Dual-Environment-Konfiguration in Xcode

Verwaltung mehrerer Build-Konfigurationen (Debug, Staging, Production)

Enterprise-Entwicklungspipelines verwalten häufig verschiedene Bundle-IDs über Build-Umgebungen hinweg (z. B. com.example.app.debug, com.example.app.staging, com.example.app).

So stellen Sie funktionierende Universal Links über alle Build-Konfigurationen hinweg sicher:

• Explizite AASA-Deklarationen: Die gehostete AASA-Datei muss die voll qualifizierte Anwendungsbezeichnung jeder Umgebung explizit in ihrem appIDs-Array aufführen:

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

• Zielspezifische Berechtigungen: Verwenden Sie Xcode-Build-Konfigurationseinstellungen, um pro Build-Konfiguration unterschiedliche .entitlements-Dateien zu verknüpfen, wodurch sichergestellt wird, dass Produktionsdomains nicht von internen Debug-Builds abgefragt werden.

Verwaltung von Zielbezeichnern

Verwenden Sie zur Fehlerbehebung von Universal Links die genaue Bundle-ID und das Anwendungsbezeichnungs-Präfix aus dem signierten Build, anstatt sich auf Platzhalterbezeichner zu verlassen. Behandeln Sie jeden Hostnamen explizit: Wenn die App beansprucht, example.com und www.example.com zu bedienen, konfigurieren Sie die entsprechenden Einträge für verknüpfte Domains und stellen Sie sicher, dass jeder Hostname die entsprechenden AASA-Daten bereitstellt. Stellen Sie sicher, dass die Berechtigung für das Ziel konfiguriert ist, das die Universal Links tatsächlich verarbeitet, und überprüfen Sie App-Extension- oder watchOS-Ziele gegebenenfalls separat.

Validieren eingebetteter Berechtigungsprofile und signierter Binärdateien in CI/CD

Automatisieren Sie die Verifizierung von Berechtigungen und Anwendungsbezeichnungen in Continuous-Integration-Build-Skripten, bevor Binärdateien in TestFlight hochgeladen werden:

# Automatisiertes CI-Validierungsskript
security cms -D -i /path/to/embedded.mobileprovision > provision.plist

# 1. Profilberechtigungen auf zulässige verknüpfte Domains untersuchen
/usr/libexec/PlistBuddy -c "Print :Entitlements:com.apple.developer.associated-domains" provision.plist

# 2. Tatsächliche signierte Berechtigungen aus der kompilierten ausführbaren Binärdatei extrahieren
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 "Extrahierte signierte Anwendungsbezeichnung: $SIGNED_APP_ID"

# 3. Validieren, dass signierte verknüpfte Domains mit der Zieldomain übereinstimmen
/usr/libexec/PlistBuddy -c "Print :com.apple.developer.associated-domains" signed-entitlements.plist

# 4. Überprüfen über Python, ob die signierte App-ID in der gehosteten AASA-Datei vorhanden ist
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"

Wenn das Verifizierungsskript mit einem Fehlercode beendet wird, brechen Sie die Build-Pipeline ab, um die Auslieferung nicht funktionsfähiger Deep-Linking-Binärdateien an die Produktion zu verhindern.

Universal-Link-Abgleichskriterien

Um ein zuverlässiges Routing zu gewährleisten, müssen die folgenden Bedingungen gleichzeitig erfüllt sein:

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

AASA-Konfiguration:
appIDs = [..., "<ApplicationIdentifierPrefix>.<CFBundleIdentifier>", ...]
components / paths = Abgleich von Ziel-URL-Pfaden und Abfrageparametern

Systemberechtigung:
1. Die Berechtigung für verknüpfte Domains enthält explizit den Zielhostnamen.
2. Die signierte Anwendungsbezeichnung stimmt mit einem autorisierten Eintrag in den appIDs der AASA der Domain überein.
3. Die eingehende URL erfüllt die AASA-Routing-Muster.
4. Der Gerätezuordnungsstatus und der Nutzer-/Browserkontext erlauben die Delegation an die native Anwendung.

Selbst wenn Berechtigung, AASA-Zuordnung und URL-Muster übereinstimmen, kann das beobachtete Routing weiterhin vom Gerätestatus sowie vom Nutzer- oder Browserkontext abhängen. Wenn ein Nutzer beispielsweise auf einen Universal Link tippt, während er dieselbe Domain bereits in Safari durchstöbert, respektiert das Betriebssystem möglicherweise die Absicht des Nutzers, in Safari zu bleiben.

Zusammenfassung und Entscheidungsrahmen

Die Zuverlässigkeit des Universal-Link-Routings hängt von einer exakten, auf Zeichenebene präzisen Ausrichtung über drei Knoten hinweg ab: der App-ID-Konfiguration im Apple Developer Portal, der Xcode-Berechtigung com.apple.developer.associated-domains und der gehosteten JSON-Datei apple-app-site-association. Ein SDK eines Drittanbieters oder ein Routing-Framework kann eine fehlgeschlagene Domain-Zuordnung des Betriebssystems nicht reparieren; es kann die URL erst verarbeiten, nachdem iOS den Universal Link erfolgreich an die Anwendung übergeben hat. Wenn Universal Links auf Betriebssystemebene korrekt zugeordnet sind, aber die Parameterextraktion fehlschlägt, untersuchen Sie die Routing-Ebene der Anwendung separat von der Domain-Zuordnungsebene.

Wenn Ihre Anwendung nach erfolgreicher Universal-Link-Zuordnung zusätzlich eine Wiederherstellung von Parametern für dynamische Links und Onboarding-Routing erfordert, bietet OpoInstall eine optionale SDK-Ebene für diesen Workflow auf Anwendungsebene an.

Weitere Informationen zu Domain-Konfigurationsmustern und der Deep-Linking-Integration finden Sie in der OpoInstall Deep-Linking-Dokumentation.

Zugehörige Materialien

• Konzepte: Verifizierung von Anwendungsbezeichnungen, AASA-Schema-Validierung, Apple-CDN-Caching, Berechtigungsextraktion

• Technologien: iOS Universal Links, Xcode-Berechtigungen, Apple Developer Portal, Shared Web Credentials

• Standards: IETF RFC 8259 (JSON Data Interchange), TLS 1.3 Specification

• Diagnosetools: Apple codesign CLI-Tool, macOS swcutil-Tool, Abfrage des von Apple verwalteten CDN-Caches

Offizielle Dokumentation

• Apple Developer Documentation on Supporting Associated Domains

• Apple Developer Documentation on Configuring Associated Domains Entitlements

• Apple Developer Technote TN3155: Debugging Universal Links

• Apple Developer Documentation on Supporting Universal Links in Your App