Universal Links

Universal Links are iOS functionality enabling standard https URLs to open directly in applications rather than Safari. When users tap a Universal Link and the associated app is installed, iOS opens the app. If not installed, the link opens in Safari as a normal webpage. This seamless behavior improves user experience and engagement.

What Are Universal Links

Universal Links associate website URLs with iOS applications. The association is verified through an apple-app-site-association file hosted on the web domain. When iOS recognizes a Universal Link, it opens the associated app to handle the URL.

Unlike custom URL schemes (myapp://), Universal Links are standard https URLs. This means the same URL works whether the app is installed (opens app) or not (opens web). Links shared via messages or email work appropriately for all recipients.

Universal Links require both server-side configuration (apple-app-site-association) and client-side implementation (handling the URL in the app). Both components must be correctly configured for Universal Links to function.

How Universal Links Work

Server configuration provides the apple-app-site-association (AASA) file at the domain’s /.well-known/ directory. This JSON file specifies which URL paths should open in which applications.

Universal Links Configuration:

Server-Side (apple-app-site-association):
{
  "applinks": {
    "apps": [],
    "details": [{
      "appID": "TEAMID.com.example.app",
      "paths": [
        "/product/*",
        "/user/*",
        "NOT /settings",
        "*"
      ]
    }]
  }
}

Hosted at:
https://example.com/.well-known/apple-app-site-association
OR
https://example.com/apple-app-site-association

Requirements:
- Valid HTTPS with trusted certificate
- Content-Type: application/json
- No redirects to the file location
- File accessible without authentication

Client-Side (iOS App):
// Associated Domains capability
applinks:example.com

// SceneDelegate / AppDelegate
func scene(_ scene: UIScene,
           continue userActivity: NSUserActivity) {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else { return }
    // Handle URL navigation
}

Client implementation handles incoming Universal Links. The app must declare Associated Domains in capabilities and implement handlers for NSUserActivity with the browsing web activity type.

URL handling parses the incoming URL and navigates to appropriate content. The same URL structure used on the web should map to corresponding app screens.

Fallback behavior ensures links work even without the app. Web content at the same URLs provides the fallback experience. This web/app parity is a key Universal Links design principle.

Key Considerations

• Requires both server and app configuration
• AASA file must be properly hosted and accessible
• HTTPS required with valid certificate
• URL paths must be explicitly specified
• Web content should exist at linked URLs
• Testing requires actual devices (not simulator for full testing)

Common Questions

Why might Universal Links not work?

AASA file issues are common causes. File must be accessible without redirects, have correct Content-Type header, and contain valid JSON with correct team ID and bundle ID.

Associated Domains configuration must match AASA exactly. Domain in entitlements must match AASA hosting domain precisely.

First-tap behavior on iOS may open Safari. Long-pressing links and choosing Open in App helps verify functionality. Links opened from Safari address bar do not trigger Universal Links.

CDN and caching issues can serve stale AASA files. Ensure CDN configuration serves updated files correctly.

How do Universal Links relate to Android App Links?

Android App Links serve the same purpose for Android. Both enable https URLs to open associated apps. Implementation differs but concept is identical.

Cross-platform URL strategy should work for both. Same URL structure can have Universal Links (iOS) and App Links (Android) configuration.

Design systems targeting both platforms should document URL patterns that work across both Universal Links and App Links implementations.

How should apps handle Universal Link navigation?

Parse URL to determine destination. Extract path components and parameters to identify which screen to display.

Navigate within existing app state. If app is already running, navigate from current state. Do not reset entire app state.

Handle missing content gracefully. If linked content no longer exists or is inaccessible, show appropriate error rather than crashing.

Consider authentication requirements. If linked content requires login, authenticate then continue to destination.

Summary

Universal Links enable standard https URLs to open iOS applications seamlessly when installed, falling back to web when not. Configuration requires both server-side (AASA file) and client-side (Associated Domains, URL handling) components. Design systems should specify URL patterns for Universal Links that align with web content and Android App Links for consistent cross-platform deep linking.