Setup universal links in Xamarin iOS

I had to implement universal links functionality in Xamarin iOS this week and boy… that didn’t go well for what was a simple issue in retrospect.
This blog post will describe the integration in quick summary as there’s enough documentation to find on the web and it will also describe the problem I had.

How to add universal links to your Xamarin.iOS app?

  1. Upload the apple-app-site-association file to the root of your website or in the .well-known subdirectory and make sure it’s served via HTTPS
    1. If it’s served via HTTPS and you don’t need to target iOS8, don’t bother trying to sign the JSON file. A plain simple JSON file will do.
  2. Enable the “Associated Domains” functionality in the Apple Developer Center for your app and regenerate the provisioning profile
  3. Add the domain(s) you want to add universal linking for to your iOS Entitlements file in the section “Associated Domains”
    1. Make sure to add the applinks: prefix (ex.
  4. Implement the logic in the AppDelegate class

This is not very difficult, but if it doesn’t work right away, it’s somewhat difficult to debug.
The first thing I did was adding a link of the website I wanted to support in the Notes app on my iPhone so I could test the integration.
I then did a long push on the link until a little menu popped up with options and verified if there was an item available with “Open with [my-awesome-app]”.

But unfortunately, no success.
As described in this Medium blog post, you can verify if the correct calls are done on app install (or update) by looking at the logs of the device in Xcode.

But since iOS10, searching these logs is quite cumbersome as there’s a lot (I mean really a lot) of logs in Xcode.
A good tool to use instead is iOS Console.

Uninstall the app, fire up iOS Console, filter the list on association and install the app again.
When the app is installed, you should see that the app is requesting the apple-app-site-association file for the domains you configured in the Entitlements file (first in the .well-known directory and then in the root of the site).

A working example
A working example

But alas, this wasn’t the case in this app.
Because I rechecked everything and was quite certain everything was setup correctly, I created a new empty Xamarin.iOS project.

I configured everything as described above and… the requests to the site popped up in the logs!

OK, I was convinced now that I did everything by the book. But why wasn’t this working in the other project?
I tried removing some SDK’s because maybe there was an SDK interfering with it, but quickly found out this wasn’t the case.

Next step was to compare the configuration of the iOS project – which was causing me headaches – and the empty Xamarin.iOS project.
And I quickly noticed that there was a setting missing in the non-working project in the tab “iOS Bundle Signing”.


The location of the Entitlements file was not filled in.
I don’t know if previous versions of Xamarin Studio did not fill this in automagically or if someone removed it, but when selecting the file in the project, everything worked as expected.

One of those days I guess…

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s