App Links/Universal Links Infrastructure Support

BridgePF's server will return the JSON files that are needed for client applications to register for HTTP links on a phone. If such a link is activated by a user, it will be routed to the client application rather than the default system web browser for processing. When the app is first installed, it will check for a JSON file on the server to verify the app should have permission to handle such links.

Although the file format is different for iPhone and Android, the process is pretty similar.

iPhone OS

The iPhone JSON file resides at the following path on the Bridge server: /.well-known/apple-app-site-association. It is a JSON file in the following format:

{
    "applinks": {
        "apps": [],
        "details": [
            { "appID": "KA9Z8R6M6K.org.sagebase.crfModuleApp", "paths": [ "/crf-module/*"] }
        ]
    }
}

Each study in Bridge can contribute one or more "details" entries in the details array (configured as part of the study object). The records should not have identical appIDs, put all the paths for a specific ID in one entry. The order of the entries in the array determines the order the system follows when looking for a match. In the example above, a link in the format https://webservices.sagebridge.org/crf-module/install would be intercepted by the app with ID *.crfModuleApp if it is installed on the device. Currently the link will not resolve to anything on the Bridge server. It may eventually resolve to a landing page to aid in the installation of the given app (TBD).

Android

The Android JSON file resides at the following path on the Bridge server: /.well-known/assetlinks.json. It is a JSON file in the following format:

[{
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
        "namespace": "android_app",
        "package_name": "com.example",
        "sha256_cert_fingerprints": ["..."]
    }
}]

Each study in Bridge can contribute one or more elements to the returned array (configured as part of the study object). Again, like iPhone, don't create multiple entries with the name namespace and package name. We have not tested this behavior and it is not necessary. Unlike iPhone, multiple Android apps can register to receive links for the same host name, and they disambiguate which app to route the URL to based on the registration of a pathPrefix in the Intent (it doesn't appear that Android supports wildcard characters like the iPhone does):

<data android:scheme="https"
      android:host="webservices.sagebridge.org"
      android:pathPrefix="/crf-module/install" />

Use Cases

OAuth authentication (like we will be integrating with in order to retrieve Fitbit data) requires that we supply an URL as a callback that will be used to redirect the user after successful authentication. We want this URL to be registered with the device's OS such that it is sent to the application to complete authentication in the application;
We eventually want to be able to send links to the device that will either open the app if it is installed, or redirect to the App Store to install the app if it is not. We need this kind of link registration to smoothly execute this workflow.

General Observations

Studies can configure multiple entries for the rare case where app development, in a hand-off between development organizations, there is a need to change the app ID of the app. If we create an installation page on BridgePF, it will have to privilege one of these records for installation (we'll either augment the system to mark the record, or always take the first record). However we expect this situation should be rare.

References

https://developer.apple.com/library/content/documentation/General/Conceptual/AppSearch/UniversalLinks.html

https://developer.android.com/training/app-links/verify-site-associations.html

Note: there has been discussion of saving credentials or information about the user on a landing page to pick up when the app is opened, so we don't send information like phone numbers to an App Store. Here's some information on this (it requires signing the JSON file however, so is not trivial to implement): https://developer.apple.com/documentation/security/shared_web_credentials