Universal-Links-Zuordnungsdatei auf einem Cloud-Mac prüfen

Ein Produktlink aus dem Release-Branch funktioniert im Browser, öffnet auf einem Testgerät aber immer nur die Webseite statt der App. Wer jetzt direkt den Code für die Linkverarbeitung ändert, übersieht womöglich die eigentliche Fehlerquelle: Das Gerät muss zuerst die Zuordnungsdatei der Domain abrufen und prüfen, ob diese Domain der betreffenden App die Übernahme der jeweiligen Pfade erlaubt. Prüfen Sie die Auslieferung der Datei zunächst auf einem Cloud-Mac und testen Sie den Link danach erneut auf dem Gerät. Getrennt dokumentierte Server- und Gerätebefunde helfen mehr als wiederholtes Antippen.

Einen fehlgeschlagenen Testfall festhalten

Notieren Sie den vollständigen Link, die erwartete App, das tatsächliche Öffnungsverhalten, die Betriebssystemversion des Geräts und die Build-Version der App. Bereiten Sie mindestens zwei Links vor: einen, den die App übernehmen soll, und einen, der im Browser bleiben soll. „Kein Link funktioniert“ ist zu ungenau; je nach Domain, Pfad und Query-Parametern können ganz unterschiedliche Regeln greifen.

Halten Sie auch den Testweg fest. Einen anklickbaren Link zu öffnen ist nicht derselbe Test, wie die URL von Hand in die Adressleiste des Browsers einzugeben. Verwenden Sie bei Wiederholungstests denselben Einstiegspunkt. Falls Produktion und Staging unterschiedliche Domains nutzen, legen Sie getrennte Aufzeichnungen an. Die Datei einer Domain erklärt nicht das Verhalten einer anderen.

Halten Sie „Was liefert der Server jetzt zurück?“ und „Wie öffnet dieses Gerät den Link jetzt?“ in zwei Spalten fest. Ersteres lässt sich sofort nachprüfen; Letzteres kann vom Installationszustand und vom Cache abhängen.

Direkte Auslieferung der Datei prüfen

Setzen Sie im Terminal des Cloud-Macs die Domain ein, über die Ihr Team tatsächlich verfügt – nicht die Bundle-ID der App. Die Zuordnungsdatei muss direkt unter /.well-known/apple-app-site-association abrufbar sein. Lassen Sie den Befehl Weiterleitungen nicht automatisch folgen: Sonst kann eine erfolgreiche Antwort nach einer Weiterleitung fälschlich als direkte Auslieferung gelten.

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

Prüfen Sie, ob der HTTP-Status 200 ist, kein Location-Header auf eine Anmeldeseite oder einen anderen Pfad verweist, der Antworttext keine HTML-Fehlerseite ist und Content-Type den Wert application/json hat. Ein erfolgreicher plutil-Test belegt nur, dass die Syntax lesbar ist – nicht, dass die Regeln stimmen. Bricht der Befehl wegen eines Netzwerkfehlers ab, prüfen Sie zuerst die DNS-Auflösung und die TLS-Verbindung. Werten Sie eine alte aasa-body.json auf der Festplatte nicht als Ergebnis dieses Abrufs. Löschen Sie bei Bedarf die alten Dateien und führen Sie die Prüfung erneut aus; bewahren Sie Antwortheader und Antworttext gemeinsam auf.

Mehr als einen Netzwerkzugang testen

Wird die Datei über einen Cache oder Reverse Proxy ausgeliefert, rufen Sie dieselbe Adresse sowohl aus dem üblichen Teamnetz als auch vom Cloud-Mac ab. Vergleichen Sie den Dateiinhalt und die Cache-Angaben in den Antwortheadern. Weichen die Ergebnisse voneinander ab, prüfen Sie zuerst den Veröffentlichungsweg, den Cache-Schlüssel und den Ablauf zur Cache-Aktualisierung. Lockern Sie nicht pauschal sämtliche Cache-Regeln, um das Problem zu verdecken. Ziel ist, dass die Zuordnungsdatei derselben Domain zuverlässig den erwarteten Inhalt liefert.

Kennungen und Pfadregeln abgleichen

Suchen Sie in der JSON-Datei den entsprechenden Eintrag unter applinks.details und vergleichen Sie dessen appID Zeichen für Zeichen mit der Team-ID und der Bundle-ID der App, die im Build verwendet werden. Gleichen Sie anschließend jeden Pfad eines fehlgeschlagenen Testlinks mit den Regeln ab. Ob Groß- und Kleinschreibung relevant sind, ob ein abschließender Schrägstrich vorhanden ist und ob eine Ausschlussregel vor einer allgemeinen Regel greift, müssen Sie anhand des tatsächlich verwendeten Regelformats prüfen. Dass eine Webroute erreichbar ist, bedeutet nicht automatisch, dass die App den Link übernehmen kann.

Query-Parameter können der App nach dem Öffnen helfen, den richtigen Inhalt zu finden. Sie ersetzen aber nicht die Prüfung, ob der URL-Pfad passt. Wenn Ihr Team von den bisherigen paths auf components umstellt, prüfen Sie zuerst, ob das Zielbetriebssystem des Geräts die gewählte Schreibweise unterstützt. Verifizieren Sie die Änderung anschließend mit echten Testlinks. Ändern Sie Kennungen, Regeln und App-Code nicht gleichzeitig, ohne Vergleichsfälle festgelegt zu haben.

Danach Build und Gerät prüfen

Wenn die Serverdatei stimmt, prüfen Sie die Konfiguration der zugeordneten Domains im App-Build. Der Domaineintrag muss auf den Hostnamen verweisen, der die Datei tatsächlich ausliefert; Subdomains sind nicht automatisch gleichwertig. Stellen Sie sicher, dass auf dem Gerät wirklich der gerade geprüfte Build installiert ist und nicht ein Paket aus einem anderen Release-Branch. Nach einer Konfigurationsänderung müssen Sie die App neu bauen und installieren. Allein die Serverdatei zu aktualisieren ändert die Konfiguration einer bereits installierten App nicht.

Dokumentieren Sie das Verhalten des Testgeräts vor der Änderung. Installieren Sie dann den neuen Build und tippen Sie denselben Link aus derselben Quelle an. Liefert der Server bereits die neuen Regeln, während das Gerät weiterhin das alte Verhalten zeigt, können Sie die App neu installieren und erneut testen. Halten Sie beide Ergebnisse fest. Gehen Sie nicht davon aus, dass die Zuordnungsdatei sofort abgerufen und geprüft wird; ein einzelner Tipp reicht nicht, um eine Serveränderung für wirkungslos zu erklären.

Fehler an der jeweiligen Grenze eingrenzen statt alles erneut zu versuchen

Ist die Datei nicht abrufbar oder liefert der Server eine Weiterleitung, beheben Sie die Auslieferung. Ist die Datei abrufbar, aber Kennung oder Pfad passen nicht, korrigieren Sie die Regeln oder die Build-Konfiguration. Stimmen beide Seiten und nur ein einzelnes Gerät schlägt fehl, vergleichen Sie Installationsverlauf, Geräteversion und den Einstiegspunkt des Links. Ändern Sie jeweils nur eine Ebene und bewahren Sie Antwortheader, Dateiinhalt, Build-Kennungen und Gerätebeobachtungen vor und nach der Änderung auf. Nur so lässt sich feststellen, welche Änderung geholfen hat.

Prüfung in den Release-Prozess aufnehmen

Ergänzen Sie den Release-Job um eine einfache Prüfung: Rufen Sie die Zuordnungsdatei der Produktionsdomain ab, verlangen Sie eine Antwort ohne Weiterleitung, mit korrektem Status und lesbarem JSON, und gleichen Sie die Regeln mit einem Pfad ab, den die App übernehmen soll, sowie einem, den sie nicht übernehmen soll. Automatische Prüfungen decken nur den Server und die statische Konfiguration ab. Welche Anwendung den Link nach dem Antippen tatsächlich öffnet, muss weiterhin mit dem installierten Build auf einem Gerät geprüft werden.

Halten Sie zum Schluss den fehlgeschlagenen Testfall, die tatsächliche Antwort, die passende Regel und die Ergebnisse des Gerätetests in einem gemeinsamen Protokoll fest. Wenn das nächste Mal eine Webseite aufgeht, die App aber nicht, kann der Bereitschaftsdienst an der zuletzt erfolgreich geprüften Grenze ansetzen, statt zunächst über Link-Code oder Cache zu spekulieren.

Häufig gestellte Fragen