Getting Started

Using the Plugin¶

The plugin uses a single event where you need to register in order to receive Deep Linking or Domain Association activations:

void Start()
{
    ImaginationOverflow.UniversalDeepLinking.DeepLinkManager.Instance.LinkActivated += Instance_LinkActivated;
}

private void Instance_LinkActivated(ImaginationOverflow.UniversalDeepLinking.LinkActivation s)
{
    //
    //  my activation code
    //
}

Never forget to remove your event registration when the GameObject where you registered it is destroyed:

void OnDestroy()
{
    ImaginationOverflow.UniversalDeepLinking.DeepLinkManager.Instance.LinkActivated -= Instance_LinkActivated;
}

The LinkActivated event will be triggered when your game is started or resumed by a Deep Link or Domain activation.

The LinkActivated event single argument LinkActivation contains the Uri that triggered the game activation, a string with the raw Query String and a Dictionary with the query string already processed:

public class LinkActivation
{
    public string Uri { get; private set; }

    public string RawQueryString { get; private set; }

    public Dictionary<string, string> QueryString { get; private set; }
}

Consider the following example:

private void Instance_LinkActivated(ImaginationOverflow.UniversalDeepLinking.LinkActivation linkActivation)
{
    var url = linkActivation.Uri;
    var querystring = linkActivation.RawQueryString;
    var qParameter = linkActivation.QueryString["q"];
}

If Sudoku Zenkai is activated with the following link:

https://sudokuzenkai.imaginationoverflow.com/puzzle?q=cMOiw5XDlsOXw5zDnMKl

The variables values would be:

url - https://sudokuzenkai.imaginationoverflow.com/puzzle?q=cMOiw5XDlsOXw5zDnMKl
querystring - q=cMOiw5XDlsOXw5zDnMKl
qParameter - cMOiw5XDlsOXw5zDnMKl

If you have the game installed on your device right now, instead of using the site URI you can use the deep linking URI instead:

sudokuzenkai://puzzle?q=cMOiw5XDlsOXw5zDnMKl

You should be seeing the exact puzzle as seen below.

Configuring the Plugin¶

The configuration interface is under Window -> ImaginationOverflow -> Universal DeepLink Configuration

On some platforms, the operating system asks the player what app she wishes to use after clicking a custom URI, the Display Name allows you to configure what name will the OS show on that occasion. The Steam App Id is for Steam only games, you can read about Steam integration on its section. The plugin allows you to configure the deep linking and domain association globally or per platform.

Note

The Standalone auto launcher features are exclusive to the Pro version of the plugin.

Global Configuration¶

If you are using the same custom URIs and Domains for every platform, you only need to setup it once and the plugin will automatically propagate all data to all platforms as you build for them.

To configure a Deep Link or a Domain Association you need to provide:

Scheme - it can be anything you wish, remember to check the Stores for other apps or games that are also using an URI you wish to adopt (when configuring for deep linking), for domain association it's usually http, if your site supports https add another entry to the list. Note: if you are thinking on redirecting a user to a deep link on the web, the scheme should always be configured in lower-case.
Host - this parameter is usually only used for domain association, here you should put the host of your website
Path - some platforms support which paths the application should be activated, but usually this is accomplished using other configuration files see Domain Association.

Per Platform Configuration¶

When you wish to override any configuration for a specific platform you can do that by clicking on the specific platform checkbox. After that, you just need to fill out the Deep Linking and Domain Association data or leave it empty if you do not wish to support these features for that specific platform. Note that by checking a platform none of the global configurations will be used for that specific platform.

In the example above, we've changed the Android Deep Linking scheme to sudokuzenkaidroid and disabled the Domain Association capability. The remaining platforms will continue to use the global configurations.

Testing¶

After your game is deployed to a device, you can test the integration simply by clicking on a configured URI on any app or website. As an example, you can send yourself a message (on any messaging app) or an email with the proper URI.

Editor¶

Warning

The editor debug window and direct deep link mock a link activation on the Unity editor, it bypasses any native platform integration and configuration.

[Pro Only] Direct deep link testing¶

In the plugin configuration window if you decide to enable Use for Unity debugging, the plugin will automatically redirect any configured deep link activations on your machine to the editor, enabling you to test the entire flow of information (for example OAuth flow) directly in the editor, without any further configuration. You can also use the run command in order to manually trigger deep links on your machine. The plugin will route them directly to your Unity Editor.

Warning

If you are working on Windows builds, the editor will replace the configuration of your already built game. To reconfigure the deep links simply open your game again.

Debug Window¶

We included a simple interface where you can test your deep linking activation without deploying, you can insert any valid and invalid URIs in order to test your integration.

When you press Debug, the LinkActivated will be triggered and your callback called if the application is running in the editor. To simplify iteration we also store the last called deep/web links in order to streamline testing.

On a Device¶

Testing in a device can be done in many different ways, via messaging apps, email apps, etc. We recommend to use our online Test Tool, to use it simply follow the steps:

On the device you wish to test open our Test Tool
Type the deep link or web link you wish to test on the text box
Click Create
Click on Test

After step 3 the website will update its url with the target test link information, making it easier to share test between team members or devices.

iOS/tvOS¶

Simulator¶

After your game is installed on a simulator, open a terminal and run the following command:

xcrun simctl openurl booted "[MY_URI_HERE]"

Examples

xcrun simctl openurl booted "sudokuzenkai://puzzle?q=cMOiw5XDlsOXw5zDnMKl"

xcrun simctl openurl booted "https://sudokuzenkai.imaginationoverflow.com/puzzle?q=cMOiw5XDlsOXw5zDnMKl"

Android¶

Open a terminal on your development machine, open a terminal (console or powershell) and run the command:

adb shell am start -W -a android.intent.action.VIEW -d "[MY_URI_HERE]"

Examples

adb shell am start -W -a android.intent.action.VIEW -d "sudokuzenkai://puzzle?q=cMOiw5XDlsOXw5zDnMKl"

adb shell am start -W -a android.intent.action.VIEW -d "https://sudokuzenkai.imaginationoverflow.com/puzzle?q=cMOiw5XDlsOXw5zDnMKl"

Windows 10¶

You can use windows run program to test your integration, just click on the Windows Button and R and place your URI on the command option and press Ok.

MacOS¶

Open up a terminal and use the Open command:

open  [MY_URI_HERE]

open  sudokuzenkai://puzzle?q=cMOiw5XDlsOXw5zDnMKl

Linux¶

On Linux you can use the xdg-open command to test your integration, open up a terminal and run the following command.

xdg-open  [MY_URI_HERE]

xdg-open  sudokuzenkai://puzzle?q=cMOiw5XDlsOXw5zDnMKl

Standalone Caveats¶

Build for MacOS¶

If you make your Mac builds on MacOS the plugin will automatically configure everything that is required in order for it to work correctly. But if you make your MacOs build on Windows you will need to do some extra steps in order to fully configure your build to receive deep link activations. Due to Unity limitations, you will need a Mac or a MacOs VM in order to completely use the plugin capabilities.

Building for MacOS on Windows¶

When the build is completed you will note that the build process created an extra folder named UniversalDeepLinkingScripts. This folder contains all tools required to correctly finish up the plugin configuration:

Copy the UniversalDeepLinkingScripts and your deliverable (you_game.app) to your Mac or VM.
Open a Terminal and navigate to the copied items location.
Run the setup.sh script:
```
./setup.sh
```

If everything goes as expected you should see something similar to the following image:

For more information on why you need to do this extra step check our Inside the Plugin Section.

Linux and Windows¶

On Windows and Linux standalone builds, the Deep Linking is only configured when the game runs the first time, so even if the player has the game installed on his machine, if he didn't play at least one time, the Deep Linking connection won't activate the game.

Windows and Linux builds also only allow players to start your game via a deep link if the player clicks on a deep link after your game is already open the plugin won't react to this new activation. The Pro version includes an option that works around this issue.

For further details on why this happens, and how to work around it you can check our Inside the Plugin Section.

Notes¶

If you don't own a mac you can always create a Mac VM
If you are targetting a platform that the plugin doesn't support, you will find that building to an unsupported platform will yield an error stating that the assembly ImaginationOverflow.UniversalDeepLinking.Platform.dll is not present. To fix this you will find a dummy assembly under Assets\Plugins\ImaginationOverflow\UniversalDeepLinking\libs\Dummy, configure it to be included on the unsupported platform that you are targetting and the error should be fixed.