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 thedatasyncService
of yourWebcomApplication
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 thestartOnline
property tofalse
.
In order to further switch your client device online (ie establish the web socket to the back end), simply set theisConnectionEnabled
property of thedatasyncService
totrue
. - 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 theplatform
property.
By default, the db associated with your application starts with an empty local data cache. You can use theofflineCache
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 theWebcomConfiguration
object (associated with the
WebcomApplication
instance to build) using itswithOfflineCache()
method (see below). - Advanced use
The web socket established by theDatasyncService
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.
- 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
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).