HowTo: Deep Linking on Smart Devices

Official Content
This documentation is valid for:

A Deep Link consists in a URI under our domain that links certain content on the web (e.g., a store product) which can be handled by a native mobile application for processing that information. This means that the end user can open a web link with a mobile application instead of the web client application in the browser.

DeepLink - Flow

This article describes the mechanisms provided by GeneXus for adding deep linking on your Smart Device application. 

Preliminary settings

Client-side settings

In the Smart Devices Main object the developer must set the Deep Link Base URL property to indicate which Base URLs should be handled by the application when the device triggers them.

Server-side settings for Android applications

The server-side setting for Android applications is optional. If server-side has not been set, the Android OS is responsible for displaying the options that allow the end user to open the requested URI (if there is more than one option). If the developer sets the server-side option by copying the following generated JSON file to the server root (Statement test might be useful for checking grant permissions), every URI that can be handled will be opened instantly by the application.

<model>/<environment>/mobile/Android/<main_object_name>/assetlinks.json

Server-side settings for iOS applications

The server-side setting for iOS applications is mandatory. To manage deep linking on iOS devices, you must include a special file in the server root for ensuring the authority of the domain (brench aasa-validator might be helpful for testing server settings). This file is automatically generated by GeneXus in the following directory.

<model>/<environment>/mobile/iOS/<main_object_name>/apple-app-site-association/<domain>

The <domain> varies depending on Deep Link Base URL property values. The developer must copy this file manually to the server root and ensure that the server accepts empty file extension request as json (see the table below). After server resetting, the file then should be accessed via HTTP, without redirects, at https://<host>/apple-app-site-association.

.NET environment (<webapp>/web.config) JAVA environment (<tomcat_dir>/conf/web.xml)
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <staticContent>
      <mimeMap fileExtension="." mimeType="application/json" />
    </staticContent>
  </system.webServer>
</configuration>

Or, another alternative, after adding the ".json" extension to the apple-app-site-association file:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <system.webServer>
    <rewrite>
       <rules>
         <rule name="apple_json_file">
            <match url="^apple-app-site-association" />
            <action type="Rewrite" url="apple-app-site-association.json" />
         </rule>
       </rules>
    </rewrite>
    </system.webServer> 
</configuration>

Tip: You can attach a web.config File object in your KB with this content, and copy it to the /web directory (action triggered before deploying it). This action will merge the generated web.config file with your custom one, simplifying the deep linking association process.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
                      http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
  version="3.1>
    <mime-mapping>
        <extension>.</extension>
        <mime-type>application/json</mime-type>
    </mime-mapping>
</webapp>

Or, another alternative for simplifying the process (available as of GeneXus 15 Upgrade 10):

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
                      http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
  version="3.1>
    <filter>
        <filter-name>CustomFilter</filter-name>
        <filter-class>
            com.genexus.filters.CustomFilter
        </filter-class>                
    </filter>
    <filter-mapping>
        <filter-name>CustomFilter</filter-name>
        <url-pattern>
             /apple-app-site-association
        </url-pattern>
        <dispatcher>REQUEST</dispatcher>
    </filter-mapping>
</webapp>

To generate the file, the Development Team ID property must be set; otherwise, the following warning will be displayed while building.
warning: The property Development Team ID of <main_app_name> is required for apple-app-site-association generation.

Handling methodology

There are two mechanisms for handling deep links in the application. When none of them can handle the URI request, the end user will be able to see the content in a web browser.
Note: In this section, ''interactive object" refers to SD Panel, Menu, and WorkWithDevices Detail Node and List Node, .

1. Automatic

There is a set of interactive objects in the Knowledge Base responsible for displaying content for the resources requested in the URI. For example, suppose that we have a WorkWithDevices object applied to the Products transaction. The Detail node of this object will be associated with the URI http://www.mystore.com/viewproduct.aspx?1. To achieve this, the developer must set the Deep Link Name property on the Detail node with 'viewproduct.aspx' value (name of the requested resource). As we already know, the Detail node will have a parm rule for indicating the ProductId to be displayed. This parm will be automatically caught from the URI's query (in the example, ProductId will be 1).

2. Manual

The DeepLink external object allows the developer to define an event for handling, parsing and redirecting the caught URIs to their corresponding interactive object. The event code and its behavior are the responsibility of the developer.

Input parameters

Deep link parameters (input parameters of handler panel) can be managed in two ways.

1. Positioned

Parameter values are sorted in the same order as they appear in the parm rule and are separated by commas (",").
For example,

http://www.mystore.com/categorysearch.aspx?17,grey+beanie

2. Nominated

Parameters can be displayed unsorted in the URI, but they have to be named (as a key=value pair, where the key is the parameter name) and separated by an ampersand (&).
For example,

http://www.mystore.com/categorysearch.aspx?SearchedText=grey+beanie,CateogyId=17

Usage example

Suppose that we have a simple e-commerce website already designed and we want to develop the mobile application. We start by creating the sibling Smart Device objects from Web objects as follows:
Deep Link - Sample - Structure
In this case, we have three data views for Web and Smart Devices:

MyStore object (main panel).
CategorySearch object (for a custom search engine).
WorkWith object (to list and detail our products).

People now share content using its URL on the web (e.g., by email, messaging systems, social networks, etc.). For this reason, when the mobile application is installed on the end user's device, they should be able to view this content from the native application instead of opening it in the browser. To achieve this, we have to map which interactive Smart Device object will display the content displayed on each interactive Web object. From our design, these objects have the same name on different packages.

The first step is to set, in the MyStore object for the Smart Device, the following property for handling deep links:

Next, we have to set which panel will handle each resource. 

As we mentioned before, with these settings we are managing automatic deep linking. If for some reason we have to manage them manually, refer to DeepLin.Handle event example.

Finally, the behavior achieved is as follows:
Deep Link - Sample - Result and behavior

Notes

  • Special URI parameters must be encoded as follows:
    - Percent-encoding for strings (e.g. "%20" or "+" for blank space). This article can be useful: W3C - ASCII Encoding Reference.
    - ISO-8601 for date, time and date-time (e.g. "20170821" for 08-21-2017). The Date Constants article may be helpful for generating this constant from GeneXus.
  • Android allows the end user to display the content in the browser if the server-side option is not set; otherwise, it will always be displayed in the app.
  • iOS only allows the end user to display content on the application because the server-side setting is required. However, when the app is opened, on the top right corner there will be an option for redirecting to the browser.

FAQ & Troubleshooting

  • Can I use both manual and automatic alternatives?
    Yes. First, the application calls the Handle event; if this action cannot meet the request (because &IsHandled is still False), it will try to solve it automatically. If the request cannot be solved in this way either, the content will be displayed in the default browser of the device.
     
  • Can I use a different URI scheme other than HTTP?
    Yes, by using the manual alternative and parsing the URI adequately.
     
  • Can I develop my mobile application and integrate it with an existing web application?
    Yes, by setting the Deep Link Base URL property correctly.

Scope

Platforms   Smart Devices (iOS, Android)

Availability

The deep linking feature is available as of GeneXus 15 Upgrade 6.

See also



Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.