Deep Linking

Mobile Deep Links

Mobile deep links are special links on Web pages. They allow users to seamlessly switch into an installed application and trigger an action there. These deep links do not start with "http://" or "https://" but use a custom schema that can be freely chosen. For instance, it is possible to register an app to react to all links that start with "i5://". To ensure that the schema is unique, it is also possible to use reverse DNS notation, e.g. by writing "com.i5.Toolkit://".

More information on mobile deep links can be found here.

Use Case

The mobile deep links can be used to quickly access functionalities and services of installed applications. As an example, it is possible to tell the app to immediately load certain content or open a specific editor. A common deep link that can be found on the Web is the "mailto://" schema. If a user clicks the link, the mail client opens and automatically sets up a new mail where the receiver mail is automatically filled based on the link's content.

Supported Platforms

Deep links can only be registered for installed apps, e.g. on the following platforms:

Universal Windows Platform
Android
iOS

In particular, this feature does not supported testing in the Unity editor and on Standalone builds.

Usage

Follow these steps to integrate deep linking into your application:

In the Player Settings of your target platform, register the deep link scheme. More information can be found in Unity's documentation. You only need to follow the the instructions for your specific platform - the code examples are already handled by the given deep linking service.

Add a DeepLinkingService to your application, e.g. in a service bootstrapper.

DeepLinkingService service = new DeepLinkingService();
ServiceManager.RegisterService(service);

Add the DeepLinkAttribute to a method that should react to a deep link. When specifying the attribute, set the path to which it should react, e.g. "myDeepLink" if it should react to deep links like "i5://myDeepLink". The path is case-insensitive.
```
[DeepLink("myPath")]
public void Foo()
{ ... }
```
Important: To optimize performance, the DeepLinkingService does not scan the entire code for the methods with attributes. Instead, you need to add the class that contains the method manually using AddDeepLinkListener(Object).
```
service.AddDeepLinkListener(myClass);
```
To clean up, you can remove a listener class again using RemoveDeepLinkListener(Object)

Filtering Schemes

Optionally, you can also enter a scheme in the attribute's definition. If you do not add a scheme, all schemes are recognized which have the same path. For instance, [DeepLink("myDeepLink")] will be activated by any URL with the path myDeepLink, e.g. "i5://myDeepLink" but also "rwth://myDeepLink", etc. If the scheme is specified, only links which match this exact scheme target the given method. So, [DeepLink(scheme: "i5", path: "myDeepLink")] will only be called by the deep link "i5://myDeepLink" but e.g. not by "rwth://myDeepLink".

Extracting Further Information About the Received Deep Link

Methods that are marked with the DeepLinkAttribute can either take no arguments or one argument of type DeepLinkArgs. In this argument helper class, the full deep link can be found, as well as information about the schema, and parameters that were specified with the deep link.

Passing Parameters to the Application Using Deep Links

You can specify parameters in the deep link, e.g. "i5://withParams?value=123&secondvalue=helloWorld". They are available as a Dictionary<TKey,TValue> in the Parameters.

Recommendations

It is possible to mark any method in the code as a deep link receiver. However, you should only choose methods that are available after the automatic initialization procedure of your application. Moreover, the methods should stay available during the entire lifetime of the application.

This is due to the fact that the deep links should be state-free. No matter where in the application you are, a received deep link should always have the same effect. Moreover, when launching the application via a deep link, it should directly react to the deep link's content without user intervention. It would be confusing for users if they start via a deep link, get into the normal main menu, can interact with it and e.g. only if they open the settings menu, the deep link is suddenly recognized and has an effect.

To keep the architecture clean, it is recommended to create few API-definition classes that bundle deep link paths instead of scattering them throughout the application's code. These API-definition classes should be available from the beginning of the application and should persist until the application is terminated.

Example Scene

There is an example scene that demonstrates the usage of the deep links. It can only be tested in UWP, Android and iOS builds.

Follow these steps to set up the example:

Open the example scene "Deep Linking Demo".
Go to "File > Build Settings" and click the button "Add open scenes". Make sure that the "Deep Linking Demo" scene has index 0 in the build - it needs to be at the top of the list. If it is not at the top, you can drag and drop the scene entry so that it is the first one in the list.
In the build settings dialog, select either Universal Windows Platform (UWP), Android or iOS as the target platform and click the "Switch Platform" button. If you want to test on your development Windows PC, it is recommended to choose UWP because you can directly install the app on your PC and do not need an additional smartphone.
Register a deep link scheme for "i5" for your selected target platform, using the platform-specific instructions in Unity's docuemtation.
Build the application and install it on your device.
Click on the following link on the device on which you installed the application. The browser will ask you whether you want to open the link with your application.

i5://changeColor?color=#0000ff

A deep link receiver that responds to the changeColor path is attached to the cube. You can modify the value of the color parameter by copying the link and manually pasting it into the browser's address bar. Each time you hit enter, the browser redirects to the example application and the cube changes its color. This works both, if the app is not running in the background and with the already opened app.

If you hit F5, you can toggle the visibility of a fullscreen app console which prints the deep link that was received.