Universal Links

Universal links let you connect to content deep inside your app. Users open your app in a specified context, allowing them to accomplish their goals efficiently.

While universal links and custom URLs are both acceptable forms of deep linking, universal links are strongly recommended as a best practice.

Overview

The purpose of universal link is to link to content within your app and share data securely.

When users tap a universal link, platforms redirect the link directly to your app without routing through any browser or your website. In addition, because universal links are standard HTTP or HTTPS links, one URL works for both your website and your app. If your app is not installed, the system opens the URL in browser of your choice, allowing your website to handle it.

Use Universal links to link to content within your app and share data securely.

On Android platforms; http, https, mailto or similar universal URL schemes are not treated differently than any other schemes. As a result, you can configure your application to handle any kind of link by defining them beforehand.

For the application to handle URL, the application should be launched at least once after it is installed.

How to use

The url will follow this markup. ://:[||]

Step 1 - Add your url pattern using data-elements

Smartface saves the Android configurations in /config/Android/AndroidManifest.xml file.

Make sure to add the under directly into field.

The path, pathPrefix and pathPattern properties must start with a /.

To handle any specific sub-url or apply regex, use android:pathPattern instead of android:path.

Smartface Framework provides an event called onApplicationCallReceived where links are received. Best practice is to invoke this event in /scripts/app.js file, to reach the whole application.

On iOS, universal linking is handled with onUserActivityWithBrowsingWeb event. So onApplicationCallReceived will not be used for that purpose.

JavaScript
JavaScript
Application.onApplicationCallReceived = e => {
if (System.OS === "Android" && e.url) {
/* Your code goes here */
}
};

Note that this function will be executed everytime when application is launched. Make sure to handle that case, otherwise the app can behave unexpectedly since it is called directly upon launch.

You can access more about custom schemes

Use Universal links to link to content within your app and share data securely.

When users install your app, iOS checks a file stored on your web server to verify that your website allows your app to open URLs on its behalf. Only you have the ability to store this file on your server, securing the association of your website and your app.

iOS will check if a Universal Link has been registered (an AASA (apple-app-site-association) file should be there in the domain which contains the bundle id of the app and the paths the app should open) for the domain associated with the link, then check if the corresponding app is installed. If the app is currently installed, it will be opened. If it’s not, Safari will open and the http(s) link will load.

How to use

Step 1 - Register your app

Step 2 - Enable Associated Domains on your app identifier

  • Configure your website to host the apple-app-site-association file

Apple App Site Association File

This file associates your website domain with your app and must be hosted at

The AASA file contains a JSON object with a list of apps and the URL paths on the domain that should be included or excluded as Universal Links. Here is a sample AASA file:

{
"applinks": {
"apps": [],
"details": [{
"appID": "AABBCCDDEE.io.smartface.test",
"paths": [
"*"
]
}]
}
}

  • appID consists of two fields; team id and the bundle id. In this example team id is AABBCCDDEE and the bundle id is io.smartface.test

  • paths field consists of an array of strings that specify which paths are included or excluded from association

Multiple apps on the same domain are also supported. To do that, you’d need to add a new appID, path dictionary to the details array in the AASA file to look something like this:

{
"applinks": {
"apps": [],
"details": [
{
"appID": "AABBCCDDEE.io.smartface.test",
"paths": [ "NOT /e/*", "*", "/", “/archives/201?/* ]
},
{
"appID": "FFGGHHIIJJ.io.smartface.test2",
"paths": [ "NOT /e/*", "*", "/", “/archives/200?/* ]
}
]
}
}

Step 3 - Create app.entitlements File

  • Create a new file named app.entitlements under /config/iOS in your workspace

  • Here is a sample app.entitlements file:

app.entitlements
app.entitlements
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.developer.associated-domains</key>
<array>
<string>applinks:[yourdomain]</string>
</array>
</dict>
</plist>

In this section we will explain how your app to respond to an incoming universal link. Smartface Framework provides an event called onUserActivityWithBrowsingWeb where universal links are received.

Best practice is to invoke this event in /scripts/app.js file, to reach the whole application.

JavaScript
JavaScript
Application.ios.onUserActivityWithBrowsingWeb = url => {
// Do something with url
return true; // iOS handled this activity
};

  • Returning true indicates that your app handled the activity

  • Returning false will let iOS know that your app did not handle the activity

Universal links offer a potential attack vector into your app, so make sure to validate all URL parameters and discard any malformed URLs. In addition, limit the available actions to those that do not risk the user’s data. For example, do not allow universal links to directly delete content or access sensitive information about the user. When testing your URL-handling code, make sure your test cases include improperly formatted URLs.