Deep Linking in Tizen

Pro tip

For an overview on how deep linking works with You.i Platform, see Deep Linking.

For Tizen, the deep linking code must be added to the app using the Linking module. Use the module’s getInitialURL() API to get the deep linking information for the session, as required.

For deep linking in Tizen to work, a set of values are used to open an app with deep link, and the data received by the opened app is coded into the query parameters of a URL. The API called to launch the Tizen app with deep link can be seen here.

URL Format for Tizen

The following input parameters are used to launch an app using the native Tizen API launchAppControl:

ApplicationControl appControl is an interface that contains the following:

DOMString operation
DOMString mime
DOMString category
ApplicationControlData[] data

Each entry in the array, which is an array of objects, includes the following data:

key
value
launchMode
uri

Applicationid is the same as one of the query parameters yiappid : id.

Native API Parameters

The input parameters can be encoded into query parameters of a URL using the following query strings. These query strings are in the following format - "Key": "Native API Args":

"yiappid": "id"
"yioperation": "appControl.mime"
"yicategory": "appControl.category"
"yidata": "appControl.data"
"yilaunchmode": "appControl.launchMode"

This should be either SINGLE or GROUP with respect to the enum value of this parameter’s type.

"yidata": "appControl.data"

If included, the yidata value should be encoded as a JSON string to match the structure of an array of ApplicationControlData. For example, sending data with two keys of "key1" and "key2" corresponding to the value arrays [“value1”] and [“value2", “value3”] would be included with the following query value:

[
  {
    "key": "key1",
    "value":
      [
        "value1"
      ]
  },
  {
    "key": "key2",
    "value":
      [
        "value2",
        "value3"
      ]
  }
]

And encoded into URL safe characters for a final query of:

yidata`=`%5B%7B%22key%22%3A%22key1%22%2C%22value%22%3A%5B%22value1%22%5D%7D%2C%7B%22key%22%3A%22key2%22%2C%22value%22%3A%5B%22value2%22%2C%22value3%22%5D%7D%5D

All of these reserved query parameters will be fetched from the URL in order to launch the deep link, and be removed from the query parameters of the URL. The resulting URL corresponds to the input that will be used for appControl.uri.

Similarly, the result of getInitialURL() will have all of the analogous parameters corresponding to RequestedApplicationControl encoded into its query parameters, as described above, when an app is launched by a deep link. For more information, see Requested Application Control.

Use Case

As described previously, the query yidata contains the customizable data used to decide on the action, formatted as a JSON string, so we can focus on parsing that query. We’ll also model the example after the common use case getting PAYLOAD data from a launch from SmartHub Preview, a Tizen menu feature. More information on SmartHub Preview, see Implementing Public Preview Deep Links.

The URL we’ll parse is following:

scheme://host?yidata=%5B%7B%22key%22%3A%22key1%22%2C%22value%22%3A%5B%22value1%22%5D%7D%2C%7B%22key%22%3A%22PAYLOAD%22%2C%22value%22%3A%5B%22%7B%5C%22value s%5C%22%3A%5C%22%7B%5C%5C%5C%22videoIdx%5C%5C%5C%22%3A1%7D%5C%22%7D%22%5D%7D%5D

The query value of yidata is a URL encoded string corresponding to the following JSON structure:

[
  {
    key: "key1",
    value: ["value1"],
  },
  {
    key: "PAYLOAD",
    value: ['{"values":"{\"videoIdx\": 1}"}'],
  },
];

So in this case, the appControl.data is an array of two ApplcationControlData objects. The first we are not interested with. The second is the SmartHub Preview payload, with key PAYLOAD and value a customizable array of strings, in this case, as in the example in the SmartHubPreview docs, containing a single string, which is itself JSON formatted string.

We want a URL that extracts videoIdx from the payload, and results in the url scheme://playerscreen/1. We will expand on the requirements and say that if videoIdx can’t be correctly parsed, the final URL should be completely blank, so that the app does not try to handle a deep link. The final transformation is {alias:videoid:{jsonvalue:videoIdx:{jsonvalue:values:{jsonarrayindex:0:{jsonvalue:value:{jsonarrayvaluematch:key:PAYLOAD:{query:yidata}}}}}:FAILURE}}{ifequal:{videoid}:FAILURE::scheme%3A%2F%2Fplayerscreen%2F{videoid}}.

One step at a time. Each step will expand on the last, and will include everything done up to that point.

First we want to make an alias, containing videoIdx, if it exists, or ‘FAILURE; if it doesn’t.
- {jsonarrayvaluematch:key:PAYLOAD:...}: Get the object within the JSON array, for which the key with name key matches the value PAYLOAD. This leaves us with only the second item in the original JSON array.
- {jsonvalue:value:...}: Get the JSON object corresponding to the parameter called value, this leaves us with only the inner array of values.
- {jsonarrayindex:0:...}: Get the first item from the array, this leaves us with only the nested JSON formatted string.
- {jsonvalue:values:...}: Get the values parameter value from the nested JSON string.
- {jsonvalue:videoIdx:...:FAILURE}: Get the parameter videoIdx from the result. It’s also important that we include that default value FAILURE, so that if any step along the way cannot parse correctly, this step will also fail, and the entire result will be failure.
- {alias:videoid:...}: Whatever the result is so far, give it an alias of videoid, so that we can continue to use the tag {videoid}, in place of this complex tag.
- In the above example, {videoid} should evaluate to 1.
- After evaluating the alias, this entire nested tag replaces itself with a blank string.
{ifequal:{videoid}:FAILURE::scheme%3A%2F%2Fplayerscreen%2F{videoid}}: This is all that remains after the alias is evaluated. This tag is an ifequal tag with the following four arguments:
- {videoid}: The result of the alias which fetches videoIdx
- FAILURE: The expected result of {videoid}, if videoIdx was not included in the expected format.
- A blank string: An empty argument (the space between the two colons next to each other after FAILURE) to signify that if {videoid} is equal to FAILURE the whole URL should be an empty string, to avoid the app from trying to handle a deep link.
- scheme%3A%2F%2Fplayerscreen%2F{videoid}: This is a URL encoded string, which when decoded equals scheme://playerscreen/{videoid}.
Since {videoid} evaluates to “1” in our above example, the resulting URL should be scheme://playerscreen/1