📆 ⏱️ 5 min de lectura

If you already know what Universal Links are (if not, I recommend reading this article first), the next step is getting them to work in test environments. And it can be a real headache.

If you’ve tried configuring Universal Links and they don’t work in pre-production, preview, or similar, it’s probably due to one of these points:

  1. Incorrect location of the apple-app-site-association file
  2. Incorrect configuration of Associated Domains in Xcode
  3. Not using developer mode for testing
  4. Trying to test them from Safari (Apple’s special behavior)
  5. Having Chrome or another browser as default (iOS 14+)

📁 1. Incorrect location of the apple-app-site-association file

The problem with placing the file at the root of our project is that in test environments, usually private or behind a VPN, Apple doesn’t have access to that specific file path, so it won’t work.

Why does this happen?

In production, Apple saves the file to its own CDN and accesses it as the first option. But in private test environments or behind a VPN, Apple’s servers can’t access your domain, so they can’t download and save it to their CDN.

Keep in mind that Apple caches this information in its CDN when you install the app. If you change something, you need to delete and reinstall it, otherwise it will use the cached version it already has.

Solution: Place the file inside .well-known/

# Correct ✅
.well-known/apple-app-site-association

# Incorrect ❌
.well-known/apple-app-site-association.json
.well-known/apple-app-site-association.txt

⚠️ Critical: The file should NOT have a .json extension - it must be called exactly apple-app-site-association

Using .well-known ensures it will work equally in production and preview/pre-production.

💡 Tip: If you can’t change the file path right now, or need to wait for it to take effect, you can use Charles Proxy or Proxyman to intercept the call and serve your own file. You can see more details in this Stack Overflow discussion. Though I have to say, I couldn’t get it to work, but proxies and I don’t get along very well. 😅

⚙️ 2. Incorrect Associated Domains configuration in Xcode

In Xcode, you need to correctly configure Associated Domains in your app’s capabilities.

Steps to follow:

  1. Open your project in Xcode
  2. Select your target → Signing & Capabilities
  3. Click + Capability and add Associated Domains
  4. Add your domain with the format: applinks:your-domain.com with developer mode at the end ?mode=developer
applinks.my-app.com?mode=developer

⚠️ Important:

  • DON’T include https:// or http://
  • DON’T include the trailing /

🔧 3. Not using developer mode for testing

  1. Connect your iOS device to your Mac
  2. Open Xcode and go to Window → Devices and Simulators
  3. Select your device
  4. On your iOS device, go to Settings → General → VPN & Device Management
  5. Tap your developer profile and trust it
  6. Go to Settings → Developer (only appears after connecting to Xcode)
  7. Enable Associated Domains Development

⚠️ Critical: Without this mode enabled, iOS won’t verify Universal Links in development environments, even if everything is configured correctly.

🚨 4. Trying to test them from Safari

This is one of the most common mistakes. Safari has special behavior with Universal Links that can make them not work as expected.

Why does this happen?

Safari has its own logic for handling Universal Links. When you click a link inside Safari, it might open the web page instead of the app, even if the app is installed and correctly configured.

Solution: Use other apps to test Universal Links, like Notes, for example.

🌐 5. Having Chrome or another browser as default (iOS 14+)

Since iOS 14, Apple changed the behavior of Universal Links when you have a browser other than Safari as default.

What happens?

If you have Chrome, Firefox, or another browser as default, iOS may not open the app when you click a Universal Link, even if it’s correctly configured. As far as I know, there’s no solution other than using Safari as the default browser.

Final reflection

Universal Links in test environments require specific configuration that differs from production. Key points to remember:

Key points:

  • Forget the simulator, it only works on real iOS devices.
  • The file must be in .well-known/ - not at the domain root
  • Developer options only appear after connecting the device to Xcode
  • You must enable “Associated Domains Development” in device settings
  • Only works in development with development certificates + developer mode
  • DON’T use Safari for testing - use Messages, Notes, Mail, etc.
  • Safari must be the default browser
  • Configuration is cached - reinstall the app after changes

Have you had problems configuring Universal Links in test environments? I’d love to hear about your experience!

See you around 🫶

Useful resources

  • 📹 Official Apple video: What’s New in Universal Links (WWDC 2020) - Complete session where Apple explains Universal Links
  • 🔍 Well-Known.dev: Tool to search and verify .well-known/ files on websites, including apple-app-site-association. Lets you see the associated domains of any page and verify your configuration is correct
  • 📚 Official documentation: Supporting Universal Links - Complete Apple documentation