Configuring iOS

Universal Links allow iOS users to tap a link and open your app directly to the right content. When configured correctly, links on your Tolinku domain will open your app instead of Safari.

Prerequisites

Before you begin, you will need:

• An Apple Developer account (individual or organization)
• Your app’s Bundle ID (e.g. com.yourcompany.appname)
• Your Apple Team ID (a 10-character identifier)
• Your app published (or in development) with the Associated Domains entitlement

Configuration

Open App Config in the sidebar and expand the iOS Configuration section.

Apple Team ID

Your Team ID is a 10-character alphanumeric string assigned by Apple. You can find it at:

1. Sign in to developer.apple.com
2. Go to Account > Membership Details
3. Copy the Team ID shown on that page

Paste it into the Apple Team ID field.

Apple Bundle ID

The Bundle ID uniquely identifies your app. It is the same value you see in Xcode under your target’s General tab (e.g. com.fooddash.ios).

Tip

You can use the search feature in the iOS section to look up your app by name on the App Store. If found, the Bundle ID and Store URL will be filled in automatically.

iOS App Store URL

Provide a direct link to your app on the App Store. This is used as a fallback when users do not have your app installed. The format is:

https://apps.apple.com/app/your-app-name/id1234567890

If you used the App Store search to find your app, this will already be filled in.

How Universal Links work

When you save your iOS configuration, Tolinku automatically generates and hosts an Apple App Site Association (AASA) file at:

https://your-domain.tolinku.com/.well-known/apple-app-site-association

This file tells iOS which paths on your domain should open your app. Tolinku keeps this file in sync with your routes, so you never need to edit it manually.

The AASA file contains your Team ID, Bundle ID, and the path patterns from your routes. Apple’s CDN caches this file and delivers it to iOS devices.

What happens when a user taps a link

1. iOS checks its cached copy of the AASA file for your domain
2. If the path matches a registered pattern, iOS opens your app
3. Your app receives the full URL and can navigate to the correct screen
4. If the app is not installed, the user is redirected to the App Store or your fallback URL

Setting up Associated Domains in Xcode

Your iOS app needs the Associated Domains entitlement to respond to Universal Links:

1. Open your project in Xcode

2. Select your app target, then go to Signing & Capabilities

3. Click + Capability and add Associated Domains

4. Add your Tolinku domain in the format:

   applinks:your-subdomain.tolinku.com

5. If you use a custom domain, add that too:

   applinks:links.yourapp.com

Note

Add one applinks: entry for each domain your links might use. If you have both a Tolinku subdomain and a custom domain, add both.

Handling links in your app

When your app opens via a Universal Link, you need to handle the incoming URL and route the user to the right screen.

SwiftUI

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    // Parse the URL path and navigate
                    handleDeepLink(url)
                }
        }
    }
}

UIKit

func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
        return false
    }
    // Parse the URL path and navigate
    return handleDeepLink(url)
}

For a full integration guide with the Tolinku SDK (which adds deferred deep linking and attribution), see the iOS SDK documentation.

Testing Universal Links

To verify your setup:

1. Check the AASA file: Open https://your-domain.tolinku.com/.well-known/apple-app-site-association in a browser. You should see a JSON file with your Team ID and Bundle ID.

2. Test on a real device: Universal Links do not work in the iOS Simulator. Install your app on a physical device.

3. Use Notes or Messages: Type your link into the Notes app, then long-press it. You should see an “Open in [Your App]” option.

4. Check Apple’s CDN: Apple caches AASA files. After making changes, it can take up to 24 hours for the cache to refresh. You can check the status at Apple’s App Search API Validation.

Caution

Universal Links do not work when typed directly into Safari’s address bar. They only trigger when a user taps a link from another app (Messages, Mail, Notes, social media, etc.) or from a web page.

Troubleshooting

Issue	Solution
Links open in Safari instead of the app	Check that Associated Domains is set up correctly in Xcode and that the AASA file is accessible
AASA file returns 404	Make sure your iOS settings are saved and your domain is properly configured
Links work on some devices but not others	Apple caches the AASA file. Wait 24 hours after changes, or reinstall the app
”Open in” banner does not appear	The user may have previously chosen “Open in Safari” for your domain. They can reset this in Settings > Safari

For more help, see Troubleshooting Universal Links.

Configuring Android Set up Android App Links for your Appspace.