Supporting universal links in a SwiftUI application

Universal Links allow iOS apps to open specific pages in response to standard web URLs. When users tap a universal link, they are redirected to a specific part of an iOS application if installed. If the app is not installed, the link opens in a browser, allowing the connected website to handle it.

In this article, we'll explore how to set up Universal Links in a SwiftUI application. We’ll go through the configuration steps required on the web and within Xcode, as well as how to handle Universal Link navigation in SwiftUI.

Let's jump in.

Architecture & Design Patterns for iOS

This book is a practical guide to essential architectural principles and design patterns for iOS development. It covers strategies for building maintainable apps with Swift and SwiftUI, including dependency injection, navigation, common patterns, and modularization.

LEARN MORE

To support universal links, the following steps are required:

1. Creating and configuring an Apple App Site Association (AASA) file.
2. Adding the AASA file to the related website.
3. Adding an associated domains entitlement to the iOS app.
4. Implement code to handle Universal Links in the app.
5. Test the universal links implementation.

Let’s dive into each step in detail.

1. Creating and configuring an Apple App Site Association (AASA) file

The Apple App Site Association file is a file called apple-app-site-association without an extension in JSON format. Let's look at an example for universal links support:

{
   "applinks":{
      "details":[
         {
            "appIDs":[
               "APPIDPREFIX.com.tanaschita.exampleApp"
            ],
            "components":[
               {
                   "/": "birds",
               },
               {
                   "?": "status",
               }
            ]
         }
      ]
   }
}

In this file:

2. appIDs specifies which app can handle the links, in the format <YOUR_TEAM_ID>.<bundleID>.
3. components specifies URL patterns that the app can handle.

In the example, the app will handle any URL that matches the /birds path and uses a query with status as a key, for example:

https://example.com/birds?status=active

If no path or pattern is specified, it defaults to *, matching all URLs under the domain.

2. Adding the AASA file to the related website

The apple-app-site-association file should be hosted at:

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

Make sure the file is accessible without any redirects, as iOS will attempt to download it directly from this location.

3. Adding an associated domains entitlement to the iOS app

1. In Xcode, open your project’s target settings.
2. Under the Signing & Capabilities tab, click the + Capability button.
3. Add the Associated Domains capability.

In the Associated Domains section, we can add the domains configured in the AASA file. The format is applinks:yourdomain.com. For example:

applinks:example.com

This tells iOS that our app can handle Universal Links for https://example.com.

Note: To enable the Associated Domains entitlement, our app must be signed with a provisioning profile that supports this capability. A paid Apple Developer Program membership is required to configure entitlements and provisioning profiles.

4. Implement code to handle Universal Links in the app.

SwiftUI provides the onOpenURL method which is called when a user taps on a universal link our app supports.

Here’s how to set up .onOpenURL in a SwiftUI view:

ContentView()
.onOpenURL { url in
    // change state based on the provided URL
}

The url parameter provides access to the URL’s components, including path and query, enabling us to navigate to the appropriate screen within the app based on the link.

To implement routing, check out this article on how to use NavigationPath for routing in SwiftUI.

5. Testing universal links

Universal Links only work on a physical device, not the simulator. To test a universal link, we can save it another app, for example in a notes app, and tap on it from there to check if the app opens and routes as planned.