How to Fix App Universal Links Not Working

Universal Links are a powerful feature that allows iOS and Android apps to open specific content directly within an app rather than a web browser. They enhance user experience by providing seamless navigation from web links to app content. However, developers often encounter issues where Universal Links do not work as expected, leading to confusion and frustration for users. If you’re facing problems with Universal Links not functioning properly, this guide will help you troubleshoot and resolve common issues to ensure smooth linking between your website and mobile app.

How to Fix App Universal Links Not Working

1. Verify Your Apple App Site Association (AASA) File and Hosting

The Apple App Site Association (AASA) file is crucial for Universal Links on iOS. It informs Apple which URLs should open in your app. Ensuring this file is correctly configured and accessible is the first step towards fixing Universal Link issues.

• Correct Placement: Host the AASA file at the root of your website or at the `/.well-known/` directory. For example:
  • https://yourdomain.com/apple-app-site-association
  • https://yourdomain.com/.well-known/apple-app-site-association
• Content Format: The file must be a valid JSON without any extension or MIME type issues. It should look like:

  {
    "applinks": {
      "apps": [],
      "details": [
        {
          "appID": "TEAMID.BUNDLEID",
          "paths": ["/path/to/content/*", "/another/path"]
        }
      ]
    }
  }
  

• Correct MIME Type: Serve the file with the `application/json` MIME type.
• Consistency: Ensure the `appID` matches your app’s Team ID and Bundle ID.

Use online tools like AASA Validator to verify your AASA file’s correctness and accessibility.

2. Ensure Your App is Properly Configured to Handle Universal Links

Beyond hosting the AASA file, your app must be set up to accept and handle Universal Links.

• Update Your App’s Capabilities: In Xcode, enable the ‘Associated Domains’ capability and add your domain(s) with the `applinks:` prefix, e.g., `applinks:yourdomain.com`.
• Configure the Entitlements: Confirm that the `entitlements` file includes the correct associated domains entries.
• Implement URL Handling: In your app delegate, handle incoming URLs:

  func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
      if userActivity.activityType == NSUserActivityTypeBrowsingWeb,
         let url = userActivity.webpageURL {
          // Handle the URL accordingly
          return true
      }
      return false
  }
  

Testing your app with Universal Links after these configurations is essential to ensure proper handling.

3. Check Your Website’s Link and Path Configuration

The URLs you want to open in your app must match the paths specified in your AASA file. Inconsistent or incorrect URL paths can cause Universal Links to fallback to the browser instead of opening the app.

• Consistent URL Schemes: Ensure your website links follow the paths listed in the `paths` array of the AASA file.
• Use Exact or Wildcard Paths: Use wildcards (`*`) for variable segments if needed, e.g., `/products/*`.
• Test Specific Links: Manually test the links on real devices to verify they open the app as expected.

For example, if your AASA file includes `/profile/*`, ensure your website links follow that pattern, such as `https://yourdomain.com/profile/12345`.

4. Clear Cache and Reinstall the App

Sometimes, cached data or previous app states interfere with Universal Link functionality.

• Clear Safari Cache: On iOS, go to Settings > Safari > Clear History and Website Data.
• Reinstall Your App: Delete the app from your device and reinstall it to ensure fresh configuration.
• Restart Your Device: Restarting can sometimes resolve lingering cache issues.

This process ensures that your device recognizes the latest Universal Link configurations.

5. Confirm Your App is Linked to Your Website

Ensure that your app is correctly associated with your website and that the app’s bundle identifiers and team IDs are correctly configured to match the AASA file.

• Check App Store Connect Settings: Verify that your app’s associated domain is correctly specified and approved.
• Update the plist and entitlements properly.

Any mismatch here can prevent Universal Links from working correctly.

6. Troubleshoot Common Issues and Use Debugging Tools

When Universal Links still don’t work, use debugging tools and logs to identify the problem.

• on iOS: Use Xcode’s Console to check for errors related to Universal Links or entitlements.
• Use the `Universal Links Validator`: Tools like Branch or Firebase DebugView can help verify link handling.
• Check Web Server Logs: Ensure your server returns the correct headers and the AASA file is accessible.

Pay attention to any error messages or warnings indicating misconfigurations or connectivity issues.

7. Additional Tips for a Smooth Universal Link Experience

• Use HTTPS: Universal Links require secure HTTPS connections with valid SSL certificates.
• Implement Fallbacks: Always provide fallback web URLs in case the app isn’t installed or Universal Links fail.
• Test on Multiple Devices: Different devices may behave differently; test across various models and OS versions.
• Keep Your App and Server Updated: Regularly update your app and server configurations to accommodate platform updates.

8. Summary of Key Points

Fixing Universal Link issues involves a combination of correct configuration on your website, proper app setup, and thorough testing. Ensure your AASA file is correctly hosted and formatted, verify your app’s entitlements and URL handling code, and confirm that your website links match the configured paths. Clearing caches, reinstalling the app, and using debugging tools can help identify and resolve persistent problems. By following these steps, you can restore seamless linking between your website and app, enhancing user experience and engagement.