Universal Links (iOS)

Universal Links let iOS users tap a link and open your app directly, bypassing Safari. Tolinku automatically hosts the Apple App Site Association (AASA) file for your Appspace’s domain.

How it works

When a user taps a link to your Tolinku domain (e.g. https://myapp.tolinku.com/merchant/abc123):

1. iOS checks the AASA file at https://myapp.tolinku.com/.well-known/apple-app-site-association.
2. If the path matches, iOS opens your app and passes the URL to your AppDelegate or SwiftUI onOpenURL handler.
3. If the app is not installed, iOS opens the URL in Safari, where the user sees your landing page.

Setup

1. Configure your iOS settings in Tolinku.

   Go to Appspace Settings > iOS and enter:

   • Bundle ID: Your app’s bundle identifier (e.g. com.example.myapp)
   • Team ID: Your Apple Developer Team ID (found in your Apple Developer account under Membership)
   • App Store URL: Your app’s App Store listing URL

2. Enable Universal Links on your routes.

   For each route that should open in your app, enable the Universal Link toggle in the route settings. Only routes with this toggle enabled are included in the AASA file.

3. Add the Associated Domains entitlement in Xcode.

   In your Xcode project:

   • Select your app target
   • Go to Signing & Capabilities
   • Click + Capability and add Associated Domains
   • Add your domain: applinks:myapp.tolinku.com

   If you use a custom domain, add that too: applinks:links.myapp.com

4. Handle incoming links in your app.

   See the iOS SDK guide for code examples using Tolinku.handleUniversalLink().

AASA file format

Tolinku generates and serves the AASA file automatically at:

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

The file is also served at the root path (/apple-app-site-association) for compatibility.

Example output:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "A1B2C3D4E5.com.example.myapp",
        "paths": [
          "/merchant/*",
          "/product/*",
          "/invite"
        ]
      }
    ]
  }
}

The appID is constructed as <Team ID>.<Bundle ID>.

Path rules

• Static routes (no dynamic token) generate a path like /invite.
• Dynamic routes (with a :token parameter) generate a wildcard path like /merchant/*.
• If no routes have Universal Links enabled, the AASA file contains ["NOT /*"] which tells iOS not to open any paths.

Custom domains

If you use a custom domain (e.g. links.myapp.com), Tolinku serves the AASA file on that domain as well. Add both your Tolinku subdomain and your custom domain to the Associated Domains entitlement:

applinks:myapp.tolinku.com
applinks:links.myapp.com

Troubleshooting

Links open in Safari instead of your app:

• Verify the Associated Domains entitlement matches your domain exactly (no https:// prefix, no trailing slash).
• Check that your Bundle ID and Team ID are correct in Appspace Settings.
• Ensure the route has Universal Links enabled.
• iOS caches the AASA file. Try deleting and reinstalling the app, or wait up to 24 hours for the cache to refresh.
• On iOS 14+, AASA files are fetched via Apple’s CDN. Changes may take time to propagate.

Only some links open in the app:

• Check that Universal Links is enabled for the specific route. Only routes with the toggle on are included in the AASA file paths.

The AASA file returns an error:

• The AASA file is only generated when both the Bundle ID and Team ID are configured. Check your Appspace Settings.

Tip

Use Apple’s AASA Validator to verify your AASA file is correctly formatted and accessible.

Testing

To test Universal Links during development:

1. Install your app on a physical device (Universal Links do not work in the Simulator).
2. Open Notes or Messages and paste a link to your Tolinku domain.
3. Tap the link. If everything is configured correctly, your app should open.
4. Long-press the link to see the “Open in App” option in the context menu.