Bridge
Contact Us Terms of Use

Configuring apps remotely

The Bridge server can provide your app with various kinds of configuration information.

App Configs

The Bridge app config system allows your app to retrieve arbitrary JSON configuration that you provide, as well as Bridge-specific information about the versions of the upload schemas and surveys your app should retrieve and use. This allows you to vary the behavior of your app to some degree (e.g. fixing a typo, adding a scheduled activity, or adding a survey question), without having to do a full app release cycle. It also allows you to manage the upgrade of apps to a newly released version.

Bridge's system includes the top-level AppConfig object, and one or more AppConfigElements that can be included in an app config. These can all be created and managed by developers through the Bridge APIs.

You can create one or more app config objects in Bridge. One of your app configs can be selected and returned to clients based on public selection criteria like the requesting app version, or the user's language (as expressed in the User-Agent and Accept-Language headers). If the user's request will match more than one app config, we return the oldest app config. App config objects are not versioned or published; once created, they are immediately available for selection by clients.

Set the minimum app version for iOS and Android to 1000 on your new app config, so it is not returned to clients before you are ready!

An app config has several important property keys to bring to your attention:

criteria: The Criteria used to select an app config based on a request. Because app configs are normally retrieved at first start up for an app, they can be retrieved through a public API before authenticating. But for this reason, only the criteria information that is communicated through HTTP headers (app version and user language) can be used to select an app config.

clientData: This is an arbitrary JSON payload that can contain anything you add to it. It is not structured or validated, and can be entered through the Bridge Study Manager.

surveyReferences, schemaReferences, and configReferences: These properties contain arrays of references to surveys, schemas, and app config elements. From these references you can retrieve the specific revision of a survey or schema to use in the app (survey GUID & createdOn timestamp, or schema ID and revision).

Config references link to a specific config element by its revision.

configElements: This is a map of string GUIDs to JSON app config element objects. There will be an app config element included for every element in the configReferences object (the former is editable, while this field is readonly). As you'd expect, the revisions that are included are the revisions specified in configReferences.

App Config Elements

AppConfigElement objects are in JSON and cannot be selected based on request criteria, however, they can be referenced in an app config, and app configs can be selected as described above. (App configs are thus the "top-level" objects of a JSON object graph.) App config elements can be revised in one or more revisions. Revisions are not published because you must specify a specific element revision when you include the element in an app config.

Why app config elements? Our principle use of these elements is to separate out configuration for external partners to manage. They can create new revisions of their configuration, and our developers can review and include the new revisions in the top-level app configs.

To create links that are intercepted by your app (“App Links” on Android, “Universal Links” on iPhone), we provide the server support to register those links with your application. You create links to the ws.sagebridge.org domain, but instead of resolving these to the Bridge server, the native mobile operating system will start your app and pass the link information to your app instead.

It is desirable to set up this functionality on an external domain that is associated with your research study. However, if you do not have access to an external web server, or just need this functionality to test until your site is up, Bridge can provide support for link interception.

Your links must point to the host and path https://ws.sagebridge.org/<your study id>.

For Apple OS where you must specify the paths that will be intercepted on this domain, your paths must always include the study-based identifier (so for example, https://ws.sagebridge.org/<your study id>/startTask3 would be fine, but https://ws.sagebridge.org/startTask3 would conflict with other studies on the Bridge server).

On Android, you should declare the Intents to capture these links so they include the <data android:pathPrefix="/<your study id>"/> element to scope your captured URLs.

Bridge enforces these constraints.

For further information, see Android App Links or Apple Universal Links.

For the intent to participate workflow, the Bridge server will send a link to the user to download your app. In the Bridge Study Manager, you can configure this link under Settings > Install Links.

You can provide separate links for iOS and Android and the API will use the submitted osName (iOS or Android) to select a link for inclusion in the the message template (see below). If you wish to do content negotiation and forward the user from an intermediate web site, you can provide one Universal link. The system will look first for the OS-specific link, then fallback to the universal link if it is defined.

This install link will be embedded in the "App Install Link" email or SMS template, depending on what identifying credential was submitted to the Intent To Participate API. If you are using the universal link, you can also just include it directly in the templates, since it will never change.