Kurzfassung

Dieser Beitrag erklärt, wie iOS Universal Links funktionieren und was für deren Implementierung erforderlich ist. Er behandelt, wie eingehende Links in einer iOS-App verarbeitet werden, wie die Apple App Site Association (AASA)-Datei erstellt und konfiguriert wird und wie die Datei korrekt gehostet wird, damit iOS eine Domain sicher mit einer App verknüpfen und übereinstimmende URLs aus dem Web in die App weiterleiten kann.

Für wen ist dieser Beitrag gedacht?

  • Softwareentwickler, die dieses Feature in ihre App integrieren möchten.
  • Technisch versierte Personen mit wenig oder keiner Erfahrung mit Universal Links, die etwas Neues lernen möchten.

Einführung

Habt ihr schon einmal auf eine Anzeige oder einen E-Mail-Link getippt und wurdet direkt zur gewünschten Anwendung weitergeleitet, ohne eine Website oder ein Pop-up zu sehen, das um Erlaubnis bittet? Dieser nahtlose Übergang vom Web zur App ist keine Magie – er wird durch Universal Links ermöglicht.

Universal Links ermöglichen es iOS (oder Android), eure App automatisch zu öffnen, wenn ein Benutzer auf eine bestimmte URL tippt, die zu einer von euch kontrollierten Domain gehört. Wenn die App installiert ist, öffnet der Link die App. Wenn nicht, öffnet sich derselbe Link einfach im Browser. Dieses Verhalten wird zu einem leistungsstarken Werkzeug für Werbung, E-Mails, die direkte Navigation in tiefere App-Bereiche, Onboarding-Flows und die allgemeine Benutzererfahrung.

Trotz der Nahtlosigkeit, die Benutzer erleben, erfordert die Einrichtung eine sorgfältige Konfiguration sowohl in der iOS-App als auch im Backend. Für Entwickler, die zum ersten Mal damit konfrontiert werden, kann der Einrichtungsprozess überraschend streng und leicht fehlkonfigurierbar sein.

Dieser Beitrag behandelt die erforderlichen Schritte, damit Universal Links unter iOS funktionieren:

  • Konfigurieren der iOS-App zur Verarbeitung eingehender Links.
  • Erstellen der Apple App Site Association (AASA)-Datei.
  • Hosten der AASA-Datei unter dem Pfad /.well-known.

Am Ende werdet ihr ein besseres Verständnis davon haben, wie man eine Anwendung zur Unterstützung von Universal Links einrichtet, was euch einen Vorsprung verschafft, wenn ihr plant, dieses Feature in eure Software zu integrieren.

Der erste Schritt besteht darin sicherzustellen, dass eure iOS-App weiß, wie sie reagieren soll, wenn jemand auf einen Universal Link tippt. Obwohl Universal Links im Web ihren Ursprung haben, leitet iOS sie über den App Delegate an die App weiter. Damit wird der App Delegate zum zentralen Punkt, an dem eure App entscheidet, wie eine eingehende URL behandelt werden soll. Zu den Optionen gehören das Öffnen eines bestimmten Screens, das Auslösen von Navigation oder das Weiterleiten von Parametern tiefer in die React-Native-Schicht.

Wenn ein Universal Link aktiviert wird, ruft iOS zwei native Methoden auf:

  • scene(_:continue:) for apps using the modern Scenes API
  • application(_:continue:restorationHandler:) for older setups

Mindestens eine davon muss implementiert werden, um die empfangene URL an den Code weiterzuleiten.

Hier ist ein vereinfachtes Beispiel mit dem SceneDelegate, der in React-Native-Projekten üblich ist:

// SceneDelegate.swift
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let incomingURL = userActivity.webpageURL else { return }
    // Pass the link to React Native
    RCTLinkingManager.application(UIApplication.shared,
                                  open: incomingURL,
                                  options: [:])
}

Wenn das Projekt noch auf den AppDelegate angewiesen ist, sieht die entsprechende Version wie folgt aus:

// AppDelegate.m (Objective-C)
- (BOOL)application:(UIApplication *)application
            continueUserActivity:(NSUserActivity *)userActivity
              restorationHandler:(void (^)(NSArray *))restorationHandler
{
  return [RCTLinkingManager application:application
                      continueUserActivity:userActivity
                        restorationHandler:restorationHandler];
}

Diese Implementierung stellt sicher, dass die React-Native-App den Link über die Linking-API empfängt, wo ihr darauf lauschen könnt:

import { Linking } from 'react-native';
Linking.addEventListener('url', ({ url }) => {
  // Handle navigation here
});

An diesem Punkt ist die native Schicht bereit – eure App kann nun Universal Links empfangen. Als Nächstes bereiten wir die Website-Seite des Handshakes vor, indem wir die AASA-Datei erstellen, damit iOS weiß, dass eure App berechtigt ist, diese Links zu verarbeiten.

Erstellen der Apple App Site Association (AASA)-Datei

Diagram showing a user clicking a Universal Link on an iOS phone, leading to an AASA file, which determines if the link opens in a React Native app, opens in Safari, or redirects to a website.

Nachdem die App Universal Links empfangen kann, besteht der nächste Schritt darin, iOS zu überzeugen, dass eure Domain berechtigt ist, eure App zu öffnen. Hier kommt die AASA-Datei ins Spiel.

Grob gesagt ist die AASA-Datei ein JSON-Dokument auf eurer Website, das iOS mitteilt:

  • welche App(s) zu eurer Domain gehören
  • welche URL-Pfade diese Apps verarbeiten dürfen
  • ob ihr Features wie Shared Web Credentials oder Universal Links unterstützt

Wenn ein Benutzer eure App installiert, ruft iOS die Datei automatisch von eurer Domain ab. Wenn die Datei gültig, korrekt formatiert und am erwarteten Ort platziert ist, registriert iOS eure App als Handler für alle übereinstimmenden Pfade.

Struktur der AASA-Datei

Im Folgenden ist die minimale Struktur, die iOS in einer apple-app-site-association-Datei erwartet, und wie jeder Abschnitt die Link-Verarbeitung beeinflusst:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "paths": ["/products/*", "/profile/*"]
      }
    ]
  }
}

Die Pfade sind natürlich die Pfade der App, die das Universal-Link-Verhalten auslösen sollen.

Die appID setzt sich zusammen aus: <Application Identifier Prefix>.<Bundle Identifier>. Der Application Identifier Prefix ist im Apple Developer Portal unter „Membership” oder in Xcode sichtbar, indem man das Projekt → Signing & Capabilities → Team auswählt. Der Bundle Identifier stammt aus demselben Xcode-Bereich und identifiziert eure App eindeutig (z. B. com.example.app).

A screenshot of Xcode’s project settings showing the Bundle Identifier field set to com.example.app under the Identity section, for an iPad app with minimum iOS deployment version 18.0 and support for Universal Links.

Das Associated Domains Entitlement zur App hinzufügen

iOS validiert die AASA-Datei nur, wenn eure App die zugehörige Domain explizit deklariert. Dazu aktiviert ihr in Xcode die Capability „Associated Domains“ und fügt einen Eintrag wie den folgenden hinzu:

applinks:<your-domain>.com

Dadurch wird eure App mit der Domain verknüpft, sodass iOS weiß, wo die AASA-Datei abgerufen und verifiziert werden soll.

Xcode Signing & Capabilities tab displaying iOS app settings, including Bundle Identifier, Provisioning Profile, Team, and Signing Certificate. The Associated Domains section features three Universal Links with applinks.*.example.com entries listed—ideal for React Native app configurations.

Hosten der AASA-Datei unter dem Pfad /.well-known

A browser shows an AASA file being transferred from a website to an iPhone with the Apple logo, illustrating how Universal Links connect directly through iOS devices. Text reads iOS devices hosted.

Damit iOS eure Universal Links erkennt, muss die AASA-Datei öffentlich zugänglich sein unter:

https://eure-domain.com/.well-known/apple-app-site-association

iOS ruft diese Datei automatisch bei der App-Installation ab, um die Domain-App-Zuordnung zu überprüfen. Das Hosten unter einem anderen Pfad oder hinter Weiterleitungen führt dazu, dass die Überprüfung fehlschlägt. Ein korrektes Hosting ist daher entscheidend für das Funktionieren von Universal Links.

Die Datei muss direkt bereitgestellt werden, ohne HTTP-Weiterleitungen (einschließlich 301, 302 oder 307). iOS folgt keinen Weiterleitungen beim Versuch, die AASA-Datei abzurufen, und selbst eine Weiterleitung von HTTP zu HTTPS kann dazu führen, dass die Überprüfung fehlschlägt.

Zusätzlich muss die Antwort mit dem korrekten Content-Type-Header bereitgestellt werden:

Content-Type: application/json

Die AASA-Datei muss über HTTPS zugänglich sein, gültiges JSON enthalten und als Rohdatei bereitgestellt werden – nicht in HTML eingebettet, komprimiert oder dynamisch generiert auf eine Weise, die die Antwort-Header verändert.

Da die Anforderungen streng sind und je nach Hosting-Anbieter oder Backend-Setup variieren (z. B. Nginx, Apache, S3, Firebase Hosting oder ein benutzerdefinierter Server), ist es leicht, diesen Schritt falsch zu machen – selbst wenn die Datei selbst korrekt ist.

In späteren Beiträgen werden wir konkrete, schrittweise Beispiele für das korrekte Hosten der AASA-Datei auf verschiedenen Infrastrukturen durchgehen und erklären, wie häufige Probleme behoben werden, wenn iOS eure Universal Links nicht erkennt.

Fazit

Obwohl Universal Links Benutzer nahtlos vom Web in eure App überführen können, funktionieren sie nur, wenn alle notwendigen Komponenten korrekt konfiguriert sind. Sobald App und Domain ordnungsgemäß verknüpft sind, kann iOS zuverlässig bestimmen, ob beim Klicken auf einen Link die App geöffnet oder auf den Browser zurückgegriffen werden soll.

Dieser Beitrag konzentriert sich auf die Kernkonzepte, die zum Verständnis der Funktionsweise von Universal Links erforderlich sind. Folgebeiträge werden konkrete Einrichtungsbeispiele liefern und häufige Fehler hervorheben, die bei der Implementierung vermieden werden sollten.