Mar 22, 2017
Share
Picture this: you want to get started with Universal Links on iOS and the documentation at Apple has asked you to create and host an AASA file. So, what is an AASA file?
The AASA (short for apple-app-site-association) is a file that lives on your website and associates your website domain with your native app. In other words, it’s a safe way to prove domain ownership to iOS. With URI schemes, which were the standard way for opening apps on iOS until iOS 9, app developers could register any URI scheme of their liking and iOS, without any verification, would respond to those URI schemes by opening apps. For example, if an indie developer registers the fb://
URI scheme for a test app, there was nothing to stop that, even thoughfb://
is used by the Facebook native app. The AASA file makes Universal Links unique and secure because there is no way for an indie developer to host an AASA file on the facebook.com domain.
Let’s look at some basics of the apple-app-site-association file that will help you in building and hosting one on your domain.
The AASA file contains a JSON object with a list of apps and the URL paths on the domain that should be included or excluded as Universal Links. Here is a sample AASA file:
{ "applinks": { "apps": [], "details": [ { "appID": "3XXXXX9M83.io.branch-labs.Branchster", "paths": [ "NOT /e/*", "*", "/", “/archives/201?/* ] } ] } }
In the AASA JSON, each app specific domain contains a dictionary of appID and paths. Let’s look at what each key in the AASA JSON object is:
* Don’t know what your Team ID is? Head over to https://developer.apple.com/account and retrieve it from the Membership section.
** To retrieve the Bundle ID, head over to your Xcode project, select project and then the ‘General’ tab.
Once you are ready with your AASA file, you can now host it on your domain either at https://<<yourdomain>>/apple-app-site-association or at https://<<yourdomain>>/.well-known/apple-app-site-association.
While hosting the AASA file, please ensure that the AASA file:
application/json
MIME type.You can support multiple apps on the same domain. To do that, you’d need to add a new appID, path dictionary to the details array in the AASA file to look something like this:
{ "applinks": { "apps": [], "details": [ { "appID": "3XXXXX9M83.io.branch-labs.Branchster", "paths": [ "NOT /e/*", "*", "/", “/archives/201?/* ] }, { "appID": "3ZZZZZ9M94.io.branch-test.Branch", "paths": [ "NOT /e/*", "*", "/", “/archives/200?/* ] } ] } }
If two or more apps associate with the same content path on the website then the order of the appID, paths dictionary in the details array will determine which app will get precedence.
Each domain that the app needs to support has to have its own apple-app-site-association file. If the content served by domains is different, then the contents of the file will also be different to support the respective paths. Otherwise, the same AASA file can be used but it needs to be accessible on every supported domain. Also note that even though example.com and www.example.com might be serving the same content, you need to ensure that the AASA file is hosted on both these domains.
At Branch, we live and breathe deep links and have created an AASA validator to help you build your valid AASA file. You can find it here: https://branch.io/resources/aasa-validator/.
If you are using Branch links, you can bypass all the steps of building, validating, hosting and managing an AASA file by checking a single box on the Branch dashboard. We take care of all everything else under the hood for you.
If you aren’t using Branch links, now’s the time to request a Branch demo!
Share
To help you fuel cross-channel and cross-platform mobile growth, our team works hard to deliver the most current, relevant resources.