Tutorial: Watch data acknowledgement

Tips and Tricks Watch data acknowledgement

How to watch the acknowledgement of some data

Usually, watching the acknowledgement of some data cannot consist in simply subscribing to the “Value Acknowledgement” and/or “Child Acknowledgement” events (see Subscribing to changes). Indeed, the Webcom SDK API doesn't enable to subscribe to these events alone, and other raised events may convey data values that are already acknowledged (the corresponding received notifications provide a field or property to check it). In this case, such data will never raise a “Value Acknowledgement” or “Child Acknowledgement” event.

Therefore, the right technique is to subscribe to both “Value Change” and “Value Acknowledgement” events, or to all the child-related events (including “Child Acknowledgement”).

Suppose we want to share the title of a contact directory between several users and that each user is allowed to edit it anytime. When edited, we display it in gray as long as it is not acknowledged by the Webcom back end, and we change its color to black as soon as it is acknowledged.

// const app = Webcom.App("<your-app>"); // UNCOMMENT if you haven't yet an instance of your app!
const database = app.serverlessDb;
// Reference to the title of our contact directory
const titleNode = database.rootNode.relativeNode("title");
// We both track the ValueChange event and ask for acknowledgement notifications
titleNode.subscribe(
    Webcom.Event.ValueChange,
    Webcom.Callback(snapshot => displayTitle(snapshot.val(), snapshot.acked)).includeAcknowledgements()
);

/**
 * Displays the given `title` in the acknowledged or not acknowledged state along the given `acknowledged` value.
 * @param {string} title
 * @param {boolean} acknowledged
 */
function displayTitle(title, acknowledged) {
    // some code
}

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

/**
 * Displays the given [title] with an acknowledgment status given by [acknowledged].
 */
fun displayTitle(title: String, acknowledged: Boolean) {
    // some code
}

val app = WebcomApplication.default
val manager = app.datasyncService.createManager()
val titleNode = manager / "title" // Reference to the title of our contact directory
val options = SubscriptionOptions(includesAcknowledgements = true)
titleNode.subscribe(Value.Changed::class, options = options) { // it: Notification<Value.Changed>
    if (it is Notification.DataNotification) {
        displayTitle(
            title = it.data.value.asString,
            acknowledged = it.data.value.acknowledged)
    }
}

let app = Webcom.defaultApplication
let manager = app.datasyncService.createManager()
let titleNode = manager / "title"

// We track value events INCLUDING acknowledgements
titleNode?.subscribe(to: .value(change: true, acknowledgement: true)) { event in
    displayTitle(title: event.value.asString, isAcknowledged: event.value.isAcknowledged)
}

func displayTitle(title: String?, isAcknowledged: Bool) {
    // some code
}

In this way, when a user changes the title on her/his device, it will be grayed until the back end acknowledges it (this may last if the device is offline). If another user on another device changes the title, then it will be updated directly in black on the first user's device (as the back end will notify it of an already acknowledged piece of data).

You can see a more detailed and more complex example, involving child-related events, here.

↑ ↑