Tutorial: App configuration

The preferred way to set up the targeted Webcom application (the one you have created on your Webcom developer console) is a property file within the src/main/assets directory of your Android module.
If this file is additionally named webcom.properties, you have nothing to do! The WebcomApplication object associated with it is directly provided by the WebcomApplication.default Kotlin property.

This WebcomApplication object is the root object to benefit from all the Webcom features: it provides both the authenticationService and the datasyncService properties to respectively access to the authentication-related features and the real database-related features.

Asset file structure

The complete structure of the webcom.properties file is as follows:

# mandatory property, it expects a string
applicationId=<IDENTIFIER-OF-YOUR-WEBCOM-APPLICATION>
# optional property, it expects a valid http or https URL (default value is "https://io.datasync.orange.com")
platform=https://io.datasync.orange.com
# optional property, it expects a boolean value (default value is "true")
startOnline=true
# optional property, it expects an encoded string value (default is no value at all)
offlineCache="JSON-encoded string representing the local data cache of the Datasync Service"
# optional property, it expects either "V5" or "V6" (default value is "V5")
websocketProtocol=V5
# optional property, it expects a valid integer (default value is "45000")
pingDelayMs=45000
# optional property, it expects a valid integer (default value is "5000")
pongDelayMs=5000

The only mandatory property is applicationId, which defines the identifier of the Webcom application you are targeting.

Then there are a couple of optional properties available for more advanced uses:

• Common use
  When you first get the datasyncService of your WebcomApplication object, it immediately attempts to connect to the Webcom back end and establish a web socket. If you wish to start offline whatever the availability of the network connectivity is, you can set the startOnline property to false.
  In order to further switch your client device online (ie establish the web socket to the back end), simply set the isConnectionEnabled property of the datasyncService to true.
• Specific use
  By default, the Webcom back end is looked up at the Webcom production platform, namely https://io.datasync.orange.com. If your Webcom application is hosted on a dedicated platform, you can specify it using the platform property.
  By default, the db associated with your application starts with an empty local data cache. You can use the offlineCache property to restore this cache in a given state. As the local cache is usually saved in the Android application data and dynamically restored at application startup, it is generally more convenient to initialize its state when building the WebcomConfiguration object (associated with the
  WebcomApplication instance to build) using its withOfflineCache() method (see below).
• Advanced use
  The web socket established by the DatasyncService between the client device and the Webcom back end may be set up using the following properties:
  • In order to keep the web socket alive, a dummy "ping" packet is regularly sent to the back end when there is no activity on the socket (ie when no message is sent or received for a while). The inactivity period for sending "ping" messages is set by the pingDelayMs property (in milliseconds).
  • In addition, the client device may require the back end to reply to each received "ping" message with a "pong" message. This may be useful on some old devices to detect faster the web socket is down. To do so, the websocketProtocol property must be set to "V6" (instead of "V5", which only sends "ping" messages).
  • When the "V6" protocol is enabled, the pongDelayMs property controls the maximum delay allowed to receive the "pong" messages. If a "pong" message exhausts this delay, the web socket will be considered as down and will be closed and re-established by the client device.

Dynamically build a WebcomConfiguration

Most of the time, we need to set dynamically some properties of the targeted Webcom configuration, while most other properties can be statically defined in an asset file. It is possible to mix these approaches using the dedicated withStartOnline() and withOfflineCache() methods of the WebcomConfiguration class:

fun userChoiceForStartingOnline(): Boolean { /* ... */ }
fun retrievePersistedCache(): String { /* ... */ }

val configuration = WebcomConfiguration
  .fromAsset("my-asset-file.properties") // load all properties from a given asset file
  .withStartOnline(userChoiceForStartingOnline()) // the `startOnline` property will be overridden by this value
  .withOfflineCache(retrievePersistedCache())     // the `offlineCache` property will be overridden by this value
val myApp = WebcomApplication.fromConfiguration(configuration) // then build an application from the previous configuration

If you need to override other properties, you can use the generic copy() method of the WebcomConfiguration data class (available in Kotlin only).