iOS 9 Universal Links (apple-app-site-association) blues


Update: 31st Oct, 2015 :jack_o_lantern::ghost:

The reason it wasn’t working is because it was working! (FML, etc.)

Yep. Let’s forget the fact that there’s no debug information whatsoever that tells you whether or not Universal Links registered correctly for your app…

It wasn’t working in Safari but did when I tested it with a link from Messages. Then, in Safari, if you long press a link, you get the option to open it in your app!

For iOS 9, you do not need to sign your apple-app-site-association file.

Nor should you serve it with the application/pkcs7-mime type (I am serving mine as application/json, because, well, it is.

(There is a mountain of misinformation and outdated information about this out there — the definitive source is the WWDC session on Seamless Linking to Your Apptranscript.)

If you do need to sign your apple-app-site-association file for iOS 8 compatibility:

There is an apple-app-site-association validator.

According to the validator, you have to sign the file (although the WWDC session and docs say that it is optional if you serve the file over HTTPS. I don’t know which is right. But I got it working with the validator anyway.)

Instructions for signing the file if you have a COMODO (NameCheap EssentialSSL Wildcard cert):

  1. Create your apple-appsite-association JSON file and call it apple-app-site-association-unsigned
  2. From the certificate bundle you received from NameCheap/COMODO, copy the STAR_<domain>.crt, and COMODORSAAddTrustCA.crt files to the same folder as the file you created in Step 1.
  3. Copy the private key for your site into a file called <domain>.key in the same folder as in the previous two steps.
  4. From the folder that all the files are in, in Terminal: cat apple-app-site-association-unsigned | openssl smime -sign -inkey <domain>.key -signer STAR_<domain>.crt -certfile COMODORSAAddTrustCA.crt -noattr -nodetach -outform DER > apple-app-site-association
  5. Test the created file with: cat apple-app-site-association | openssl smime -verify -inform DER -noverify — you should get the JSON back.

Upload the apple-app-site-association file to the root of your domain.

nginx mime-type setup

The file has to be served as mime type application/pkcs7-mime. Since we use an nginx reverse proxy, I set it up there:

location = /apple-app-site-association {
  proxy_hide_header Content-Type;
  add_header	Content-Type	"application/pkcs7-mime";

If you’re not using a proxy, you can set it up using something like:

location = apple-app-site-association {
  default_type application/pkcs7-mime

Useful links