Tutorial: Quickstart

Android Quickstart

1. Configure your Android project

Minimal configuration

The minimal configuration consists in adding a dependency to the Webcom SDK for Android into the build.gradle file of your module:

dependencies {
    // ...
    implementation 'com.orange.webcom:sdk-android:2.0.6'
    // ...
}

If you wish to test a *-SNAPSHOT version, you must add the following maven repository into the top-level build.gradle file of your project:

allprojects {
    repositories {
        maven { url "https://oss.sonatype.org/content/repositories/snapshots/" }
    }
}

Additional configuration

Some Webcom SDK for Android features require some additional configuration of your Android project. On this purpose, see directly the dedicated sections:

Conflicting files merged from other dependencies

The Webcom SDK for Android uses itself 3rd-party open source libraries. Their license files may conflict when Android Studio builds your project, as they are usually named the same way. To avoid this, you can include in the build.gradle file of your modules:

android {
    packagingOptions {
        pickFirst 'LICENSE.txt'
        pickFirst 'META-INF/LICENSE'
        pickFirst 'META-INF/NOTICE'
    }
}

Note: As most open source licenses require to be included in your software, don't forget to include them by other means before distributing it.

2. Start coding

The whole Kotlin API is under the com.orange.webcom.sdk package.

First define the link to your actual Webcom application (ie the one you have created on the Webcom developer console) by providing a webcom.properties asset file (in the src/main/assets directory of your application module):

applicationId=YOUR-WEBCOM-APP-NAME

The corresponding WebcomApplication Kotlin object is then provided through the WebcomApplication.default Kotlin property.

Now you just have to wait for the Webcom SDK for Android to be initialized using the Webcom.whenSdkIsInitialized entry point, before calling any function of the SDK:

import com.orange.webcom.sdk.datasync.subscription.SubscribableEvent.*

Webcom.whenSdkIsInitialized { // WARNING: calling any API before the 'whenSdkIsInitialized' method calls its passed callback will not work!
    @Serializable
    data class MyBusinessObject(val a: String, val b: Boolean, val c: Int)

    val myApp = WebcomApplication.default // the app defined by the 'webcom.properties' asset file
    val datasync = myApp.datasyncService // this service is the entry point for all datasync-related features
    val manager = datasync.createManager()
    val path = "/some/path"
    
    // READ DATA
    manager.node(path).get {
        when (it) {
            is WebcomResult.Success -> {
                when (val data = it.result.tryGet { asA(MyBusinessObject::class) }) { // data: MyBusinessObject?
                    null -> println("Could not convert to MyBusinessObject")
                    else -> println("Data at $path are: $data")
                }
            }
            is WebcomResult.Failure -> println("Could not read data at $path: ${it.error.message}")
        }
    }
    
    // REAL-TIME SUBSCRIBE TO DATA
    manager.node(path).subscribe(Value.Changed::class) {
        when (it) { // it: Notification<DataEvent.Value.Changed>
            is Value.Changed -> println("New value available at $path: ${it.value.asNative}")
            is Canceled -> println("The subscription at $path has been stopped")
            is DatasyncEvent.Revoked -> println("The subscription at $path has been revoked by the back end: ${it.error.message}")
        }
    }
    
    // WRITE DATA
    manager.node(path).set(MyBusinessObject("propertyA", true, 42)) {
        when (it) {
            is WebcomResult.Success -> println("Succeeded writing data")
            is WebcomResult.Failure -> println("Failed writing data")
        }
    }
}

See the complete API reference for more details.

↑ ↑