Skip to main content

Config

There is a lot that your app can do, most of it can be set in the configuration. Despite the vast amount of actions, layers and events with which you you create almost anything, some details are more of the generic type and control the basic underlying features of you application. This is where the config/app.json comes in: This file offers you the possibility to set some ground rules and general settings for different aspects of your app.

Basic structure

The app.json file within the ./config directory is the only file and consists of a single object named context:

basic structure
{
"context": {
...
}
}

Inside the context object is where the magic is happening. Take a look at the following attributes that you can configure to define the general behavior of your app.

Context attributes

note

Some of the following settings (marked with *) need further explaination, please see below under Notes on certain attributes.

KeyTypeDescriptionDefault Value
"baseUrl"StringThis value sets the baseUrl for the app to connect to its mos.server instance. It is provided by mos.server automatically and it is not necessary to be set manually.null
"beaconMode"*StringDescribes how the app will scan for beacons. Possible values are always, withPermisson or onDemand.null
"cachedUrls"StringA list of URLs to be cached by the app, usually preserved for websites, PDFs, etc. Every entry is separated by a ::.null
"enablePush"*BooleanThis setting enables push as a basic setting and therefore asks the user as soon as possible on first start. It is generally not advised to use this option. For more details, see below.null
"matomoTrackingId"StringIf using Matomo as your analytics platform, this value should be set to your matomo provided tracking ID of the website.null
"matomoTrackingUrl"StringThis URL should point to your matomo instance, e.g. https://mymatomo.xyz/client/matomo.php.null
"pushHistoryEnabled"BooleanThe global setting to enable the storage of received push notifications within the app itself.null
"pushHistoryMaxAge"IntegerThe maximum age of the stored push messages in seconds.null
"pushHistoryQueries"ObjectDictionary of named SQLite queries to retrieve stored messages, i.e. "all": {"custom": "SELECT * FROM _push_history"}.null
"pushHistorySavePayload"BooleanDetermines if the payload of a messages is stored in addition to the message itself.null
"pushUrl"StringThe URL to send device information (like your push token) to, if enablePush is set to true.null
"tamperedReaction"StringBehavior of your application if the device running it is rooted. Possible values: none, message, close (Android only).null
"tamperedText"StringIf tamperedReaction is set to message, the text to be displayed.null
"tamperedTitle"StringIf tamperedReaction is set to message, the title to be displayed.null
"updateBehavior"* (required)StringIf your app detects an update of its configuration, these are the options how to behave: manual, directly, popUpnull
"updateErrorBehavior"StringSets the behavior of the app, if the update of the configuration fails. Possible values are errorScreen or oldConfignull
"updateInterval" (required)IntegerTime in seconds between checking for new configuration.null
updateOnlyNewPushTokensBooleanThe app will only send the push token to the pushUrl if an new token is provided by the respective service (Android only).null
updatePopUpLaterButtonDelayIntegerTime in seconds between postponing an update notification and the next one.null
updatePopUpLaterButtonEnabledBooleanDetermines if the user can postpone the update to be asked again at a later date.null
updatePopUpLaterButtonMaxIntegerNumber of times a user can postpone the update notification before being forced to update.null
updatePopUpLaterButtonTextStringText displayed on the button to postpone an update notification.null
"updatePopUpText"StringText to be displayed to inform the user about an update.null
updatePopUpUpdateButtonTextStringText displayed on the button to update the application to the newest configuration.null
updatePopUpUpdateInBackgroundBooleanDetermines if the app will restart while in background to fetch updated configuration.null
updatePopUpUpdateInBackgroundDelayIntegerIf updatePopUpUpdateInBackground is enabled and an update is available, the amount of time in seconds the app has to be in background before it automatically will restart.null
"updateUrl"StringThis value consists of the baseUrl to mos.server and the /_update path for the app to check for configuration changes, i.e. `` for the app to connect to its mos.server instance.This value is provided by mos.server and should not be set manually.null

Notes on certain attributes

beaconMode

Depending on the value of beaconMode, the app will scan for beacons in different ways. While always will start scanning for beacons immediately (and therefore promt the user with a permission request for notificatins on app start), withPermisson or onDemand will wait for the startBeaconScanning action to be triggered by the user.

enablePush

While using enablePush technically promts the user to grant permission for notifications, it is not recommended, as this happens immediately after the (first) app start. Instead you should seek a way to introduce the feature and/or explain to the user why you want to provide them with push notifications and why this is beneficial to them before are asked asked to grant permisson. This generally oncreases acceptance and provides a better user experience. To enable push notifications afterwards, see registerPush.

updateBehavior

Depending on the updateInterval, your app will look for changes of your configuration on a regular basis while being actively used (note that mos. apps will always load the newest configuration on a fresh app start). If an update is detected, there are multiple ways for your app to react to these changes: manual, directly, popUp.
As the name suggests, manually will do nothing except writing some update information (updateAvailable, updateSince) to the userSettings storage. This offers the developer the most freedom to handle the process on their own.
The update behavior directly will restart the app to load the newest configuration immediately. This option will likely result in a poor user experience as active users may lose their data/progress depending on the structure and type of your app.
Using the popUp option is considered the best option for most use cases. As soon as an update is registered, the app will display a pop-up with the specified texts, informing the user of the update, but giving them the option to postpone the update/restart, e.g. to finishing the current session or task.

Examples

A few examples on layouting multiple layers in various ways.

  1. The first example with the most basic settings.
basic config
{
"context": {
"updateBehavior": "popUp",
"updateInterval": 600
}
}
  1. This example extends the previous one with tracking and push history.
extended app config with tracking and push history
{
"context": {
"updateBehavior": "popUp",
"baseUrl": "https://my.app.org",
"pushUrl": "https://my-profile.app.org",
"matomoTrackingUrl": "https://analytics.app.org/my-app/matomo.php",
"matomoTrackingId": "123",
"updateInterval": 600,
"pushHistoryEnabled": true,
"pushHistorySavePayload": true,
"pushHistoryMaxAge": 2419200,
"pushHistoryQueries": {
"allMessages": {
"custom": "SELECT * FROM _push_history"
}
}
}
}