Why to watch out with Apple App Site Association file (AASA)

Recently we ran into a situation where we had to implement Universal Links (iOS) for our Xamarin Forms App. With universal Links the user clicks on a link, in let’s say the phone’s mail app, and the user gets redirected to a specific part of your app (deep linking) or, when a your app is not installed on the user’s device, the user gets redirected to a website.

For the app and the website to know of each other you need put a file in your well.known directory of your website. This file is also referred to as the Apple App Site Association file. In the iOS app on the other hand, in the Entitlemens file you specify which website domains your app supports with Universal Links.


Because we test our app phased in DTAP we included all of our three test websites in the Entitlement.plist file for T, A and P so in all phases we would be able to test our app universal links with their respective website.

What happened

When the app went live it turned out that when the app got updated/installed, the operating system of the iPhone tried to connect to all three websites ( of T, A and P) to retrieve the AASA file, twice. iOS will look in two different places (I believe this iOS version dependent) for the AASA file : in the well.known directory and in the root of the website. So this generates 6 network calls to websites.

The trouble we had was that the OS of the phone seemed to retry this very aggressively when the  AASA file could not be downloaded by the OS (i.e. some hardware returns a http 503 errorresponse). Since the T phase in DTAP is a website that is not reachable from outside a particular network, IOS can never succeed in downloading this AASA file. It sure tries a couple of times, even when the app is deleted from the phone! Obviously this generated too much traffic and we had to push a new modified version of the app to the App Store.

So why to watch out

  • Be aware that iOS will try to retrieve this AASA file more than once.
  • Be aware that the AASA file will only be downloaded by an app install/update. So if you want to make changes, you will have to push a new version of your app to the Store.
  • Be aware that the websites you use are reachable. So maybe it is good practice to use only the production website for this in your Entitlements.
  • Be aware that even when the app is not longer installed on a phone, the OS could still reach out to a website registered in the formerly installed app.

Leave a Reply

Your email address will not be published. Required fields are marked *