Config

The app config defines general settings that control the basic behavior of your app.

The config is stored in ./config/app.json.

Quick guide

A basic config can look like this:

./config/
└── app.json

The app.json file contains a context object with the configuration settings.

{
  "context": {
    "updateBehavior": "popUp",
    "updateInterval": 600
  }
}

In this example, the app checks for configuration updates every 600 seconds and displays a pop-up when an update is available.

Config file

app.json is the only config file needed.

./config directory

The app.json file is stored in the ./config directory.

./config/
└── app.json

app.json structure

The app.json config file consists of a single context object:

{
  "context": {
    ...
  }
}

All attributes are defined inside the context object.

Context attributes

The following attributes can be used to configure the general behavior of the app.

Key	Type	Description	Default
baseUrl	String	Base URL used by the app to connect to its mos.server instance. This value is provided by mos.server and does not need to be set manually.	null
beaconMode	String	Defines how the app scans for beacons. Possible values are always, withPermission, and onDemand.	null
cachedUrls	String	List of URLs to cache, for example websites or PDF files. Multiple URLs are separated by ::.	null
enablePush	Boolean	Enables push notifications as a basic setting and requests notification permission as soon as possible after the first app start.	null
matomoTrackingId	String	Matomo tracking ID used by the app.	null
matomoTrackingUrl	String	URL of the Matomo instance, e.g. https://mymatomo.xyz/client/matomo.php.	null
pushHistoryEnabled	Boolean	Enables storing received push notifications in the app.	null
pushHistoryMaxAge	Integer	Maximum age of stored push notifications in seconds.	null
pushHistoryQueries	Object	Named SQLite queries used to retrieve stored push notifications, e.g. "allMessages": {"custom": "SELECT * FROM _push_history"}.	null
pushHistorySavePayload	Boolean	Determines whether the payload of a push notification is stored in addition to the push notification itself.	null
pushUrl	String	URL to which device information, such as the push token, is sent when enablePush is set to true.	null
tamperedReaction	String	Defines how the app reacts when it detects a rooted device. Possible values are none, message, and close (Android only).	null
tamperedText	String	Text displayed when tamperedReaction is set to message.	null
tamperedTitle	String	Title displayed when tamperedReaction is set to message.	null
updateBehavior	String	Defines how the app reacts when an updated configuration is available. Possible values are manual, directly, and popUp.	null
updateErrorBehavior	String	Defines how the app reacts when updating the configuration fails. Possible values are errorScreen and oldConfig.	null
updateInterval	Integer	Time in seconds between checks for an updated configuration.	null
updateOnlyNewPushTokens	Boolean	Sends the push token to pushUrl only when a new token is provided (Android only).	null
updatePopUpLaterButtonDelay	Integer	Time in seconds between postponing an update pop-up and the next one.	null
updatePopUpLaterButtonEnabled	Boolean	Determines whether the user can postpone an update to be asked again later.	null
updatePopUpLaterButtonMax	Integer	Maximum number of times an update pop-up can be postponed before the update is forced.	null
updatePopUpLaterButtonText	String	Text displayed on the button used to postpone an update.	null
updatePopUpText	String	Text displayed in the update pop-up.	null
updatePopUpUpdateButtonText	String	Text displayed on the button used to update the app to the newest configuration.	null
updatePopUpUpdateInBackground	Boolean	Determines whether the app can restart in the background to load an updated configuration.	null
updatePopUpUpdateInBackgroundDelay	Integer	Time in seconds the app must remain in the background before restarting to load an update when updatePopUpUpdateInBackground is set to true.	null
updateUrl	String	URL used by the app to check for configuration updates. This value consists of the baseUrl and the /_update path and is provided by mos.server and should not be set manually.	null

Configuration details

Some attributes require additional explanation of their possible values and behavior.

beaconMode

The beaconMode attribute defines how the app scans for beacons.

Possible values are:

• always starts scanning for beacons immediately and prompts the user for the required permissions on app start.
• withPermission start scanning when the startBeaconScanning action is executed and requests the required permissions if needed. Scanning does not continue after an app restart.
• onDemand starts scanning immediately after app start if all permissions have already been granted.

Depending on the selected value, the app may request the required permissions at different times.

To start beacon scanning manually, use the startBeaconScanning action.

enablePush

The enablePush attribute enables push notifications as a basic app feature.

{
  "context": {
    "enablePush": true
  }
}

When enabled, the app requests notification permission as soon as possible after the first app start.

This is generally not recommended. Users are more likely to accept notification permissions when they understand why notifications are useful and what they will receive.

A better approach is to introduce the push notification feature first and request permission when it becomes relevant to the user.

To enable push notifications later, use the registerPush action.

updateBehavior

The updateBehavior attribute defines how the app reacts when a new configuration is available.

Possible values are:

• manual does not automatically apply the update. Instead, information such as updateAvailable and updateSince is written to the app storage so that the update can be handled manually.
• directly restarts the app immediately to load the new configuration. See Example Config with direct updates
• popUp displays an update notification and allows the user to postpone the update. See Example Config with update pop-ups

The popUp option allows users to finish their current task before restarting the app.

The app checks for configuration updates according to updateInterval.

A fresh app start always loads the newest available configuration.

Examples

Config with direct updates

When updateBehavior is set to directly, the app updates immediately when a configuration update is available.

{
  "context": {
    "updateBehavior": "directly",
    "updateInterval": 120
  }
}

Config with update pop-ups

When updateBehavior is set to popUp, the app displays a pop-up when a configuration update is available. The user can then choose whether to install the update.

{
  "context": {
    "updateBehavior": "popUp",
    "updateInterval": 120,
    "updatePopUpText": "A new configuration update is available. Installation requires restarting the app.",
    "updatePopUpUpdateButtonText": "Update",
    "updatePopUpLaterButtonText": "Not now"
  }
}

The updatePopUpText, updatePopUpUpdateButtonText and updatePopUpLaterButtonText fields specify the text for the pop-up.

Config with tracking and push history

A config set up for Matomo tracking and enabled push history that saves push notifications including their payload for 28 days.

{
  "context": {
    "updateBehavior": "popUp",
    "updateInterval": 600,
    "baseUrl": "https://my.app.org",
    "pushUrl": "https://my-profile.app.org",
    "matomoTrackingUrl": "https://analytics.app.org/my-app/matomo.php",
    "matomoTrackingId": "123",
    "pushHistoryEnabled": true,
    "pushHistorySavePayload": true,
    "pushHistoryMaxAge": 2419200,
    "pushHistoryQueries": {
      "allMessages": {
        "custom": "SELECT * FROM _push_history"
      }
    }
  }
}

Troubleshooting

If a configuration setting does not behave as expected, check the following:

1. Is app.json stored in the ./config directory?
2. Is the setting defined inside the context object?
3. Is the attribute name spelled correctly?
4. Is the value using the correct data type?
5. Does the selected value match one of the supported values for the attribute?
6. Does the setting require an additional action, such as registerPush or startBeaconScanning?
7. Is the app using the latest configuration?