Universal and App Links

Enhance your app's user experience with universal links or app links by opening your app via a web URL.

Project Usage

With universal and app links, you can use the same URL to open your app or a web page, depending on whether the app is installed on a device. If the app is not installed, the link automatically falls back to opening in the web browser. This guarantees that the users will always have a consistent and optimal experience, whether they have the app installed or not.

For handling universal and app links in QML use the App::appLinkUrlReceived signal, which provides URL information when your application is opened from an app or universal link.

You can implement it the following way:

 import Felgo

 App {
   onAppLinkUrlReceived: function(appLinkUrl) {
     console.log("Opened with:", appLinkUrl)
   }
 }

Also see App::appLinkUrlReceived for more information about handling the universal and app links in your app.

iOS Setup

To create a secure connection between your website and your app, you have to associate them.

To be able to make the connection, first you need to create your entitlements file. To activate the entitlement for your app, add the following settings to your CMakeLists.txt configuration to use a custom entitlements file:

 if(CMAKE_SYSTEM_NAME STREQUAL "iOS")
 set_target_properties(TargetApp PROPERTIES
     XCODE_ATTRIBUTE_CODE_SIGN_ENTITLEMENTS
     "${CMAKE_CURRENT_SOURCE_DIR}/ios/TargetApp.entitlements")

 target_sources(TargetApp PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/ios/TargetApp.entitlements")
 endif()

You must add the associated domain to your .entitlements file. By specifying associated domains in the .entitlements file, you allow your app to handle universal links for those domains. This adds a layer of security by ensuring that the domains are linked to the appropriate app and it is also required for enabling universal links functionality in your app.

 <?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:example.com</string>
   </array>
 </dict>
 </plist>

Android Setup

To create a secure connection between your website and your app, you have to associate them.

You need to specify which URLs your app can handle by adding intent filters to your app's AndroidManifest file. This step tells the Android system that your app can open certain URLs.

 <intent-filter android:autoVerify="true">
     <action android:name="android.intent.action.VIEW" />
     <category android:name="android.intent.category.DEFAULT" />
     <category android:name="android.intent.category.BROWSABLE" />
     <data android:scheme="https" android:host="example.com" android:path="/subfolder"/>
 </intent-filter>

Web Hosting

To use universal links, you need a website with an associated domain.

1. Publish the Apple iOS App Site Association File

Create a file named apple-app-site-association and host it at your domain's .well-known folder. For example https://example.com/.well-known/apple-app-site-association

This file tells the mobile browser which iOS application to open instead of the browser. It uses JSON format, but doesn't include the .json file extension. To create the file, you need to know the appID of your application, which consists of the TeamID and BundleID. You can also specify paths so that only URLs that include the specified paths will open the app, not all URLs.

What the fields in apple-app-site-association file mean:

• details: An array that contains objects with details about the different apps that are associated with your domain.
• appID: It consists of two parts. TeamID: A 10-character ID assigned by Apple to your developer account. BundleID: It's a unique string that identifies an application. Typically has a format like: com.yourcompany.yourappname
• paths: specifies the path part of the URL. It means that only URLs that include the specified paths will open the app, not all URLs.

The file should look similar to the following:

 "applinks": {
     "apps": [],
     "details": [
         {
             "appID": "TeamID.BundleID",
             "paths": ["*"]
         }
     ]
 }

For further information visit Apple's documentation.

2. Publish the Android Asset Links File

Create a file named assetlinks.json and host it at your domain's .well-known folder. For example: https://example.com/.well-known/assetlinks.json

This file tells the mobile browser which Android application to open instead of the browser. To create the file, you need the app's package name and the SHA-256 fingerprint of the signing key used to sign the Android app.

What the fields in assetlinks.json file mean:

• relation: specifies the relationship type between your domain and the target. delegate_permission/common.handle_all_urls means that the app can handle all URLs for the specified domain.
• namespace: specifies the type of the target that can handle the URLs. Setting the namespace to android_app means that the target is an Android app.
• package_name: specifies the unique identifier of the target. It has to be set to your Android application ID.
• sha256_cert_fingerprints: ensures that only the app signed with the specified certificate can handle the domain's URLs.

The file should look like the following:

 [
     {
         "relation": [
             "delegate_permission/common.handle_all_urls"
         ],
         "target": {
             "namespace": "android_app",
             "package_name": "com.example.app",
             "sha256_cert_fingerprints": [
                 "AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90"
             ]
         }
     }
 ]

For further information visit the Android app link documentation.