Set up Universal Links

Universal Links allow seamless integration between your website and your iOS application. By using standard HTTP or HTTPS links, you ensure that users are directed to specific content within your app without the need for browser redirects or system prompts.

Unlike custom URL schemes, Universal Links provide a reliable fallback strategy: if the application is not installed, the link functions as a standard web link and directs the user to your site. This guarantees the link resolves to the correct content, regardless of whether the app is installed.

Apple recommends Universal Links as the primary method for deep linking due to their security and usability advantages over legacy URL schemes.

The following table compares the features and behavior of Universal Links versus Custom URL Schemes:

Define the associated domains

To create Universal Links, you must create a JSON file named apple-app-site-association. This file defines the relationship between your website and your application. Host the file at one of the following locations:

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

Ensure your server meets the configuration requirements:

• The file must be served over HTTPS.
• The file must be served with the Content-Type header set to application/json.
• The filename must not have an extension (do not use .json).

The following example demonstrates how to configure your application identifier and supported paths.

1
{
2
  "applinks": {
3
    "apps": [
4
      "ABCDE12345.com.yourcompany.YourApp"
5
    ],
6
    "details": [
7
      {
8
        "appID": "ABCDE12345.com.yourcompany.YourApp",
9
        "paths": [
10
          "/products/*",
11
          "/profile",
12
          "NOT /help/*",
13
          "*"
14
        ]
15
      }
16
    ]
17
  }
18
}

Configuration reference

The following table describes the keys used to configure the apple-app-site-association file.

Path matching rules

Use the following patterns to control which links open your app:

• Specific Paths: Use explicit paths like /profile to match exact URLs.
• Wildcards (*): Use an asterisk to match dynamic content. For example, /products/* matches products/shoes and products/12345. The asterisk * in the code example directs all remaining traffic to the app. Remove this line if you only want specific paths to open the app.
• Exclusions (NOT): Prepend a path with NOT (including a space) to prevent the app from opening specific URLs. For example, NOT /help/* ensures your help documentation opens in the browser, not the app.

Verify your configuration

Run the following command in your terminal to confirm your server is returning the correct Content-Type (it must be application/json):

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

Add the Associated Domains entitlement

The Associated Domains entitlement identifies specific domains for which your app should intercept traffic. Adding this entitlement ensures iOS verifies your apple-app-site-association file and routes valid links to your app instead of the browser. See the Apple page on supporting associated domains for more details.

1. Open your project in Xcode and select your application target.
2. Go to the Signing & Capabilities tab.
3. Click + Capability and select Associated Domains.
4. In the Domains list, add the domains that host your apple-app-site-association file. You must prefix each domain with applinks:.

The following example demonstrates how to configure the entitlement for both your root domain and the www subdomain. Including both entries ensures that links resolve correctly regardless of whether the URL is accessed with or without the www prefix.

applinks:yourdomain.com
applinks:www.yourdomain.com

Handle incoming links

iOS delivers the Universal Link to your application using a specific delegate method. You must implement this handler to parse the incoming URL and navigate the user to the specific content they requested.

Depending on your app’s lifecycle configuration (iOS 13+ vs. Legacy), you will implement this in either the Scene Delegate or the App Delegate.

1
import UIKit
2
3
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
4
5
    // This method is called when the app is running or suspended
6
    // and a Universal Link is tapped.
7
    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
8
        
9
        // 1. Validate the activity type and extract the URL
10
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
11
              let incomingURL = userActivity.webpageURL else {
12
            return
13
        }
14
        
15
        print("Incoming Universal Link URL: \(incomingURL)")
16
        
17
        // 2. Parse the URL path
18
        // Example URL: https://yourdomain.com/products/12345
19
        let pathComponents = incomingURL.pathComponents
20
        
21
        // 3. Route the user to the correct content
22
        if let index = pathComponents.firstIndex(of: "products"),
23
           index + 1 < pathComponents.count {
24
            let productID = pathComponents[index + 1]
25
            handleProductDeepLink(id: productID)
26
        }
27
    }
28
    
29
    func handleProductDeepLink(id: String) {
30
        // Implement your navigation logic here
31
        print("Navigating to product view for ID: \(id)")
32
    }
33
}

Configure your deep link strategy (optional)

App Universal Links function without a fallback. However, Trustly recommends having a default deep link strategy configured for your merchant account. This ensures your application has a consistent fallback behavior if a strategy isn’t explicitly provided within the establishData object in your code.

Because this setup requires internal configuration, you’ll need to contact your Customer Success Manager (CSM) or Trustly Support to enable this fallback for your account.

When you submit your request, you must provide the following information:

• Deep link strategy: Specify universal-link.
• Universal Link: Provide your fully qualified domain (for example, https://yourdomain.com/).