Class: Webcom

Webcom(app, optionsopt)

A Webcom instance represents a particular location in the data tree of a Webcom application, which is specified by the app parameter.

Reading data is done using on() and once() methods. Writing data is done using set(), push(), update() and remove() methods. Browsing the data tree is done using Query#child, Query#parent or Query#root methods. See Browse data for more details.

Internally, a Webcom instance opens a web-socket connection to the Webcom back end for the requested application, unless the {goOnline:false} option is passed to the constructor. All Webcom instances on the same application share the same web-socket connection as well as the same authentication state. Consequently, you cannot authenticate several users on the same application.

Constructor

new Webcom(app, optionsopt)

Constructs a Webcom instance.

Parameters:
Name Type Attributes Description
app string | WebcomApp

The Webcom application, which this instance of Webcom must connect to.
If no specific hosting Webcom platform is required, then app can be the name of the application (on the Webcom production platform) given as a string. Otherwise, the app parameter must be a WebcomApp object that is built using the Webcom.App method.

options Object <optional>

Startup options. Note that these options are taken into account only on the first call to the Webcom constructor for a given app.

Properties
Name Type Attributes Description
persist boolean <optional>

Deprecated. Use DatasyncService.persist instead.

goOnline boolean <optional>

Deprecated. Use DatasyncService.connect instead.

DatasyncService DatasyncService.Options <optional>

Options of the DatasyncService attached to this Webcom instance. The actually applied options can be later retrieved by getting the DatasyncService#options property of the Webcom#datasync member.

Example
// Get a reference to the "contacts" application
var ref = new Webcom('contacts');

Extends

Members

(static) Event :EventDescriptor

Convenient link to the EventDescriptor class. This property is intended to access the EventDescriptor.ValueChange and EventDescriptor.Child static properties that make it possible to create instances of EventDescriptor.

Type:
Since:
  • 2.10

(static) Log :LogManager

Gets the LogManager API to control logs produced by the Webcom SDK.

Type:
Since:
  • 2.11

authenticator :AuthenticationService

Authentication service that manages this instance.

Type:
Overrides:

authState :AuthenticationService.State

Returns the current authentication state based on the Webcom Authentication Service model.

Type:
Since:
  • 2.8
Deprecated:
  • use the currentState property of WebcomBase.authenticator instead.

datasync :DatasyncService

Datasync service that manages this instance.

Type:
Overrides:

Methods

(static) App(appId, pfopt) → {WebcomApp}

Creates an instance of WebcomApp.

Parameters:
Name Type Attributes Default Description
appId string

The identifier of the Webcom application the WebcomApp object to be created will refer to.

pf string <optional>
"io.datasync.orange.com"

Authority of the Webcom platform that hosts the referred application. This parameter is intended for advanced usages, typically for testing purposes. If needed, use the following syntax: {protocol}?{host}(:{port})?

Since:
  • 2.8
Returns:
Type
WebcomApp

(static) AuthenticationService(app, options) → {AuthenticationService}

// TODO DOC

Parameters:
Name Type Description
app WebcomApp
options Object
Since:
  • 2.11
Returns:
Type
AuthenticationService

(static) avatarURL(user) → {string}

Get the user's avatar URL (if known) from the identity referred to by an authentication state.

Parameters:
Name Type Description
user

The auth data passed to an authentication callback.

Since:
  • 2.8
Returns:

the user's avatar URL if known or undefined otherwise

Type
string

(static) pushIdToDateTime(id) → {number}

Retrieves the date time associated with a node identifier generated by the Webcom#push method.
If the given identifier is not generated by the Webcom#push method, the result is indeterminate, generally a negative number.

Parameters:
Name Type Description
id string

The identifier, which to retrieve the date from.

Since:
  • 2.8
Returns:

The date time associated with the given identifier, expressed in milliseconds since Unix Epoch.

Type
number

(static) Webhook(identifier, context) → {Webhook}

Creates an instance of Webhook notification target, which is intended to be used with the Webcom#subscribe method.

Parameters:
Name Type Description
identifier string

The identifier of webhook defined in the Webcom developer console, which will be targeted by all further events notified to this target.

context string

A customized string, which will be attached to all further events notified to this target.

Since:
  • 2.10
Returns:
Type
Webhook

addAccount(provider, details, messageopt) → {Promise}

Creates a new identity managed by the Webcom Authentication Service.

Parameters:
Name Type Attributes Description
provider string

The internal provider to use to create the identity. Currently only "password" and "phone" (resp. for email-based and phone-based identities) are supported.

details Object

The details associated with the identity to create.

Properties
Name Type Attributes Description
id string

The identifier of the identity to create. For an email-based identity, it is an email address. For a phone-based identity, it is the MSISDN of a phone device able to receive SMS (without the "+" prefix).

password string

(email-based identities only)
The password associated to the email-based identity to create.

displayName string <optional>

A human-readable display name for the identity to create. This piece of information can be further retrieved within the displayName attribute of the auth parameter received by the authentication callbacks.

profile Object <optional>

A user-profile structure for the identity to create. This piece of information can be further retrieved within the providerProfile attribute of the auth parameter received by the authentication callbacks.

message Object <optional>

The parameters to apply to the verification message to be sent to the user.

Properties
Name Type Attributes Default Description
template string <optional>
"create"

The identifier of the verification message to send to the user. It must be picked among the template messages defined in the Webcom developer console.

sender string <optional>

(phone-based identities only)
The identifier of the SMS sending implementation to use to send the verification message to the user (the implementations must be set up in the Webcom developer console).

locale string <optional>

The locale of the verification message to send to the user (e.g. en for English whatever its variant, en_US for the american English, etc.). It must be in the ll_CC format, where ll is the ISO 639 alpha-2 code for the language and CC is the ISO 3166 alpha-2 code for the country variant.

Since:
  • 2.6.2
Deprecated:
Returns:

A promise that will be resolved once the identity creation successfully completed. In case of success (reps. failure), the resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.
Note that the just created identity is in the "unverified" state and cannot be used to sign a user in until it is verified. To do so, the user will receive a token or a code on the specified email address or MSISDN, which must be passed back to the Webcom#verifyIdentity method.

Type
Promise

addAuthCallback(callback) → {AuthenticationService.authCallback}

Adds an authentication callback function to the set of functions subscribed to changes of the authentication state. This function will be (asynchronously) called with the current authentication state, and then each time the authentication state changes.

Parameters:
Name Type Description
callback AuthenticationService.authCallback

the callback function to add.

Since:
  • 2.8
See:
Returns:

the added callback function. Note that it is useful to keep a reference on this function as soon as you need to remove it from the subscribed functions using the Webcom#removeAuthCallback method.

Type
AuthenticationService.authCallback

addIdentity(provider, details, messageopt) → {Promise}

Creates a new identity managed by the Webcom Authentication Service. If the Webcom#useCurrentContextForNextAuthOperation method is called just before this method, then the new identity is bound to the Webcom account of the currently authenticated user. Otherwise (or if no user is currently authenticated), the new identity is bound to a new Webcom account (to be created at the same time). Currently, Webcom is able to manage email- and phone-based identities.

Parameters:
Name Type Attributes Description
provider string

The internal provider to use to create the identity. Currently only "password" and "phone" (resp. for email-based and phone-based identities) are supported.

details Object

The details associated with the identity to create.

Properties
Name Type Attributes Description
id string

The identifier of the identity to create. For an email-based identity, it is an email address. For a phone-based identity, it is the MSISDN of a phone device able to receive SMS (without the "+" prefix).

password string

(email-based identities only)
The password associated to the email-based identity to create.

displayName string <optional>

A human-readable display name for the identity to create. This piece of information can be further retrieved within the displayName attribute of the auth parameter received by the authentication callbacks.

profile Object <optional>

A user-profile structure for the identity to create. This piece of information can be further retrieved within the providerProfile attribute of the auth parameter received by the authentication callbacks.

message Object <optional>

The parameters to apply to the verification message to be sent to the user.

Properties
Name Type Attributes Default Description
template string <optional>
"create"

The identifier of the verification message to send to the user. It must be picked among the template messages defined in the Webcom developer console.

sender string <optional>

(phone-based identities only)
The identifier of the SMS sending implementation to use to send the verification message to the user (the implementations must be set up in the Webcom developer console).

locale string <optional>

The locale of the verification message to send to the user (e.g. en for English whatever its variant, en_US for the american English, etc.). It must be in the ll_CC format, where ll is the ISO 639 alpha-2 code for the language and CC is the ISO 3166 alpha-2 code for the country variant.

Since:
  • 2.8
See:
Returns:

A promise that will be resolved once the identity creation successfully completed. In case of success (reps. failure), the resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.
Note that the just created identity is in the "unverified" state and cannot be used to sign a user in until it is verified. To do so, the user will receive a token or a code on the specified email address or MSISDN, which must be passed back to the Webcom#verifyIdentity method.

Type
Promise

auth(cred, onCompleteopt)

Authenticates the user using a (already available) Webcom authentication token.

Parameters:
Name Type Attributes Description
cred String

The Webcom authentication token to use

onComplete AuthenticationService.authCallback <optional>

Callback function to be called when the authentication completes.

Deprecated:

authAnonymously(onCompleteopt) → {Promise}

Authenticates the user using a temporary account (to be lost at next sign out or at authentication token expiration) with no explicit credentials.

Parameters:
Name Type Attributes Description
onComplete AuthenticationService.authCallback <optional>

Callback function to be called when the authentication completes.
Deprecated: Consider rather using the returned Promise.

Since:
  • 1.1
See:
Returns:

The authentication is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.

Type
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// Anonymously log the user in
ref.authAnonymously().then(function(auth) {
  console.log("User logged in, with UID", auth.uid);
});
// ==> ends up in calling authentication callbacks previously registered using resume()

authInternally(provider, credentials) → {Promise}

Authenticates the user using a given Webcom internally managed authentication method among:

  • Email-based authentication, with a personal password,
  • Phone-base authentication, with a one time password (OTP). In this case, an OTP must be sent to the user beforehand using the Webcom#sendOtp method and the returned challenge identifier must be kept (see the credentials.challenge parameter).
Parameters:
Name Type Description
provider string

The authentication method to use: "password" for email-based authentication or "phone" for phone-based authentication.

credentials Object

The user's credentials. Their content depends on the chosen authentication method.

Properties
Name Type Attributes Description
id string

The identifier of the user's identity. For email-based authentication, it is her⋅his email address, for phone-based authentication, it is her⋅his MSISDN (without the "+" prefix, eg: "33612345678").

challenge string <optional>

(mandatory for phone-based authentication only)
The challenge identifier associated with the one time password sent to the user to sign in.

password string

The personal password of the user (for email-based authentication) or the one time password received by the user on her⋅his mobile phone (for phone-based authentication)

Since:
  • 2.8
See:
Returns:

The authentication is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.

Type
Promise

authWithCustomProvider(provider, credentials, onCompleteopt) → {Promise}

Authenticates the user using credentials provided by a third-party ad-hoc identity provider.

Parameters:
Name Type Attributes Description
provider string

Identifier of the custom provider to use.

credentials string

Credentials for the user to authenticate, to be supplied by the 3rd-party identity provider.

onComplete AuthenticationService.authCallback <optional>

Callback function to be called when the authentication completes.
Deprecated: Consider rather using the returned Promise.

Since:
  • 2.2.2
See:
Returns:

The authentication is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.

Type
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// Log the user in, using a 3rd-party identity provider
ref.authWithCustomProvider("myprovider", "theprovidedcredentialsfortheusertoauthenticate").then(function(auth) {
  console.log("User logged in, with UID", auth.uid);
});
// ==> ends up in calling authentication callbacks previously registered using resume()

authWithOAuth(provider, optionsopt, onCompleteopt) → {Promise}

Authenticates the user using a 3rd-party OAuth2 provider.

Parameters:
Name Type Attributes Description
provider string

The OAuth2 provider to use. Currently supported providers are:

options Object <optional>

The authentication options to use, with the following properties:

Properties
Name Type Attributes Default Description
scope string <optional>

The OAuth2 scope requested to OAuth2 provider. This value is provider-specific and documented in the OAuth API of the provider.
If not set, the minimal scope is used (see Default Scope). This parameter is not relevant when the mode parameter equals "code".

mode string <optional>
popup

Currently 3 authentication modes are supported:

  • "popup": the calling window opens a popup window to play the OAuth2 authorization call-flow and closes it when completed,
  • "redirect": the calling window is redirected to the OAuth2 provider authentication portal and will be reloaded at the end of the authorization call-flow.
  • "code": this mode is relevant when using an OAuth2 provider-specific SDK to play the authorization call-flow and that SDK returns an OAuth2 authorization code. In this case, the returned code must be specified in the code parameter.
code string <optional>

The OAuth2 authorization code to use when the mode parameter equals "code". This parameter is not relevant otherwise.

state string <optional>

The OAuth2 state parameter to use when the mode parameter equals "code". This parameter is not relevant otherwise.

onComplete AuthenticationService.authCallback <optional>

Callback function to be called when the authentication completes.
Deprecated: Consider rather using the returned Promise.

Since:
  • 1.3
See:
Returns:

The authentication is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.

Type
Promise
Examples
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// Log the user in with Orange France using a popup
ref.authWithOAuth('orange');
// ==> ends up in calling authentication callbacks previously registered using resume()
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// Log the user in with Facebook using redirection
ref.authWithOAuth('facebook', {mode: 'redirect'});
// ==> ends up in reloading the page
//     the authentication callbacks will be then called as soon as registered using resume()
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// Log the user in with Google using an authorization code (returned by the Google SDK)
ref.authWithOAuth('google', {mode: 'code', code:'XXX...XXX'});
// ==> ends up in calling authentication callbacks previously registered using resume()

authWithPassword(credentials, onCompleteopt) → {Promise}

Authenticates the user using her⋅his email and personal password.

Parameters:
Name Type Attributes Description
credentials Object

The user's credentials.

Properties
Name Type Description
email String

The user's email address.

password String

The user's personal password.

onComplete AuthenticationService.authCallback <optional>

Callback function to be called when the authentication completes.
Deprecated: Consider rather using the returned Promise.

Deprecated:
Returns:

The authentication is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.

Type
Promise

authWithPhone(credentials) → {Promise}

Authenticates the user using her⋅his MSISDN and a one time password

Parameters:
Name Type Description
credentials Object

The user's credentials.

Properties
Name Type Description
id string

The user's MSISDN (without the "+" prefix, eg: "33612345678")

challenge string

The challenge identifier associated with the one time password sent to the user to sign in.

password string

The one time password received by the user on her⋅his mobile phone

Since:
  • 2.6.2
Deprecated:
Returns:

The authentication is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.

Type
Promise

authWithToken(token, onCompleteopt) → {Promise}

Authenticates the user using a (already available) Webcom authentication token. This method is mainly intended for Node.js back end.

Parameters:
Name Type Attributes Description
token String

The Webcom authentication token to use

onComplete AuthenticationService.authCallback <optional>

Callback function to be called when the authentication completes.
Deprecated: Consider rather using the returned Promise.

Since:
  • 1.3
Returns:

The authentication is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.

Type
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// Log the user in with a custom-made Webcom authentication token
ref.authWithToken('<THE-TOKEN>').then(function(auth) {
  console.log("User logged in, with UID", auth.uid);
});
// ==> ends up in calling authentication callbacks previously registered using resume()

changePassword(email, oldPassword, newPassword, onCompleteopt) → {Promise}

Changes the password of an existing email-based identity.

Parameters:
Name Type Attributes Description
email String

The email of the identity, the password of which has to be updated

oldPassword String

The current password of the identity

newPassword String

The new password to set

onComplete AuthenticationService.authCallback <optional>

A 1-argument callback function that is called after the password change completion, which receives an Error object if it has failed or null otherwise.

Returns:
Type
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// Change the password associated with "john@webcom.com" identity
ref.changePassword("john@webcom.com","pwd","newPwd", function(error) {
  if (error) {
    switch (error.code) {
      case "INVALID_CREDENTIALS":
        console.log("The email doesn't exist or the current password is incorrect!");
        break;
      case "TOO_WEAK_PASSWORD":
        console.log("The new password is not strong enough!");
        break;
      default:
        console.log("The password change failed: " + error.message);
    }
  } else {
    console.log("Password changed successfully!");
  }
});

child(pathString) → {Webcom}

Gets a Webcom instance that refers to a specific data node within the application data tree, specified as a relative path to the data node referred to by this Query instance.

Parameters:
Name Type Description
pathString string

Data path, relative to the location of this Query instance:

  • It may include several segments separated by slashes ("/")
  • Path is always interpreted relatively to the current data node, even with a leading slash
  • Path-segments "." and ".." are interpreted as "same node" and "parent node". Warning: ".." on the root data node returns itself (and not null as the Query#parent method)
  • Path-segments starting with "#" or ".hash." generate hashed-paths, with 3 additional sub-levels, which make it possible to handle large lists of items (see Manage long lists)
  • Path-segments starting with ".list." give a hint to the Webcom back end that these nodes are intended to have many children (as a list) so that it optimises the individual retrieval of their children, preventing retrieving the nodes as a whole when the data of all their children become too big
Overrides:
Returns:

A Webcom instance that refers to the specified path.

Type
Webcom
Example
// Get a reference to the "friends" data node
var ref = new Webcom("contacts").child("friends");

var johnRef = ref.child("john");
console.log(johnRef.name());
// ==> "/https/io.datasync.orange.com/contacts//friends/john"

var maryRef = ref.child("/mary");
console.log(maryRef.toString());
// ==> "/https/io.datasync.orange.com/contacts//friends/mary"

var maryRef2 = johnRef.child("../mary");
console.log(maryRef2.toString());
// ==> "/https/io.datasync.orange.com/contacts//friends/mary"

var nameThenLastRef = johnRef.child("name").child("last");
console.log(nameThenLastRef.toString());
// ==> "/https/io.datasync.orange.com/contacts//friends/john/name/last"

var lastNameRef = johnRef.child("name/last");
console.log(lastNameRef.toString());
// ==> "/https/io.datasync.orange.com/contacts//friends/john/name/last"

var rootRef = ref.child("../..");
console.log(rootRef.toString());
// ==> "/https/io.datasync.orange.com/contacts/"

var hashedRef = ref.child("#john");
console.log(hashedRef.toString());
// ==> "/https/io.datasync.orange.com/contacts//friends/.list.pR/3a/fH/john"

createUser(details, onCompleteopt) → {Promise}

Creates a new Webcom account bound to an email/password identity.

Parameters:
Name Type Attributes Description
details Object

The details associated with the account to create.

Properties
Name Type Attributes Description
email String

The email associated with the account to create.

password String

The password associated with the account to create.

profile Object <optional>

A user-profile structure associated with the account to create. This piece of information can be further retrieved within the providerProfile attribute of the auth parameter received by the authentication callbacks.

onComplete AuthenticationService.authCallback <optional>

Callback function to be called when the account creation completes.
Deprecated: Consider rather using the returned Promise.

Deprecated:
Returns:

The account creation is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.

Type
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// Create a new account for this application
ref.createUser({
  email: "john@webcom.com",
  password: "pwd"
}, function(error, auth) {
  if (error) {
    switch (error.code) {
      case "EXISTING_IDENTITY":
        console.log("Email already in use!");
        break;
      case "INVALID_EMAIL":
        console.log("Email format is not valid!");
        break;
      default:
        console.log("Account creation failed: " + error.message);
    }
  } else {
    console.log("Successfully created account with UID:" + auth.uid + ", it must be confirmed before use!");
  }
});

endAt(nameopt) → {Query}

Creates a Query object that returns children beginning at a specific ending point.

Parameters:
Name Type Attributes Description
name string <optional>

The child name to end at

Since:
  • 2.2
Overrides:
Returns:
  • Generated query
Type
Query
Example
// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

// Display friends whose names (keys) come before john
ref.endAt("john").on("value", function(snapshot){
     console.log(snapshot.val());
});

equalTo(nameopt) → {Query}

Creates a Query object that returns children matching a specific value.

Parameters:
Name Type Attributes Description
name string <optional>

The child name to match for.

Since:
  • 2.2
Overrides:
Returns:
  • Generated query
Type
Query
Example
// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

// Display friends whose names (keys) is exactly john
ref.equalTo("john").on("value", function(snapshot){
     console.log(snapshot.val());
});

get() → {Promise.<DataSnapshot>}

Gets the data at the data node referred to by this Query instance.

This method works asynchronously. It will actually involve an exchange with the Webcom back end only if the requested data are not in the local cache.

Since:
  • 2.14
Overrides:
Returns:

A promise that will be resolved with the read data.

Type
Promise.<DataSnapshot>
Example
// Get a reference on the "friends" node of the "contacts" application
const friendsNode = new Webcom("contacts").child("friends");
// Read the value of this node
friendsNode.get()
    .then(data => {
        console.log("The 'friends' data are:", JSON.stringify(data.val()));
        console.log("They are", data.acknowledged() ? "acknowledged" : "not yet acknowledged", "by the back end");
    })
    .catch(error => console.log("Could not read data:", error.message);

getCache() → {DataSnapshot}

Returns (synchronously) the value stored in the local cache at the data node represented by this Query instance. The returned value is of the same type than the one passed to watch callbacks.

Since:
  • 2.15
Overrides:
Returns:
Type
DataSnapshot

goOffline()

Forces disconnection of the websocket managed by this Webcom instance from the Webcom server and disables the retry connection feature. The websocket will be not restablished until Webcom#goOnline is called.

Deprecated:

goOnline()

Force reconnection of the websocket managed by this Webcom instance to the Webcom server and enables the retry connection feature.

Deprecated:

increment(step, startValueopt) → {Promise.<number>}

Atomically increments the value at the data node referred to by this Webcom instance.

"Atomically" means that this operation is robust to concurrent increment operations by many clients. It is guaranteed that if n clients perform an increment at the same time, then the value of the data node ends in being incremented by n×step, that is, none of the concurrent operations can overwrite one another.

If the data node has no value, then the increment acts as if it equals the given startValue.

If the data node has a non-numeric value, then the increment fails.

If you need to perform a more complex operation in an atomic way, use the Webcom#transaction method.

Parameters:
Name Type Attributes Default Description
step number

The step to add to the current data node value.

startValue number <optional>
0

The default starting value of the data node if it has no value when the increment is performed.

Since:
  • 2.13
Returns:

The resulting value of the increment operation.
Note that the returned value may not be synchronized with the actual value of the data node, especially if other clients perform write operations at the same time. Use rather subscriptions to watch the actual value of a data node.

Type
Promise.<number>

limit(lim) → {Query}

Create Query object to limit the number of children.

Parameters:
Name Type Description
lim number

Number of items

Since:
  • 2.2
Overrides:
Returns:

new limited Query object.

Type
Query
Examples

Last

// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

var lastFriends = ref.endAt().limit(5);
// Display the 5 last friends
lastFriends.on("value", function(snapshot){
     console.log(snapshot.val());
});

First

// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

var lastFriends = ref.startAt().limit(5);
// Display the 5 first friends
lastFriends.on("value", function(snapshot){
     console.log(snapshot.val());
});

First starting at some key

// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

var lastFriends = ref.startAt("john").limit(5);
// Display friends whose names (keys) come after john display the following 5
lastFriends.on("value", function(snapshot){
     console.log(snapshot.val());
});

logout(onCompleteopt) → {Promise}

Signs the currently authenticated user out.

Parameters:
Name Type Attributes Description
onComplete function <optional>

A 1-argument callback function that is called after the log-out, which receives an Error object if it has failed or null otherwise.
Deprecated: Consider rather using the returned Promise.

Returns:

A promise that will be resolved (with no value) once the user is properly signed out.

Type
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// Register an authentication callback
ref.resume(myAuthCallback);
// Log the current user out ==> ends up in calling myAuthCallback
ref.logout(function (error) {
  if (error) {
    console.log("The log-out failed: " + error.message);
  } else {
    console.log("Logged out successfully!");
  }
});

name() → (nullable) {string}

Returns the name of the data node this Query instance refers to.

Overrides:
Returns:

The name of the data node or null if this instance refers to the root node of the application.

Type
string
Example
// Get a reference to the "john" data node
var ref = new Webcom("contacts").child("friends/john");

console.log(ref.name());
// ==> "john"

console.log(ref.child("name").name());
// ==> "name"

console.log(ref.root().name());
// ==> null

off(eventTypesopt, callbackopt, contextopt)

Unwatches data changes at the data node referred to by this Query instance.

It actually unregisters a callback function (or all ones) previously registered on the data node referred to by this Query instance using the Query#on method.

As a side effect, all data previously watched will be removed from the local cache. If you want to keep these data in the local cache in order to work offline for example, use the Query#offPreservingOfflineData method instead.

Note: unregistering all callback functions attached to a data node doesn't unregister callback functions attached to its child nodes. The Query#off method must be called on all the data nodes that the Query#on method has been called on.

Parameters:
Name Type Attributes Description
eventTypes string | Array.<string> <optional>

The type of event to unwatch. It can be either a single value among "value", "child_added", "child_changed" or "child_removed", or a list of them.
If not specified, all callbacks previously registered on the data node are unregistered.

callback Query~watchCallback <optional>

Reference to the callback function to unregister (previously passed to or returned by the Query#on method).
If not set, all callbacks of type eventTypes previously registered on the data node are unregistered.

context Object <optional>

Context object for callback binding, passed to previous call to Query#on.

Overrides:
Examples

Unregister a single callback

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("contacts").child("friends");

var onChange = ref.on("value", function(snapshot) {
  // your handler
});

// later...
ref.off("value", onChange);

Unregister several callbacks

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("contacts").child("friends");

var onChanged = function(snapshot) {
  // your first handler
});
var onAdded = function(snapshot) {
  // your second handler
});

ref.on("value", onChanged);
ref.on("child_added", onAdded);

// later...

// Unregister all callback functions from ref...
ref.off();
// ...or all callback function associated to a specific kind of event
ref.off("value"); // onChanged is unregistered while onAdded remains registered

offPreservingOfflineData(eventTypeopt, callbackopt, contextopt)

Unwatches data changes at the data node referred to by this Query instance, similarly to the Query#off method. The difference is that this method additionally preserves the previously watched data within the local cache and maintains them up-to-date.

As a consequence, unwatched data remain available if the network becomes down, and it is possible to use them offline. As soon as the network becomes up, they will be automatically re-synchronised.

In order to definitely remove some unwatched data from the local cache, use the DatasyncService#cleanOfflineData method.

Parameters:
Name Type Attributes Description
eventType string | Array.<string> <optional>

The type of event to unwatch. It can be either a single value among "value", "child_added", "child_changed" or "child_removed", or a list of values among the same constants.
If not specified, all callbacks previously registered on the data node are unregistered.

callback Query~watchCallback <optional>

Reference to the callback function to unregister (previously passed to or returned by the Query#on method).
If not set, all callbacks of type eventType previously registered on the data node are unregistered.

context Object <optional>

Context object for callback binding, passed to previous call to Query#on.

Since:
  • 2.11
Overrides:
Deprecated:

on(eventTypes, callback, completionCallbackopt, contextopt) → {Query~watchCallback}

Watches data changes at the data node referred to by this Query instance.

It actually registers a callback function on the data node referred to by this Query instance for a given type of event to watch or a given set of types of events to watch.

The specified callback may be called initially (when the on method is called) with respect to the data currently stored at this node (depending on the requested event type). And then, it will be called whenever the data change. The notifications can be stopped using the Query#off method.
Several kinds of callback are available depending on the kind of event to watch:

  • value event

    The callback is called initially once with the current data.
    It is then called again each time the data (stored a this node or any sub-node) change.

    The DataSnapshot passed to the callback refers to the new data stored at the data node referred to by this Query instance.
    The prevChildName argument passed to the callback is not used and remains undefined.

  • value_ack event

    The callback is not initially called.
    It is then called each time the value at this data node is acknowledged by the Webcom back end. Note that if both the value and the acknowledgement status change, then the value event is raised instead.

    As with the value event, the DataSnapshot passed to the callback refers to the value of the data node and the prevChildName is not used.

  • child_added event

    The callback is called initially once for each current child node of this node.
    It is then called again each time a new data child is added to this node.

    The DataSnapshot passed to the callback refers to the new data stored at the corresponding child data node.
    The prevChildName argument passed to the callback refers to the name of the sibling child node that precedes the added child node in the data tree structure (following key order), or null if the added child node is the first child of the data node referred to by this Query instance.

  • child_changed event

    The callback is not initially called.
    It is then called each time the value of one of the data children changes (excluding child additions and removals).

    The DataSnapshot passed to the callback refers to the new data stored at the corresponding child data node.
    The prevChildName argument passed to the callback refers to the name of the sibling child node that precedes the changed child node in the data tree structure (following key order), or null if the changed child node is the first child of the data node referred to by this Query instance.

  • child_removed event

    The callback is not initially called.
    It is then called each time one of the data children is removed (or its value becomes null or it loses all of its children).

    The DataSnapshot passed to the callback refers to the old data stored at the corresponding child data node.
    The prevChildName argument passed to the callback is not used and remains undefined.

  • child_ack event

    The callback is not initially called.
    It is then called the value of a child of this data node is acknowledged by the Webcom back end. Note that if both the value and the acknowledgement status of the child change, then one of the child_added, child_removed or child_changed events is raised instead.

    The DataSnapshot passed to the callback refers to the value of the child node.
    The prevChildName argument passed to the callback is not used and remains undefined.

Note: data is first synchronized locally, so that if you set (using the set() method) some data locally after registering a watch callback, this callback will be called immediately. Later, when the synchronization with the server occurs, the callback will be possibly called again for acknowledgement notification, data update, or even for data deletion if the synchronization fails.

Parameters:
Name Type Attributes Description
eventTypes string | Array.<string>

The type of event to watch. It can be either a single value among "value", "value_ack", "child_added", "child_changed", "child_removed" or "child_ack", or a list of values among these constants.

callback Query~watchCallback

Callback function called when one of the watched events is raised.

completionCallback Query~completionCallback <optional>

Callback function called when the data node is no longer watched. This can result from either a cancelation from the app (by calling the Query#off method) or a revocation from the Webcom back end due to a permission loss (either the token of the authenticated user has expired or the security rules have denied the read permission). In case of cancelation, the callback is called with null, in case of revocation it is called with an Error object. In addition, the value returned by this callback controls how the corresponding data in the local cache is kept or deleted.
Note 1: In both cases, the watch callback function is automatically unregistered and will no longer be called.
Note 2: the completionCallback is called for a cancelation only if the underlying Webcom instance has been constructed with the DatasyncService.completeSubscriptionOnCancelation option set to true.

context Object <optional>

Context object for binding of the callback functions

Overrides:
Returns:

A reference to the callback function provided in the callback parameter. It is intended to be passed to the Query#off method, especially when the callback parameter is given as an inline function.

Type
Query~watchCallback
Examples

Value

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("contacts").child("friends");

// This callback is called only when some data change under the "friends" node
ref.on("value", function(snapshot) {
  console.log("New friends value is: " + JSON.stringify(snapshot.val()));
});

Child Added

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("contacts").child("friends");

// This callback is called only when a new child is added to the "friends" node
ref.on("child_added", function(snapshot, prevChildName) {
  console.log("New child for friends: " + snapshot.name() + " -> " + JSON.stringify(snapshot.val()));
  if (prevChildName) {
    console.log("This new child comes after " + prevChildName);
  } else {
    console.log("This new child is the only one");
  }
});

Child Changed

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("contacts").child("friends");

// This callback is called only when the value of an existing child of the "friends" node changes
ref.on("child_changed", function(snapshot, prevChildName) {
  console.log("The " + snapshot.name() + " child has changed value to: " + JSON.stringify(snapshot.val()));
  if (prevChildName) {
    console.log("This child comes after " + prevChildName);
  } else {
    console.log("This child is the only one");
  }
});

Child Removed

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("contacts").child("friends");

// This callback is called only when a child of the "friends" node is removed
ref.on("child_removed", function(snapshot) {
  console.log("The " + snapshot.name() + " child has been removed, its value was: " +
    JSON.stringify(snapshot.val()));
});

once(eventType, callback, cancelCallbackopt, contextopt)

Watches the next data change at the data node referred to by this Query instance.

This method is similar to Query#on, except it automatically unregisters the given callback function from the data node referred to by this Query instance as soon as it is called. In other words, the given callback function will be called no more than once.

With the "value" event type, this method makes it possible to read (asynchronously) the data stored at a given data node. Other event types are useless with this method.

Parameters:
Name Type Attributes Description
eventType string

The type of event to watch. Although the same event types as for the Query#on method are available, on the "value" one is really useful.

callback Query~watchCallback

Callback function called when the specified event occurs.

cancelCallback Query~completionCallback <optional>

Callback function called when the authenticated user loses read permission at the data node referred to by this Query instance. In this case, the watch callback function is automatically unregistered and will no longer be called.

context Object <optional>

Context object for callback binding

Overrides:
Deprecated:
Examples
// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("contacts").child("friends");

// Read the value of the "friends" node
ref.once("value", function(snapshot) {
  console.log("The value of the " + snapshot.name() + " node is: " + JSON.stringify(snapshot.val()));
});
// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("contacts").child("friends");

// Check the read permission on the "friends" node
ref.once("value", function() {}, function(error) {
  console.log("Insufficient read permission");
});

onDisconnect() → {OnDisconnect}

Gets an instance of OnDisconnect, which refers to the data node referred to by this Webcom instance.

Returns:
Type
OnDisconnect
Example
// Get a reference to the "john" data node
var ref = new Webcom("contacts").child("friends/john");

// Create a disconnection listener
var disconnectRef = ref.child("online").onDisconnect().set(false);

parent() → {Webcom}

Gets a Webcom instance that refers to the parent data node of the one referred to by this Query instance.

Overrides:
Returns:

A parent instance of this Query instance or null if the data node referred to by this Query instance has no parent.

Type
Webcom
Example
// Get a reference to the "friends" data node
var ref = new Webcom("contacts").child("friends");

var contactsRef = ref.parent();
console.log(contactsRef.toString());
// ==> "/https/io.datasync.orange.com/contacts/"

pathString() → {String}

Returns the path of the data node represented by this instance of Query.

Since:
  • 2.6.2
Overrides:
Returns:

The path of this data node, with path levels separated by "/" (slashes)

Type
String

persist() → {boolean}

Persists the data currently stored in the client local cache. This method has no effect if the Webcom instance that first established the connection to the Webcom server was created with the {persist: false} option (in this case, the method returns false). This data will the be restored in a further client establishing its first connection to the Webcom server passing the {persist: true} option to the Webcom constructor.

Since:
  • 2.6
Returns:

true if the data has been persisted or false otherwise

Type
boolean

push(valueopt, onCompleteopt) → {Webcom}

Adds a new child at the data node referred to by this Webcom instance. Its key is automatically generated, so that it is unique and lexicographically ordered after any previously generated key.

Parameters:
Name Type Attributes Description
value Object | string | number | boolean | null <optional>

The value of the new child to add. If not set, the new child is created without value.

onComplete function <optional>

A 2-argument callback function called after synchronization with the server. Its fist argument is filled with an Error object if an error occurred. Otherwise, its second argument is filled with a Webcom instance referring to the added child.

Returns:

A Webcom instance referring to the added child.

Type
Webcom
Examples
// Get a reference to the "john" data node
var ref = new Webcom("contacts").child("friends/john");

// Create a randomly generated unique child
var refPhone = ref.push();
console.log(refPhone.toString());
// ==> "/https/io.datasync.orange.com/contacts//friends/john/-Jjj6vK9L0NAd9JHusrd"

// Set a value on this new child
refPhone.set({number : "0123456789"});
var ref = new Webcom("contacts").child("friends/john");

// The same as the previous example, in a single operation
ref.push({number : "0123456789"});
var ref = new Webcom("contacts").child("friends/john");

// The same as the previous example, with a completion callback
ref.push({number : "0123456789"}, function(error, childRef) {
  if (error) {
    console.log("synchronisation error:", error);
  } else {
    console.log("synchronisation ok, created child is:", childRef.name());
  }
});

ref() → {Webcom}

Returns a Webcom reference associated to the data node referred to by this Query instance.

Overrides:
Returns:

The Webcom reference associated with this instance.

Type
Webcom
Example
// Get a reference to the "friends" data node
var ref = new Webcom("contacts").child("friends");

var query = ref.limit(2);
var refSameLocation = query.ref(); //ref === refSameLocation

registerAuthCallback(callback) → {AuthenticationService.authCallback}

Adds an authentication callback function to the set of functions subscribed to changes of the authentication state. Contrary to the Webcom#addAuthCallback method, this method doesn't initially call the added callback function with the current authentication state.

Parameters:
Name Type Description
callback AuthenticationService.authCallback

the callback function to add.

Since:
  • 2.1
Deprecated:
Returns:

the added callback function.

Type
AuthenticationService.authCallback

remove(onCompleteopt)

Removes data at the data node referred to by this Webcom instance.

Parameters:
Name Type Attributes Description
onComplete function <optional>

A 1-argument callback function called after synchronization with the server. Its argument is filled with an Error object if an error occurred or null otherwise.

Example
// Get a reference to the "john" data node
var ref = new Webcom("contacts").child("friends/john");

// Remove all data from the "john" data node
ref.remove();

removeAccount() → {Promise}

Deletes the Webcom account associated with the currently authenticated identity. This method deletes also all the identities associated with this account. In order to succeed, this sensible operation requires a fresh authentication. If the current authentication token is too old, then the operation fails, in this case you have to refresh the user authentication by authenticating her⋅him afresh explicitly before renewing the operation.

Since:
  • 2.6.2
See:
Returns:

The identity deletion is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. In case of succes, the resolve callback is called with no argument. In case of failure, the reject callback is called with the reason of the failure.

Type
Promise

removeAuthCallback(callbackopt) → {boolean}

Removes an authentication callback function from the set of functions subscribed to changes of the authentication state. As soon as this method returns, further changes of the authentication state will no longer result in calling the specified callback function(s).

Parameters:
Name Type Attributes Description
callback AuthenticationService.authCallback <optional>

the callback function to remove. Note that it must be a reference to a function previously added with Webcom#addAuthCallback (an inline function would not be recognized).
If not specified, this method removes all callback functions.

Since:
  • 2.8
See:
Returns:

true if the callback function to remove was found, or false otherwise

Type
boolean

removeIdentity() → {Promise}

Deletes the currently authenticated identity. This method doesn't delete the associated Webcom account unless there is no other identity associated with it. In order to succeed, this sensible operation requires a fresh authentication. If the current authentication token is too old, then the operation fails, in this case you have to refresh the user authentication by authenticating her⋅him afresh explicitly before renewing the operation.

Since:
  • 2.6.2
See:
Returns:

The identity deletion is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. In case of succes, the resolve callback is called with no argument. In case of failure, the reject callback is called with the reason of the failure.

Type
Promise

removeUser(email, password, onCompleteopt) → {Promise}

Removes an existing email-based identity.
Warning: this method doesn't remove the associated Webcom account.

Parameters:
Name Type Attributes Description
email String

The email of the identity to remove

password String

The password of the identity to remove

onComplete AuthenticationService.authCallback <optional>

A 1-argument callback function that is called after the email/password identity removal, which receives an Error object if it has failed or null otherwise.

Deprecated:
Returns:
Type
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// Remove the "john@webcom.com" identity
ref.removeUser("john@webcom.com", "pwd")
  .then(function() {
    console.log("Identity removed!");
  }).catch(function(error) {
    switch (error.code){
      case "INVALID_CREDENTIALS":
        console.log("The identity or the password is invalid!");
        break;
      default:
        console.log("The identity removal failed: " + error.message);
    }
  });

resume(callbackopt)

Resumes the authentication state (based on records from the local storage).

Parameters:
Name Type Attributes Description
callback AuthenticationService.authCallback <optional>

If set, registers additionally an authentication callback function to be called each time the authentication state changes.
Deprecated The usage of this parameter is strongly discouraged, use explicitly the Webcom#addAuthCallback method instead.

Deprecated:
  • This method no longer needs to be called

root() → {Webcom}

Gets a Webcom instance that refers to the data tree root of current Webcom application.

Overrides:
Returns:

A Webcom instance that refers to the root data node

Type
Webcom
Example
// Get a reference to the "john" data node
var ref = new Webcom("contacts").child("friends/john");

var rootRef = ref.root();
console.log(rootRef.toString());
// ==> "/https/io.datasync.orange.com/contacts/"

sendConfirmationEmail(email, onCompleteopt) → {Promise}

Sends an email with a link to confirm an email/password identity. This method is particularly useful when the user has not received the initial confirmation email sent when creating her/his account (using the Webcom#createUser method.

Parameters:
Name Type Attributes Description
email String

The email address of the identity to confirm, which the email must be send to

onComplete AuthenticationService.authCallback <optional>

A 1-argument callback function that is called after the sending of the confirmation email, which receives an Error object if it has failed or null otherwise.

Deprecated:
Returns:
Type
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// Send a confirmation email
ref.sendConfirmationEmail("john@webcom.com", function(error) {
  if (error) {
    switch (error.code) {
      case "INVALID_CREDENTIALS":
        console.log("The specified identity is invalid!");
        break;
      case "ALREADY_VERIFIED_IDENTITY":
        console.log("The specified identity is already confirmed");
        break;
      default:
        console.log("The sending of the confirmation email failed: " + error.message);
    }
  } else {
    console.log("Confirmation email successfully sent!");
  }
});

sendOtp(provider, id, messageopt) → {Promise}

Sends a one time password (OTP) to a user through a given identity. This method is particularly useful before calling the Webcom#authInternally method, which may requires a temporary password to complete depending on the chosen identity provider.

Parameters:
Name Type Attributes Description
provider string

The provider associated with the identity, which to send the OTP to. Currently, possible values are "password" (for email-based identities) or "phone" (for phone-based identities)

id string

The identifier of the identity, which to send the OTP to

message Object <optional>

The parameters to apply to OTP message to be sent

Properties
Name Type Attributes Default Description
template string <optional>
"login"

The identifier of the OTP message to send to the user. It must be picked among the template messages defined in the Webcom developer console.

sender string <optional>

(phone-based identities only)
The identifier of the SMS sending implementation to use to send the OTP message to the user (the implementations must be set up in the Webcom developer console).

locale string <optional>

The locale of the OTP message to send to the user (e.g. en for English whatever its variant, en_US for the american English, etc.). It must be in the ll_CC format, where ll is the ISO 639 alpha-2 code for the language and CC is the ISO 3166 alpha-2 code for the country variant.

Since:
  • 2.6.2
Returns:

A promise that will be resolved once the OTP successfully sent. In case of success, the resolve callback is called with one parameter equal to the sent OTP identifier or challenge (given as a string). This identifier is required for further methods such as Webcom#authInternally.

Type
Promise

sendPasswordResetCode(provider, id, messageopt) → {Promise}

Sends a code to the user, which allows her⋅him to reset her⋅his password for a given Webcom internally manged identity. Currently, only email-based identities are supported (parameter provider equal to "password").

Parameters:
Name Type Attributes Description
provider string

The internal provider of the identity, which to send the password reset code to. Currently, only "password" is supported.

id string

The identifier of the identity, which to send the password reset code to.

message <optional>

The message template to use to send the password reset code

Properties
Name Type Attributes Default Description
template string <optional>
"password-reset"

The identifier of the message to send to the user. It must be picked among the template messages defined in the Webcom developer console.

locale string <optional>

The locale of the message to send to the user (e.g. en for English whatever its variant, en_US for the american English, etc.). It must be in the ll_CC format, where ll is the ISO 639 alpha-2 code for the language and CC is the ISO 3166 alpha-2 code for the country variant.

Since:
  • 2.6.2
Returns:

A promise that is resolved once the password reset code has been sent

Type
Promise

sendPasswordResetEmail(email, onCompleteopt) → {Promise}

Sends an email to the user of an email/password identity, with a link to reset the associated password. This method is intended to be used when the user has lost her/his password.

Parameters:
Name Type Attributes Description
email String

The email of the identity to reset

onComplete AuthenticationService.authCallback <optional>

A 1-argument callback function that is called after the sending of the password reset email, which receives an Error object if it has failed or null otherwise.

Deprecated:
Returns:
Type
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// Send a password reset email
ref.sendPasswordResetEmail("john@webcom.com", function(error) {
  if (error) {
    switch (error.code) {
      case "INVALID_CREDENTIALS":
        console.log("The specified identity is invalid!");
        break;
      default:
        console.log("The sending of the password reset email failed: " + error.message);
    }
  } else {
    console.log("Reset password email successfully sent!");
  }
});

sendVerificationCode(provider, id, messageopt) → {Promise}

Sends a code to the user, which makes it possible to verify one of her⋅his unverified identities internally managed by Webcom (i.e. email- and phone-based identities). This method fails on an already verified identity.

Parameters:
Name Type Attributes Description
provider string

The internal provider that manages the identity to verify. Current supported values are "password" (for email-based identities) and "phone" (for phone-based identities).

id string

The identifier of the identity to verify. It is either an email address (for email-based identities) or a MSISDN without the "+" prefix (for phone-based identities).

message <optional>

The message template to use to send the verification code to the user

Properties
Name Type Attributes Default Description
template string <optional>
"create"

The identifier of the verification message to send to the user. It must be picked among the template messages defined in the Webcom developer console.

sender string <optional>

(phone-based identities only)
The identifier of the SMS sending implementation to use to send the verification message to the user (the implementations must be set up in the Webcom developer console).

locale string <optional>

The locale of the verification message to send to the user (e.g. en for English whatever its variant, en_US for the american English, etc.). It must be in the ll_CC format, where ll is the ISO 639 alpha-2 code for the language and CC is the ISO 3166 alpha-2 code for the country variant.

Since:
  • 2.6.2
Returns:

A promise that will be resolved once the verification message successfully sent. In case of success, the resolve callback is passed a "challenge" string that must be used to eventually verify the identity using the Webcom#verifyIdentity method

Type
Promise

set(newVal, onCompleteopt)

(Over)writes data at the data node referred to by this Webcom instance.

Parameters:
Name Type Attributes Description
newVal Object | String | Number | Boolean | null

The value to write. If it is an Object, all children of the current data node are removed before writing this value. In order to merge existing children with the ones of the value to write, use update().

onComplete function <optional>

A 1-argument callback function called after synchronization with the server. Its argument is filled with an Error object if an error occurred or null otherwise.

Examples

Write a single value

// Get a reference to the "john" data node
var ref = new Webcom("contacts").child("friends/john");

// Overwrite first name and last name with "John" and "Doe" values
ref.child("name/first").set("John");
ref.child("name/last").set("Doe");

Write an object

// Get a reference to the "john" data node
var ref = new Webcom("contacts").child("friends/john");

// Define a callback to log the result
var onFinish = function(error) {
  if(error) {
    console.log("There is a problem...");
  } else {
    console.log("It's OK!");
  }
};
// Overwrite the "name" data node atomically
ref.child("name").set({first:"John",last:"Doe"}, onFinish);

shouldBeOnline() → {boolean}

Returns the current expected state of the Datasync websocket: true if it should be online (whatever the actual network state) or false if it should be offline. The actual state of the Datasync websocket may be monitored by subscribing to the ".info/connected" virtual node using the on() method.

Since:
  • 2.6.2
Deprecated:
Returns:

the current expected state of the Datasync websocket

Type
boolean

startAt(nameopt, nullable) → {Query}

Creates Query object that returns children beginning at a specific starting point.

Parameters:
Name Type Attributes Description
name string <optional>
<nullable>

The child name to start at. If omitted or null, the query iterate items from the upper ones in key order.

Since:
  • 2.2
Overrides:
Returns:

Generated query

Type
Query
Example
// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

// Display friends whose names (keys) come after john
ref.startAt("john").on("value", function(snapshot){
     console.log(snapshot.val());
});

subscribe(event, target) → {Promise.<Subscription>}

Subscribes to events that match a given description and are raised on the data node referred to by this Webcom instance. Such raised events will be notified to a given target. Currently only Webhook targets are available, however additional ones may become available in future versions.

This method requires to be authenticated. Read permissions required to watch specified data events will be evaluated in real-time by the Webcom back end according to the current authentication state at the time this method is called.

The resulting subscription may be further unsubscribed either by calling the Subscription#cancel method on the Subscription instance resolved by the Promise returned by this method, or by calling the Webcom#unsubscribe method (which doesn't need further a reference to the Subscription instance).

Parameters:
Name Type Description
event EventDescriptor

The descriptor of data events to subscribe to. Such descriptors must be created using the Webcom.Event property.

target Webhook

The target that will be notified when subscribed data events are raised on the current data node. Such targets must be created using the Webcom.Webhook static method.

Since:
  • 2.10
See:
Returns:

The returned Promise is resolved with a Subscription instance that represents the subscription created by this method. This instance provides methods that make it possible to either cancel the subscription or update the subscribed events.

Type
Promise.<Subscription>

toString() → {String}

Returns the absolute URL of the data node referred to by this Webcom instance.

Returns:

The absolute URL of this Webcom instance

Type
String
Example
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");

console.log(ref.toString());
// ==> "/https/io.datasync.orange.com/contacts/"

var johnRef = ref.child("friends/john");
console.log(johnRef.toString());
// ==> "/https/io.datasync.orange.com/contacts//friends/john"

var alfredRef = ref.child("friends/alfred:54");
console.log(alfredRef.toString());
// ==> "/https/io.datasync.orange.com/contacts//friends/alfred%3A54"

transaction(transactionUpdate, onCompleteopt, optionsopt)

Writes data atomically within a transaction at the data node referred to by this Webcom instance. This means the data will be actually written only if the data node is not modified by another client during the transaction. Otherwise, the transaction is retried (up to 25 times) until it can be completed safely without conflict.

If the transactionUpdate function consists in incrementing (or decrementing) the value of the data node, use rather the Webcom#increment method, which is more efficient in this case.

Parameters:
Name Type Attributes Default Description
transactionUpdate function

A 1-argument function that receives the current value of the data node and is expected to return either an undefined value to abort the transaction, or the new value to overwrite at the data node.
It may be called several times if the transaction performs retries.

onComplete function <optional>

A 3-argument function that is called after the transaction execution whatever its outcome (completed or aborted):

  • The first argument receives null if no error occurred during the transaction or an Error object otherwise.
  • The second argument is a Boolean indicating whether the transaction has completed (true) or has been aborted (false) because transactionUpdate returned an undefined value.
  • The third argument is a JSON or DataSnapshot object containing the resulting value of the data node (this value is passed even in case of error).
options Object <optional>
{}
Properties
Name Type Attributes Default Description
applyLocally boolean <optional>
true

If set to true, updates locally the data node value (and further calls the listeners on the data node) each time transactionUpdate is called, that is possibly many times if the transaction performs several retries.
If set to false, updates the data node value only once the transaction is completed.

valueFormat string <optional>
"json"

Sets the format of the value passed to the 1st parameter of the given transactionUpdate function:

  • With "json", the passed value is a JSON object representing the data node in raw format (ie. arrays occur as objects with 0, 1, 2... keys).
  • With "snapshot", the passed value is a DataSnapshot instance (like the one passed to the callback of the on function). In this case, you can use the val or rawVal methods to fit your needs.
Since:
  • 1.1
Examples

Toggle the value of a data node between 2 constants

// Get a reference to the "john" data node
var ref = new Webcom("contacts").child("friends/john");

ref.child("busy").transaction(current => {
  if (current) {
    return false;
  } else {
    return true;
  }
});

Write some data only if there is none

// Get a reference to the "john" data node
var ref = new Webcom("contacts").child("friends/john");

ref.transaction(current => {
  if (current === null) {  // there is no data at the "john" data node => set some
    return {name: {first: "John", last: "Doe"}};
  } else { // there is already some data => abort transaction
    console.log("John already exists!");
    return;
  }
}, (error, committed, snapshot) => {
  if (error) {
    console.log("An unexpected error occurred:", error);
  } else if (!committed) {
    console.log("Transaction aborted (John already exists)");
  } else {
    console.log("Transaction completed (John added)");
  }
  console.log("John: " + JSON.stringify(snapshot));
});

unregisterAuthCallback(callbackopt) → {boolean}

Removes an authentication callback function from the set of functions subscribed to changes of the authentication state.

Parameters:
Name Type Attributes Description
callback AuthenticationService.authCallback <optional>
Since:
  • 2.1
Deprecated:
Returns:
Type
boolean

unsubscribe(target, receivesRevocationsopt) → {Promise.<Subscription>}

Unsubscribes a given target from the data events previously subscribed to using the Webcom#subscribe method.

This method requires to be authenticated with the same user than the one used with the Webcom#subscribe method to create the subscription to cancel.

Parameters:
Name Type Attributes Default Description
target Webhook

The target that unsubscribes events.

receivesRevocations boolean <optional>
false

Indicates whether to receive the corresponding revocation.

Since:
  • 2.10
See:
Returns:

The returned Promise is resolved as soon as the unsubscription is acknowledged by the Webcom back end, with the updated subscription to be revoked.

Type
Promise.<Subscription>

update(newVal, onCompleteopt)

Updates data at the data node referred to by this Webcom instance.

Parameters:
Name Type Attributes Description
newVal Object

The children to add to the current data node, given as a json Object. The difference with set() is that existing children (at depth 1 only) are preserved (provided newVal doesn't specify a new value for them).

onComplete function <optional>

A 1-argument callback function called after synchronization with the server. Its argument is filled with an Error object if an error occurred or null otherwise.

Examples
// Get a reference to the "lords" data node
var ref = new Webcom("got").child("lords");

// Update first name and last name without deleting other existing children of "id56".
ref.child("id56").update({first:"John",last:"Snow"});
// Thus: if data at ref.child('id56') was {first:"Ned",last:"Stark",status:"King of the North"}
// it is now: {first:"John",last:"Snow",status:"King of the North"}.

Warning about update depth

ref.child('id57').update({ name: { first:'Alice' } })
//is exactly equivalent to
ref.child('id57').child("name").set({ first:'Alice' })
// Thus: if data at ref.child('john') was {first:"John",last:"Doe"}
// it is now: { first:'Alice' }. Note that last field is deleted

//Other example:
ref.child('id57').update({ name: { first:'John' } , age:43})
//is equivalent to
ref.child('id57').child("name").set({ first:'John' })
//PLUS
ref.child('id57').child("age").set(43)
//except that update performs 2 operations atomically.

updateEmailPasswordProfile(pathopt, data, onCompleteopt) → {Promise}

Updates some data within the profile associated with the currently authenticated email/password identity.

Parameters:
Name Type Attributes Description
path string <optional>

The path within the profile where to update the data.

data Object

The data to update within the profile (as a JSON object).

onComplete AuthenticationService.authCallback <optional>

A 1-argument callback function that is called after the profile update completion, which receives an Error object if it has failed or null otherwise.
Deprecated: Consider rather using the returned Promise.

Deprecated:
Returns:

A promise that will be resolved (without passing any argument) as soon as the update operation completes successfully, or rejected otherwise (with the failure reason as argument)

Type
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// We must be authenticated...
ref.authWithPassword({email:"john@webcom.com", password:"mypassword"})
    // ...before updating the identity profile
    .then(auth => ref.updateEmailPasswordProfile({age: 42}))
    .then(() => console.log("profile updated!")
    .catch(error => console.log("profile update failure:", error);

updateIdentityProfile(pathopt, data) → {Promise}

Updates some data within the profile associated with the currently authenticated email- or phone-based identity. This method fails if no user is currently authenticated or if the currently authenticated user is not identified with an email- or phone-based identity.

Parameters:
Name Type Attributes Description
path string <optional>

The path within the profile where to update the data.

data Object

The data to update within the profile (as a JSON object).

Since:
  • 2.6.2
Returns:

A promise that will be resolved (without passing any argument) as soon as the update operation completes successfully, or rejected otherwise (with the failure reason as argument)

Type
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("contacts");
// We must be authenticated...
ref.authWithPassword({email:"john@webcom.com", password:"mypassword"})
    // ...before updating the identity profile
    .then(auth => ref.updateIdentityProfile({age: 42}))
    .then(() => console.log("profile updated!")
    .catch(error => console.log("profile update failure:", error);

useCurrentContextForNextAuthOperation()

After this method is called, the next authentication-related operation will be performed in the context of the current authentication state. An authentication request will end in a multi-factor token (including at least the identity currently signed in). An identity creation request will add a new identity to the currently signed in Webcom account.

Once the next authentication-related operation performed, the effect of this method is forgotten, that is, further authentication-related operations are executed starting from an empty authentication context event if a user is authenticated.
If you need to cancel the effect of this method before the next authentication-related operation, simply call the Webcom#useNewContextForNextAuthOperation method.

Since:
  • 2.8

useNewContextForNextAuthOperation()

Cancels the effect of the Webcom#useCurrentContextForNextAuthOperation method. Once called, the next authentication-related operation will be performed without any context of authentication state, even if a user is currently signed in.

Since:
  • 2.8

verifyIdentity(provider, id, data) → {Promise}

Verifies an identity newly created using the Webcom#addIdentity method. If the verification is successful, this method also signs the user in with this identity.

Parameters:
Name Type Description
provider string

The internal provider used to create the identity to verify. Currently only "password" and "phone" (resp. for email-based and phone-based identities) are supported.

id string

The identifier of the identity to verify. For email-based identities, it is an email address. For phone-based identities, it is a MSISDN (without the "+" prefix).

data Object

The verification data.

Properties
Name Type Description
token string

(email-based identities only)
The verification token received by the user at her⋅his email address.

auth Object

(phone-based identities only)
The authentication data returned by the Webcom#addIdentity method that created the identity to verify.

password string

(phone-based identities only)
The one time password received by the user at her⋅his MSISDN.

Since:
  • 2.6.2
Returns:

The authentication following the verification is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.

Type
Promise
show
deprecated