Flutter: Supporting "universal links" on iOS

I recently added deep link functionality to our TaleMe app.

Deep links are links that redirect the user to a specific page of the app when it is installed on their device.

Thanks to Flutter and its documentation, you can quickly see how to set them up. However, after several unsuccessful attempts and some wasted hours, I'm sharing a checklist here to save you time.

1/ Verify that the correct configurations have been added to the ios/Runner/Info.plist file

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  ...
  <key>FlutterDeepLinkingEnabled</key>
  <true/>
  ...
</dict>
</plist>

2/ Verify that the correct configurations have been added to the ios/Runner/Runner.entitlements file

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.apple.developer.associated-domains</key>
  <array>
    <string>applinks:monsite.com</string>
  </array>
</dict>
</plist>

⚠ Here, the domain monsite.com is the one being targeted, not its subdomains. If you have multiple domains, you can add them to the array, or use a wildcard applinks:*.monsite.com.

3/ Add the apple-site-association file

a) Use the most recent format! It turns out there are several formats of the apple-site-association file, and it's easy to get confused. I recommend copying and pasting from Apple's documentation, not from Stack Overflow or elsewhere.

• Apple documentation on supporting associated domains

b) Add the file in the right place: it must be accessible at this address: https://monsite.com/.well-known/apple-app-site-association. It seems that previously it was possible to leave it at the root of the site, but this is no longer mentioned in Apple's documentation... be cautious.

c) The file must be accessible over HTTPS and not be password-protected. It must also return the MIME type application/json. No redirects either.

4/ Verify that the apple-site-association file is accessible and recognized by Apple's CDN

Usually, Apple's CDN updates its information within 12 to 24 hours (but it can take longer).

You can use the following services:

• Branch AASA validator
• Yurl checker
• Apple technical note TN3155 - Debugging Universal Links

There are also some command-line commands to verify that the file is accessible:

  sudo swcutil dl -d monsite.com

5/ Test deep links

You can use this command to check that deep links are working properly:

  swcutil verify -d monsite.com -j ./path/to/apple-app-site-association [-u <URL>]

If you want to test your app you can use a simulator, then open a terminal to run this command:

  xcrun simctl openurl booted https://monsite.com/

The -u option allows you to specify the URL to test for the "match", in case you plan to filter which URLs should be redirected to your application.

Keep in mind that Apple's CDN can take time to update its information, and that deep links will not work if the app is not installed on the device.

You can also bypass Apple's CDN by modifying the ios/Runner/Runner.entitlements file:

applinks:monsite.com -> applinks:monsite.com?mode=developer

It didn't work for me, but it may be useful for you. You will also need to remove the developer mode before publishing the app.

And there you go! I hope this article was helpful to you! For Android, the process is quite different; I'll explore that in another article.