> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://amer.developers.trustly.com/llms.txt. > For full documentation content, see https://amer.developers.trustly.com/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://amer.developers.trustly.com/_mcp/server. # Set up Universal Links Universal Links are a Beta feature. Functionality is subject to change as Trustly continues to make improvements. To enable this feature or request assistance, contact [Trustly Support](mailto:us.support@trustly.com). [Universal Links](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content/) 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: | Feature | Universal Links | Custom URL Schemes | | :-------------- | :-------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | | User Experience | Opens the app directly. If the app is missing, it opens the web URL. | If the app is missing, the user often sees an error such as **Safari cannot open the page**. | | Security | Links are associated with your domain, preventing other apps from hijacking them. | Multiple apps can claim the same scheme, leading to collisions. | | Protocol | Uses standard web URLs HTTP/HTTPS. | Requires non-standard schemes. For example, `myapp://`. | | Support | The standard for iOS deep linking. | No longer recommended for primary deep linking. | ### 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. ```json { "applinks": { "apps": [ "ABCDE12345.com.yourcompany.YourApp" ], "details": [ { "appID": "ABCDE12345.com.yourcompany.YourApp", "paths": [ "/products/*", "/profile", "NOT /help/*", "*" ] } ] } } ``` #### Configuration reference The following table describes the keys used to configure the `apple-app-site-association` file. | Key | Description | | :------ | :----------------------------------------------------------------------------------------------------------------------------------- | | `apps` | An array of application identifiers. While required, the detailed matching is handled in the `details` section. | | `appID` | Your app's unique identifier in the format `.`. You can find your Team ID in the Apple Developer Portal. | | `paths` | An array of strings specifying which URL paths the app should handle. | #### 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`): ```bash 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](https://developer.apple.com/documentation/xcode/supporting-associated-domains) for more details. Adding this capability automatically modifies your app's entitlements file (typically `YourApp.entitlements`) by inserting the `com.apple.developer.associated-domains` key. 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. ```text 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. ```swift title="Scene Delegate (iOS 13+)" import UIKit class SceneDelegate: UIResponder, UIWindowSceneDelegate { // This method is called when the app is running or suspended // and a Universal Link is tapped. func scene(_ scene: UIScene, continue userActivity: NSUserActivity) { // 1. Validate the activity type and extract the URL guard userActivity.activityType == NSUserActivityTypeBrowsingWeb, let incomingURL = userActivity.webpageURL else { return } print("Incoming Universal Link URL: \(incomingURL)") // 2. Parse the URL path // Example URL: https://yourdomain.com/products/12345 let pathComponents = incomingURL.pathComponents // 3. Route the user to the correct content if let index = pathComponents.firstIndex(of: "products"), index + 1 < pathComponents.count { let productID = pathComponents[index + 1] handleProductDeepLink(id: productID) } } func handleProductDeepLink(id: String) { // Implement your navigation logic here print("Navigating to product view for ID: \(id)") } } ``` ```swift title="App Delegate (Legacy)" import UIKit @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { // This method is called to handle a Universal Link activation. func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool { // 1. Validate the activity type and extract the URL guard userActivity.activityType == NSUserActivityTypeBrowsingWeb, let incomingURL = userActivity.webpageURL else { return false } print("Incoming Universal Link URL: \(incomingURL)") // 2. Handle the routing (Same logic as SceneDelegate) // ... Implement your routing logic here ... return true } } ``` ### 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. Any settings passed to the `establishData` object in your code override the default configurations stored in your Trustly account profile. 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/`).