What's New in Universal Links

Welcome to our session on Universal Links. My name is Jonathan Grynspan and I work on the Core Frameworks Team at Apple.

Today, I'll be showing you how to use universal links in your app.

We introduced the universal links in iOS 9 as a great way to provide rich content both on the web and in your app.

Today, I'll be showing you the enhancements we've made to this feature.

Whether you've already adopted universal links in your iOS app or you're adding them to your macOS app, you will want to pay close attention to the changes I'll be discussing.

To begin, let's talk about what universal links are.

Universal links are HTTP or HTTPS URLs that Apple's operating systems recognize as pointing to resources either on the web or in your app.

This means that a single URL can represent that content, whether your users have your app installed or it just haven't downloaded it yet. They are great way to increase user engagement within your app.

Universal links are introduced in iOS 9 and tvOS 10. I'm happy to announce that we are introducing them to the Mac with macOS 10.15, whether you're using AppKit or UIKit. I'll tell you more about that in a moment.

Universal links are securely associated between your app and your website. Your app adopts an entitlement in Xcode that indicates which domains it can represent and your web server adopts a single JSON file that contains more details about what parts of its domain are representable in your app.

These two ways secure handshake ensures nobody can redirect your users into their apps instead of yours.

We recommend that where you are currently using custom URL schemes, you begin migrating to universal links today.

Custom URL schemes are inherently insecure and can be abused by malicious developers. New uses of custom URL schemes are highly discouraged.

Now that we know what universal links are, let's talk about how to build them. We'll start with your web server.

Your web server must have a valid HTTPS certificate. HTTP is not secure and cannot be used to validate an association between your app and your website. The root certificate used to sign your HTTPS certificate must be recognized by the operating system. Custom root certificates are not supported.

After generating your certificate and configuring your server, add your apple-app-site-association file. This is a JSON file. We'll discuss this format in a moment. When your app is installed on an Apple device, the operating system downloads this file to determine what services the server will let your app use. The system also periodically downloads updates for this file. Universal links are one of many services that may be included in this file.

This file should be located at HTTPS://your domain name/ .well-known/apple-app-site- association.

Other paths are deprecated.

In the past, we've discussed signing your apple-app-site-association file. This has never been a necessary step to support universal links so it is now deprecated.

Support for sign JSON files and JSON files at other paths will be removed in a future release. With that out of the way, let's take a look at your apple-app-site-association file.

If you already have one of these files on your web server this probably looks familiar, but we have a few changes to introduce today. At the top level is a dictionary whose keys are service types. For universal links, the key is applinks like you see here but other services are also available.

We'll be focusing solely on Universal Links. Under that top level key are the apps key and the details key. If you are targeting iOS 13, tvOS 13 and macOS 10.15, you do not need the apps key, so you can remove it.

If you are continuing to provide support for iOS 12, tvOS 12 or earlier, you'll still need it. For universal links, it should always be an empty array.

The details key contains an array of dictionaries, each of which represents a specific apps universal links configuration. In the past, we supported using a dictionary structure here instead of an array but that configuration is obsolete.

Under the details key is an appID key whose value is your app identifier. Your app identifier consists of an alphanumeric, 10 character prefix provided by Apple, a period, and your bundle identifier.

The prefix may or may not be equal to your team identifier. Check the developer portal to confirm your app identifier. If you have multiple apps with the same universal links configuration, you may not want to repeat the relevant JSON. If you are targeting this year's releases, you can reduce the size of this file by using the plural appIDs key. The value of that key is an array of app identifiers. If you need to support previous releases, you should keep using the singular appID key for each app.

Next is the paths key. This key contains an array of path patterns. Pattern matching is performed the same way it is in terminal. The asterisk is used to indicate multiple wildcard characters while the question mark matches just one character.

Beginning this year, we are replacing the paths key with the components key.

This key's value is an array of dictionaries, each of which contains zero or more URL components to pattern match against. As before, you can match against the URL's path component whose key is the forward slash. If you need to support previous releases, you can keep the paths key.

iOS 13, tvOS 13 and macOS 10.15 will ignore it if the components key is present. And now you can match against the URL's fragment component whose key is the hash mark and you can match the query component whose key is the question mark.

Now many, if not most URLs out there divide their query component up into key value pairs called query items. For the query component, you can specify a dictionary instead of a string as its value and pattern match individual query items. URLs may repeat query item names and the operating system will require that all instances of a given query item name match your pattern.

Query items with no value and absent query items are treated by the operating system as if they have a value equal to the empty string.

For a components dictionary to match a candidate URL, all the specified components must match. If you don't specify a component, the operating system's default behavior is to simply ignore that component. So if, for example, your app doesn't care about the fragment component of a URL, you don't need to specify it in this file. You may have sections of your website that are not able to be represented in your app yet. You can exclude such subsections by specifying the exclude key with a Boolean value of true.

This key has the same behavior as a not keyword that you used in the old paths key. That key word is not supported when using the component's dictionary.

Here we have a few examples of URLs that we need to pattern match. I'm working on a meal ordering app and I'm using universal links to bring users into my app from Safari. On the left, you can see some JSON from my server and on the right, you can see some URLs.

First, I want to match all the order forms on my website which are all located on a path where the first component can be anything. The second component is order and there are no further path components afterward.

This pattern will match a URL such as these two on the right. Time for lunch.

Next, I know a lot of my customers are going to want to put cheese on their tacos so I'm going to match any URL where the path starts with the path component taco and where a query item named cheese is specified. You'll notice that I specify a question mark and an asterisk as the pattern from the query items value. A pattern consisting of a single asterisk matches any string, including the empty string. And a missing query item has a value equivalent to the empty string. So to match against the string that's at least one character long, I specify a question mark and then any additional characters are matched by the asterisk.

That matches our third URL.

The fourth and fifth URLs look very similar but there's a good reason for that. My website also has lots of four-digit coupon codes that the app can handle. But if they start with a 1, I want them to stay in the browser. Because the operating system is going to look at the available patterns from top to bottom, we'll first mark coupon code starting with the one as excluded.

This tells the system to stop looking here if it finds a match but not to open the URL as a universal link. Then any other coupon will match the fourth and final components dictionary.

Before we move on to your app, let's discuss how to support an international audience.

URLs are always ASCII coded so component matching is done in ASCII as well.

If you need to match Unicode characters present and code them like you would in your URL.

Because components are present and coded, a Unicode character may be represented by more than one ASCII character, so keep that in mind when using the question mark in your patterns.

When you build your JSON, you may be tempted to provide country-specific patterns for every country you support. This increases the size of your JSON significantly.

If your pattern-matching is consistent between countries, you can reduce the traffic to and from your server by simplifying you JSON.

For instance, if you separate your content by two-letter country code, you need to only specify two question marks where you are previously using those country codes. Other more complex patterns like you see here can also be matched easily.

If you encounter a URL with an invalid country code or locale specific identifier, just treat it like the user's current locale.

Beginning in this release, the operating system will prioritize apple-app-site-association downloads based on where a user is most likely to browse. We'll still download them all when an app is installed but at different priorities. The top-level domains .com, .net, and .org, are high priority domains because they account for so much internet traffic worldwide.

Country code TLDs also known as ccTLDs and internationalized TLDs are also prioritized if they match the user's current locale settings. For example, the average user in China is more likely to visit a domain under a Chinese ccTLD than under, for example, an Italian or Russian ccTLD.

So now your server is ready to support universal links. Let's update your app. Open your project in Xcode and navigate to your project settings. Add the Associated Domains capability. This adds a new entitlement to the selected target. You can modify this entitlement directly from this view.

The value of this entitlement is an array of strings of the form service type: domain name. For universal links, the service type is applinks like it was in your apple-app-site-association file. The order of values in this array is ignored by the system.

Here, we declare that your app supports universal links for www.example.com. When your app is then installed, the operating system will visit www.example.com looking for the apple-app-site-association file we just discussed. If it's present and it contains information for these apps, app identifier, then the association is confirmed.

It's also possible to indicate wildcard support for subdomains of a given domain as shown here. In this case, the operating system will visit example.com. No www at this time.

Exact domains have higher priority during universal links look up than wildcard domains. In this case, that means when the system opens a URL at www.example.com, it will try to match patterns from that domain before the ones it got from the parent domain. Patterns from the parent domain will only be matched if no match was found at the fully qualified subdomain.

Finally, here's an example of an internationalized domain. Since URLs are always ASCII, your internationalized domain names will need to be encoded using Punycode. For more information on Punycode, see RFC 3492.

Now that your app declares support for certain domains, you'll need to actually parse the URLs as they come in.

Universal links are based on foundations and as user activity class and are handled by your app delegate.

You'll need a handler for incoming user activities. If you already support hand-off or other similar technologies, you may already have this method in your app delegate. This method returns a bool. Return true if you could successfully open the user activity and false if you couldn't.

If you're using UI scene, then a similar delegate method is available. If you're using AppKit, the signature of this method is almost identical. Just replace UI with NS like you see here.

We'll use UI application for the remainder of this session.

Next, we'll check that the activityType is NSUserActivityTypeBrowsingWeb. This helps distinguish universal links from other incoming user activities that your app may support.

Even if you don't support other activity types now, it's a good idea to check the activity type in case you need to support other types in the future. The activity type looks good. Let's grab the webpage URL from the user activity object. This will never be nil for a universal link and let's build a URL components draft from the URL. You should always parse URLs using URL components. Using regular expressions or manually parsing a URL string may leave you vulnerable to security issues.

We're past the guard statement so let's examine the contents of the URL. In this case I'm interested in the query items of the URL but you can use any of the URL's components to root activities at this point. If you support universal links from multiple domains, don't forget to check the host component.

Our code is complete and our server is configured but there are few differences when using universal links on macOS.

Universal links open in the browser by default on macOS. When they do, Safari will give the user the option to open them in your app. If the user selects this option, your links will continue to open in your app afterward.

Unlike iOS, macOS supports launching apps present on remote volumes. Apps on remote volumes cannot use universal links. They must be installed locally. If the user downloads your app from the App Store, the system will begin downloading apple-app-site-association files as soon as soon as your app is installed or updated.

If your app is developer ID-signed, the system will not begin these downloads until the user has launched your app at least once.

Because a universal link is backed by a secure association with an app identifier, only one copy of a given app will be able to handle universal links on a Mac. Typically, this will be the copy of the app present in slash applications. Keep that in mind anytime you need to test changes to your associated domains entitlement.

If you are on the other end of an operation and want to open a universal link, UIApplication and NSWorkspace and launch services will all automatically open them when available.

If you want to require opening a universal link in an app rather than the default browser, you can use UIApplication or NSWorkspace API as appropriate. If these open operations fail, it means that a universal link was not available for the supplied URL.

If you're developing a web browser from macOS, additional API will be made available to help you support universal links.

To help you make the best apps and to provide the best user experience, I've got a few final tips to share with you.

The first is to fail gracefully. It's possible you'll be provided with URLs that represent outdated, invalid, or nonexistent content. If you determine that a universal link can't be opened by your app, you can often open it in Safari View Controller. This keeps the user engaged in your app. If Safari View Controller is not an option, consider opening the URL in Safari, or at a minimum, prompting with details about the issue. Avoid sending the user to a blank screen.

If the user is visiting your website, use the Smart App Banner to provide a link either to the App Store or to your content. The Smart App Banner integrates seamlessly with Safari and looks great. And there's no JavaScript or custom URL schemes required to support it.

Finally, if you have feedback on how we can improve universal links, I would love to hear it. Please use the feedback assistant and let us know what we can do to make universal links even better. Thank you.