IOTA deep linking: A proposal for standard deep links to increase IOTA wallet UX
This article explores how we can use deep linking to invoke specific functionality in the IOTA wallets in a standardized way.
What are deep links?
Deep links are nothing more than urls that enable you to go straight to a certain page by clicking on them. Like the one you used to get to this page. You probably did not go to medium.com first, before browsing to my article. Instead you clicked on a link that delivered you at this page directly.
Of course everyone is so used to this when browsing the web that they don’t even call it deep link any more. It’s just a link. But things are not so straight forward when you are using an app, like an IOTA wallet, and want to use a deep link to invoke a specific functionality of the app.
Initially I started out defining an url scheme specific for IOTA. I thought it would be really cool to be able to use an iota: url scheme to invoke specific wallet functionality, simply by specifying iota://cheque, or iota://donate for example. But when doing proof of concept on Android and iOS I quickly encountered some hurdles that made this iota: scheme infeasible to say the least.
I am not going to rehash every single problem here. There is an excellent article that gives an overview of all the problems and differences between systems and even OS versions. Suffice to say that the biggest hurdle is the fact that most apps, even browsers and email apps, won’t recognize the iota: urls as links, so they won’t highlight them as clickable. Well dang!
Universal Links to the rescue!
Luckily I also found workarounds, although less elegant. Since normal http: and https: urls are recognized by most apps (yes, even by browsers and email apps), I decided to us the concept of Universal Links. A universal link is simply a normal web url that, when clicked, will be intercepted by the operating system and passed to the app that registered the universal link instead of the browser. Furthermore, Apple in its infinite wisdom decided to implement a more secure version of Universal Links, requiring the support of the host of an existing web domain.
So now instead of using an iota:// prefix I will be using http://iotalias.link/ as prefix. Which will turn the examples from the previous paragraph into the following: http://iotalias.link/cheque and http://iotalias.link/donate. It’s only a slight modification but it makes a world of difference in ease of implementation. And it is still quite readable. And yes, I had to register the iotalias.link domain to be able to make it work on iOS.
Standardizing the link format
Now that we have a way that has been proven to work it is time to specify the format. Having a standard makes it a lot easier for different wallet implementations to respond correctly to the same deep links. We can identify a number of different actions, that operate on action-specific targets, and can have different kinds of optional parameters.
That means that an IOTA deep link has the following format:
An action is usually denoted by a verb. It should give a clear indication of what the action is supposed to do. Actions can have synonyms that perform the exact same action, but give a better indication to the reader of its intended purpose. Examples of such synonyms are ‘pay’ and ‘donate’. Of course a donation is a payment as well, but the intention behind it is much clearer this way:
A target is the main object involved in the context of the action. In the action examples above the target is obviously an IOTA alias. But other target examples could be: a 90-tryte IOTA address (including 9-tryte checksum), or an 88-tryte IOTA subseed (including a 7-tryte checksum), or an email address. It totally depends on the context of the action of course. Yet it is a good idea to standardize targets in such a way that different target types are easily distinguishable and/or parsable:
- An IOTA alias:
- An IOTA address:
A parameter is any (optional) data that could be of importance or interest to the action that is taken on the target. Parameters are even more dependent on the context, because they can not only be action-specific, but also specific to the target type. For a few good examples look at the examples above. Similar to action names and target types, we want to standardize the parameter names and types so that it becomes easy to predict what name to use for what purpose. Parameters can be optional, in which case a default value is assumed. Parameters can also be non-standard, and the wallet will attempt to store and display all of these as well.
Note that the wallet will usually show a dialog asking for any missing data or for confirmation by the user. This is good practice because the deep links that the user clicks could have been generated by a malicious entity. Therefore the default action of such a dialog should always be to cancel the action.
Any action that results in the transfer of funds from the user’s wallet should be subsequently followed by a confirmation dialog that asks the user to enter his PIN before continuing. Of course here the default action should be to cancel the dialog as well.
There can of course be certain actions that don’t need further user interaction. An example of such an action is redeeming an IOTA donation cheque (any funds coming in will gladly be taken :-).
Standardized target types
We will identify a number of target types that we will encounter regularly and fix their format and identifying features. All target types are made up of lowercase letters (a-z), digits (0–9), dash ( - ), dot ( . ), underscore ( _ ), at-sign ( @ ) and dollar-sign ( $ ). Any uppercase letters will be converted to lowercase before further processing.
An IOTA alias consisting of maximal 27 characters that identify the alias name, followed by a period, followed by minimum 8 starting tryte characters of the hash value of the alias. The latter makes the alias unique and unforgeable. More hash characters make the alias more secure but less easy to remember. See my IOTΛlias article for more details.
Private aliases use the full 27 alias name characters and are completely random tryte characters. They are generated and used between wallets and generally not for human consumption. Public aliases use a human-readable string of up to 27 characters.
An alias name can contain any of the target type characters, but keep in mind that any non-alphabetic characters will be ultimately be replaced by 9's, to make them a tryte value. Examples:
Private alias: rlhdvdtqjotx9dvogislpwxpibz.iwois9wh
Public alias: donations.medium.com.katshvbs
Public alias: eric.hop.klab9nxa
An IOTA address, encoded as the 81-tryte hash that is the actual address plus a 9-tryte checksum hash. An address can therefore be uniquely identified by the fact that it is always 90 tryte characters. Example:
An IOTA subseed, encoded as the 81-tryte hash that is the actual subseed plus a 7-tryte checksum hash. A subseed can therefore be uniquely identified by the fact that it is always 88 tryte characters. Example:
A standard email address. The email address can be uniquely identified by the fact that it always contains a single at-sign ( @ ) and of course otherwise obeys the rules for valid email addresses. Example:
We will show a number of predefined actions with possible synonyms and define what target types and parameters can be used with them.
Setting up IOTA deep links
Here’s how to set up IOTA deep links on mobile devices.
Android deep links
Select the activity you want to be activated by IOTA deep links. In the manifest for your app add the following to the <activity> tag:
In the onCreate method of your activity add the following code to receive the deep link url:
final Intent intent = getIntent();
final Uri uri= intent.getData();
final String url = intent.getDataString;
// parse either uri or url depending on your preferences
// to process the IOTA deep link
That’s all there is to it on Android! Be sure to have the activity that handles the deep link do the same kind of initializations that your landing activity would ordinarily perform. You could even make your landing activity do dual duty and have it process the IOTA deep links.
iOS deep links
To avoid doubling this article in size I will simply refer to this excellent article that explains the same hoops I had to jump to get it to work on iOS. It also contains a step by step guide on how to implement the deep links on iOS.
Don’t forget to replace his sample domains with iotalias.link. And of course you will need your own app id and everything. You will also need to contact me to add your app to the hosted json file on http//iotalias.link. The latter is a drag. I had hoped to make this a standard and fully decentralized, but Apple forced my hand in this.
By defining a standard for IOTA deep links I hope to increase user acceptance of IOTA by providing a way to simply click a link to invoke IOTA-specific app functionality.