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:

http://iotalias.link/<action>/<target>?<parameters>

• Actions
  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:
  http://iotalias.link/pay/orders.amazon.com.gsidmetq?order=1234567&amount=42.37Mi&article=Amazon%20Kindle
  http://iotalias.link/donate/eric.medium.donations.ywkjdncr
• Targets
  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:
  http://iotalias.link/pay/orders.amazon.com.gsidmetq?order=1234567&amount=42.37Mi&article=Amazon%20Kindle
  - An IOTA address:
  http://iotalias.link/pay/sflyeypjkfkbrlhdvdtqjotxddvogislpwxpibzkom9ef gykjgkquygxekvkefmdqnygbnuvwsr9zvrbvilfkubmaq?amount=20Mi&reason=Birthday
• Parameters
  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.

• Alias
  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
• Address
  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:
  sflyeypjkfkbrlhdvdtqjotxddvogislpwxpibzkom9efgykjgkquygxekvke fmdqnygbnuvwsr9zvrbvilfkubmaq
• Subseed
  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:
  qjotxsflyeypjkfkbrlhdvdtddvogislpwxm9efgykjgkquygxekvkepibzko qnylfkubmgbfmdnuvwsr9zvrbvi
• Email
  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:
  eric@bugfreesoftware.be

Standardized actions

We will show a number of predefined actions with possible synonyms and define what target types and parameters can be used with them.

TBD

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:

<intent-filter>
 <data android:scheme="http"/>
 <data android:host="iotalias.link"/>
  <data android:pathPattern=".*"/>
  <action android:name="android.intent.action.VIEW"/>

  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
</intent-filter>

In the onCreate method of your activity add the following code to receive the deep link url:

final Intent intent = getIntent();
if ("android.intent.action.VIEW".equals(intent.getAction()))
{
  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.

Conclusion

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.

Part 1: Solving the IOTA donations problem by using IOTA cheques

Part 2: Solving the IOTA address aliasing problem by using IOTA cheques

Part 3: IOTΛlias, a wallet protocol for implementing public and private aliases

Part 4: IOTA cheques: sending iotas anywhere without requiring a receive address