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.

Key	Type	Description	Default Value
"baseUrl"	String	This 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"*	String	Describes how the app will scan for beacons. Possible values are always, withPermisson or onDemand.	null
"cachedUrls"	String	A list of URLs to be cached by the app, usually preserved for websites, PDFs, etc. Every entry is separated by a ::.	null
"enablePush"*	Boolean	This 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"	String	If using Matomo as your analytics platform, this value should be set to your matomo provided tracking ID of the website.	null
"matomoTrackingUrl"	String	This URL should point to your matomo instance, e.g. https://mymatomo.xyz/client/matomo.php.	null
"pushHistoryEnabled"	Boolean	The global setting to enable the storage of received push notifications within the app itself.	null
"pushHistoryMaxAge"	Integer	The maximum age of the stored push messages in seconds.	null
"pushHistoryQueries"	Object	Dictionary of named SQLite queries to retrieve stored messages, i.e. "all": {"custom": "SELECT * FROM _push_history"}.	null
"pushHistorySavePayload"	Boolean	Determines if the payload of a messages is stored in addition to the message itself.	null
"pushUrl"	String	The URL to send device information (like your push token) to, if enablePush is set to true.	null
"tamperedReaction"	String	Behavior of your application if the device running it is rooted. Possible values: none, message, close (Android only).	null
"tamperedText"	String	If tamperedReaction is set to message, the text to be displayed.	null
"tamperedTitle"	String	If tamperedReaction is set to message, the title to be displayed.	null
"updateBehavior"* (required)	String	If your app detects an update of its configuration, these are the options how to behave: manual, directly, popUp	null
"updateErrorBehavior"	String	Sets the behavior of the app, if the update of the configuration fails. Possible values are errorScreen or oldConfig	null
"updateInterval" (required)	Integer	Time in seconds between checking for new configuration.	null
updateOnlyNewPushTokens	Boolean	The app will only send the push token to the pushUrl if an new token is provided by the respective service (Android only).	null
updatePopUpLaterButtonDelay	Integer	Time in seconds between postponing an update notification and the next one.	null
updatePopUpLaterButtonEnabled	Boolean	Determines if the user can postpone the update to be asked again at a later date.	null
updatePopUpLaterButtonMax	Integer	Number of times a user can postpone the update notification before being forced to update.	null
updatePopUpLaterButtonText	String	Text displayed on the button to postpone an update notification.	null
"updatePopUpText"	String	Text to be displayed to inform the user about an update.	null
updatePopUpUpdateButtonText	String	Text displayed on the button to update the application to the newest configuration.	null
updatePopUpUpdateInBackground	Boolean	Determines if the app will restart while in background to fetch updated configuration.	null
updatePopUpUpdateInBackgroundDelay	Integer	If 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"	String	This 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
  }
}

2. 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"
      }
    }
  }
}