iOS Universal Links Setup Guide

How universal links behave

Apple describes the core behavior in one paragraph: "When users tap or click a universal link, the system redirects the link directly to your app without routing through the person's default web browser or your website." Because universal links "are standard HTTP or HTTPS links, one URL works for both your website and your app. If the person hasn't installed your app, the system opens the URL in their default web browser, allowing your website to handle it."

The security comes from the file on your server. When someone installs the app, the system checks that file to confirm your website allows the app to open its URLs. In Apple's words, "Only you can store this file on your server, securing the association of your website and your app."

Set up the two-way association

1. Entitlement. In Xcode, open the target's Signing & Capabilities tab and add Associated Domains. Add one entry per domain in the form applinks:www.example.com. Apple asks for the subdomain and top-level domain only, with no path, query or trailing slash.
2. Association file. Serve apple-app-site-association at /.well-known/ on every domain in the entitlement, over https with a valid certificate and no redirects. The file format is in the Apple App Site Association (AASA) guide.
3. App handling. Update the app delegate or scene delegate to read the user activity the system passes in when a universal link opens the app, and route to the matching screen.

Subdomains are separate. Apple's note is explicit: if a site uses example.com, www.example.com and support.example.com, each needs its own entitlement entry and each must serve its own file. Apple's debugging note adds that applinks domains should not include port numbers.

Same-domain taps and typed addresses

Two behaviors surprise teams in testing, and both are deliberate. First, "When a user browses your website in Safari and taps a universal link in the same domain, the system opens that link in Safari, respecting the user's most likely intent to continue within the browser. If the user taps a universal link in a different domain, the system opens the link in your app." Apple's debugging note suggests a separate subdomain with its own file when a button on your site must open the app.

Second, a typed address never opens the app. Apple's note treats it as a direct visit; once the visitor is on your site, a banner can offer the app, as the install banner guide describes. People can also choose the browser for a domain by long-pressing a link, and that choice becomes the default for that domain on the device until they change it. All of these cases are compared in the note on links that open the browser.

Passing data in the link

Apple's example shows parameters in the query string, such as an album name and a photo index, so other apps can ask your app to open a specific item. A sportsbook might pass an event or market ID the same way. Two cautions apply. If your own app calls the open URL method on a universal link to your own website, Apple says "the link won't open in your app." And every parameter arrives from outside, so validate it against what the screen expects before you show account data. The Android equivalent of these routes is set up in Android App Links for casino and sportsbook apps.

Casino and sportsbook choices

• Use exclusions in the association file to keep licensing, terms, help and safer gambling pages on the web.
• If each licensed market has its own domain, each domain needs its own entitlement entry and file.
• The App Store requires real-money apps to be geo-restricted to licensed locations; a universal link to a market page should still lead to a web page a visitor elsewhere can read. See the store rules for real-money apps.

Testing

Apple's debugging note lists the tools: swcutil on a Mac to download and check the file, a sysdiagnose from a device to see whether the site approval reads approved, and Developer Mode on the device with Associated Domains Development turned on to run diagnostics on a full URL. The step-by-step checks are in the device test plan for deep links, and the implementation checklist tracks them for a release.