Class: Webcom

Webcom

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

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

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

new Webcom (app, options)

Webcom.js, line 74

Constructs a Webcom instance.

Name Type Default Description
app api.WebcomApp

Instance describing your [[service]] application on a given platform. If no specific [[service]] platform is required, then app can be a string equal to the [[service]] application name.
options Object {} optional

Options of the shared connection to the [[service]] server

Name Type Default Description
persist boolean false optional

If true, the shared connection can be used offline and the data stored in the local client cache are made visible.
goOnline boolean true optional

If true, opens the web-socket connection upon creation of this Webcom instance.
If false, the connection is not established, it will be established later using the Webcom#goOnline method.
Example
// Get a reference to the "contacts" application
var ref = new Webcom('contacts');

Extends

Members

api.WebcomApp App

Convenient link to the api.WebcomApp class.

Methods

addAccount (provider, details, message)

Webcom.js, line 1327

Creates a new [[service]] account bound to an identity managed by [[service]]. Currently, [[service]] is able to manage email- and phone-based identities.

Name Type 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 use for the account creation.

Name Type Description
id String

The identifier of the identity associated with the account 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.
password String

(email-based identities only) The password to the email-based identity associated with the account to create.
displayName String optional

A human-readable display name for the identity associated with the account 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 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.
message Object optional

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

Name Type Default Description
template String "create" optional

The identifier of the verification message to send to the user. It must be picked among the template messages defined in the [[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 [[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
Versions
  • ≥ 2.6.2

Deprecated
See:
Returns:
Type Description
Promise A promise that will be resolved once the account 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 account is in the "unverified" state and cannot be used to log 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 verifyIdentity()

addIdentity (provider, details, message)

Webcom.js, line 1272

Creates a new identity managed by [[service]]. Depending on the current authentication state, this new identity is bound to either a new [[service]] account (if not authenticated) or the [[service]] account of the currently authenticated user. Currently, [[service]] is able to manage email- and phone-based identities.

Name Type 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.

Name Type 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.
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

Name Type Default Description
template String "create" optional

The identifier of the verification message to send to the user. It must be picked among the template messages defined in the [[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 [[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
Versions
  • ≥ 2.8

See:
Returns:
Type Description
Promise 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 log 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 verifyIdentity() method.

auth (cred, onComplete)

Webcom.js, line 721

Authenticates the user using a (already available) [[service]] authentication token.

Name Type Description
cred String

The [[service]] authentication token to use
onComplete Webcom.authCallback optional

Callback function to be called when the authentication completes.
Deprecated

authAnonymously (onComplete)

Webcom.js, line 956

Authenticates the user using a temporary account (to be lost at next log-out) with no explicit credentials.

Name Type Description
onComplete Webcom.authCallback optional

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

See:
Returns:
Type Description
Promise 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.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/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()

authWithCustomProvider (provider, credentials, onComplete)

Webcom.js, line 981

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

Name Type Description
provider String

Identifier of the custom provider to use.
credentials String

Credentials for the user to authenticate, which are generated by the 3rd-party identity provider.
onComplete Webcom.authCallback optional

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

See:
Returns:
Type Description
Promise 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.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/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, options, onComplete)

Webcom.js, line 1117

Authenticates the user using an OAuth2 provider.

Name Type Description
provider String

The OAuth2 provider to use. Currently supported providers are:
options Object optional

The authentication options to use, with the following properties:

Name Type 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 popup optional

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 a 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 Webcom.authCallback optional

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

See:
Returns:
Type Description
Promise 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.
Examples
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/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("[[baseUrl]]/base/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("[[baseUrl]]/base/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, onComplete)

Webcom.js, line 1009

Authenticates the user using email & password credentials (locally managed by the [[service]] server).

Name Type Description
credentials Object

The user's credentials

Name Type Description
email String

The user's email
password String

The user's password
onComplete Webcom.authCallback optional

Callback function to be called when the authentication completes.
Deprecated: Consider rather using the returned Promise.
See:
Returns:
Type Description
Promise 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.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Log the user in with credentials
ref.authWithPassword({
  email: "john@webcom.com",
  password: "pwd"
}).then(function(auth) {
  console.log("User logged in, with UID", auth.uid);
}).catch(function(error) {
  console.log("Login failed, with error", error);
});
// ==> ends up in calling authentication callbacks previously registered using resume()

authWithPhone (credentials)

Webcom.js, line 1041

Authenticates the user using MSISDN / One-Time-Password credentials (locally managed by the [[service]] server). To make the user beforehand receive a One-Time-Password on her/his mobile phone, the application must call the sendOtp() method and keep the returned OTP identitifer (or "challenge").

Name Type Description
credentials Object

The user's credentials

Name Type Description
id String

The user's MSISDN (whithout the "+" prefix), ex: "33612345678"
challenge String

The challenge id associated with the One-Time-Password sent to the user
password String

The password received by the user on her/his mobile phone
Versions
  • ≥ 2.6.2

See:
Returns:
Type Description
Promise 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.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Log the user in with credentials
ref.authWithPhone({
  id: "33612345678",
  challenge: "1234567890abcdefghij"
  password: "pwd"
}).then(function(auth) {
  console.log("User logged in, with UID", auth.uid);
}).catch(function(error) {
  console.log("Login failed, with error", error);
});
// ==> ends up in calling authentication callbacks previously registered using resume()

authWithToken (token, onComplete)

Webcom.js, line 930

Authenticates the user using a (already available) [[service]] authentication token.

Name Type Description
token String

The [[service]] authentication token to use
onComplete Webcom.authCallback optional

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

See:
Returns:
Type Description
Promise 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.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Log the user in with a custom-made [[service]] authentication token
ref.authWithToken('').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, onComplete)

Webcom.js, line 1541

Changes the password of an existing email/password identity.

Name Type 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 function optional

A 1-argument callback function that is called after the password change completion, which receives an Error object if it has failed or no argument otherwise.
Returns:
Type Description
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/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.js, line 222

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 Webcom instance.

Name Type Description
pathString String

Data path, relative to the location of this Webcom 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 parent() method)
  • Path-segments starting with "#" generate hashed-paths, with 3 additional sub-levels, which make it possible to handle large lists of items (see Browse data)
Returns:
Type Description
Webcom A Webcom instance that refers to the specified path
Example
// Get a reference to the "friends" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

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

var maryRef = ref.child("/mary");
console.log(maryRef.toString());
// ==> "[[baseUrl]]/base/contacts/friends/mary"

var maryRef2 = johnRef.child("../mary");
console.log(maryRef2.toString());
// ==> "[[baseUrl]]/base/contacts/friends/mary"

var nameThenLastRef = johnRef.child("name").child("last");
console.log(nameThenLastRef.toString());
// ==> "[[baseUrl]]/base/contacts/friends/john/name/last"

var lastNameRef = johnRef.child("name/last");
console.log(lastNameRef.toString());
// ==> "[[baseUrl]]/base/contacts/friends/john/name/last"

var rootRef = ref.child("../..");
console.log(rootRef.toString());
// ==> "[[baseUrl]]/base/contacts"

var hashedRef = ref.child("#john");
console.log(hashedRef.toString());
// ==> "[[baseUrl]]/base/contacts/friends/pR/3a/fH/john"

createUser (details, onComplete)

Webcom.js, line 1206

Creates a new [[service]] account bound to an email/password identity.

Name Type Description
details Object

The details associated with the account to create.

Name Type 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 Webcom.authCallback optional

Callback function to be called when the account creation completes.
Deprecated: Consider rather using the returned Promise.
Deprecated
Returns:
Type Description
Promise 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.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/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!");
  }
});

inherited endAt (name)

api/Query.js, line 435

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

Name Type Description
name String optional

The child name to end at
Versions
  • ≥ 2.2

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

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

inherited equalTo (name)

api/Query.js, line 457

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

Name Type Description
name String optional

The child name to match for.
Versions
  • ≥ 2.2

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

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

goOffline ()

Webcom.js, line 844

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

goOnline ()

Webcom.js, line 856

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

inherited limit (lim)

api/Query.js, line 364

Create Query object to limit number of children

Name Type Description
lim Number

Number of items
Versions
  • ≥ 2.2

Returns:
Type Description
api.Query
  • new limited Query object.
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 whoses names (keys) come after john display the following 5
lastfriends.on("value", function(snapshot){
     console.log(snapshot.val());
});

logout (onComplete)

Webcom.js, line 1764

Logs the currently authenticated user out.

Name Type 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 no argument otherwise.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/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 (){String}

Webcom.js, line 195

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

Returns:
Type Description
String The name of the data node or null if this instance refers to the root of the application
Example
// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

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

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

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

inherited off (eventType, callback, context)

api/Query.js, line 237

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 on() method.

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

Name Type 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 api.Query~watchCallback optional

Reference to the callback function to unregister (previously passed to or returned by the 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 on().
Examples

Unregister a single callback

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/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("[[baseUrl]]/base/contacts/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

inherited on (eventType, callback, cancelCallback, context)

api/Query.js, line 98

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 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.

  • 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.

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 data update, or even for data deletion if the synchronization fails.

Name Type Description
eventType string | Array.<string>

The type of event to watch. It can be either a single value among value, child_added, child_changed or child_removed (see above), or a list of values among the same constants.
callback api.Query~watchCallback

Callback function called when the specified event occurs (see above).
cancelCallback api.Query~cancelCallback 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
Returns:
Type Description
api.Query~watchCallback A reference to the callback function provided in the callback parameter. It is intended to be passed to the off() method, especially when the callback parameter is given as an inline function.
Examples

Value

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/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("[[baseUrl]]/base/contacts/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("[[baseUrl]]/base/contacts/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("[[baseUrl]]/base/contacts/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()));
});

inherited once (eventType, callback, cancelCallback, context)

api/Query.js, line 303

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

This method is similar to 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.

Name Type Description
eventType String

The type of event to watch. It can be either value, child_added, child_changed or child_removed (see on()).
callback api.Query~watchCallback

Callback function called when the specified event occurs.
cancelCallback api.Query~cancelCallback 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
Examples
// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/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("[[baseUrl]]/base/contacts/friends");

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

onDisconnect (){api.OnDisconnect}

Webcom.js, line 704

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

Returns:
Type Description
api.OnDisconnect
Example
// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

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

parent (){Webcom}

Webcom.js, line 283

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

Returns:
Type Description
Webcom A parent instance of this Webcom instance or null if the data node referred to by this Webcom instance has no parent.
Example
// Get a reference to the "friends" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

var contactsRef = ref.parent();
console.log(contactsRef.toString());
// ==> "[[baseUrl]]/base/contacts"

inherited pathString (){String}

api/Query.js, line 69

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

Versions
  • ≥ 2.6.2

Returns:
Type Description
String The path of this data node, with path levels separated by "/" (slashes)

push (value, onComplete)

Webcom.js, line 641

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.

Name Type 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 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.
Returns:
Type Description
Webcom A Webcom instance referring to the added child.
Examples
// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

// Create a randomly generated unique child
var refPhone = ref.push();
console.log(refPhone.toString());
// ==> "[[baseUrl]]/base/contacts/friends/john/-Jjj6vK9L0NAd9JHusrd"

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

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

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

inherited ref (){Webcom}

api/Query.js, line 80

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

Returns:
Type Description
Webcom A Webcom reference.
Example
// Get a reference to the "friends" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

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

registerAuthCallback (callback)

Webcom.js, line 786

Registers an authentication callback function, to be called each time the authentication state changes.

Name Type Description
callback Webcom.authCallback

the callback function
See:
Returns:
Type Description
Webcom.authCallback the registered callback function
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Register an authentication callback
ref.registerAuthCallback(function(error, auth) {
  if (error) {
    console.log("An error occurred while authenticating", error);
  } else if (auth) {
    console.log("The user with the following identity information has logged in", auth);
  } else {
    console.log("The user has logged out");
  }
});
// Log the user in, this will end in calling the authentication callback
ref.authAnonymously();

remove (onComplete)

Webcom.js, line 500

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

Name Type 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("[[baseUrl]]/base/contacts/friends/john");

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

removeAccount (){Promise}

Webcom.js, line 1405

Deletes the [[service]] account associated with the currently authenticated identity. This method deletes also all the identities associated with the deleted 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.

Versions
  • ≥ 2.6.2

See:
Returns:
Type Description
Promise 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.

removeIdentity (){Promise}

Webcom.js, line 1384

Deletes the currently authenticated identity. This method doesn't delete the associated [[service]] 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.

Versions
  • ≥ 2.6.2

See:
  • removeAccount
Returns:
Type Description
Promise 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.

removeUser (email, password, onComplete)

Webcom.js, line 1580

Removes an existing email/password identity.
Warning: this method doesn't remove the associated [[service]] account.

Name Type Description
email String

The email of the identity to remove
password String

The password of the identity to remove
onComplete function 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 no argument otherwise.
Deprecated
Returns:
Type Description
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/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 (callback)

Webcom.js, line 750

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

Name Type Description
callback Webcom.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 registerAuthCallback() method instead.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Register an anthentication callback
ref.registerAuthCallback(function(error, auth) {
  if (error) {
    console.log("An error occurred while authenticating", error);
  } else if (auth) {
    console.log("The user with the following identity information has logged in", auth);
  } else {
    console.log("The user has logged out");
  }
});
// Resume the authentication state, this will possibly end in calling the authentication callback
ref.resume();

root (){Webcom}

Webcom.js, line 305

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

Returns:
Type Description
Webcom A Webcom instance that refers to the root data node
Example
// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

var rootRef = ref.root();
console.log(rootRef.toString());
// ==> "[[baseUrl]]/base/contacts"

sendConfirmationEmail (email, onComplete)

Webcom.js, line 1688

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.

Name Type Description
email String

The email address of the identity to confirm, which the email must be send to
onComplete function 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 no argument otherwise.
Deprecated
Returns:
Type Description
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/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, message)

Webcom.js, line 1080

Sends a One-Time-Password (OTP) to a user through a given identity. This method is particularly useful before calling the authWithPhone() method, which requires a temporary password to complete.

Name Type 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

Name Type Default Description
template String "login" optional

The identifier of the OTP message to send to the user. It must be picked among the template messages defined in the [[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 [[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
Versions
  • ≥ 2.6.2

Returns:
Type Description
Promise 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 (given as a String). This identifier is required for further methods such as authWithPhone()

sendPasswordResetCode (provider, id, message)

Webcom.js, line 1659

Sends a code to the user, which allow her/his to reset her/his password for a given identity. Currently, only email-based identities are supported (parameter provider equal to "password").

Name Type 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

Name Type Default Description
template String "password-reset" optional

The identifier of the message template (to be picked among the templates defined in the [[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
Versions
  • ≥ 2.6.2

Returns:
Type Description
Promise A promise that is resolved once the password reset code has been sent

sendPasswordResetEmail (email, onComplete)

Webcom.js, line 1620

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.

Name Type Description
email String

The email of the identity to reset
onComplete function 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 no argument otherwise.
Deprecated
Returns:
Type Description
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/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, message)

Webcom.js, line 1731

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.

Name Type Description
provider String

The internal provider that manages the identity to verify
id String

The identifier of the identity to verify
message optional

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

Name Type Default Description
template String "create" optional

The identifier of the verification message to send to the user. It must be picked among the template messages defined in the [[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 [[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
Versions
  • ≥ 2.6.2

Returns:
Type Description
Promise 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 verifyIdentity() method

set (newVal, onComplete)

Webcom.js, line 357

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

Name Type 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("[[baseUrl]]/base/contacts/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("[[baseUrl]]/base/contacts/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}

Webcom.js, line 867

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.

Versions
  • ≥ 2.6.2

Returns:
Type Description
boolean the current expected state of the Datasync websocket

inherited startAt (name)

api/Query.js, line 410

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

Name Type Description
name String optional

The child name to start at
Versions
  • ≥ 2.2

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

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

toString (){String}

Webcom.js, line 327

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

Returns:
Type Description
String The absolute URL of this Webcom instance
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");

console.log(ref.toString());
// ==> "[[baseUrl]]/base/contacts"

var johnRef = ref.child("friends/john");
console.log(johnRef.toString());
// ==> "[[baseUrl]]/base/contacts/friends/john"

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

transaction (transactionUpdate, onComplete, options)

Webcom.js, line 523

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.

Name Type 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 api.DataSnapshot object containing the resulting value of the data node (this value is passed even in case of error).
options object {} optional
Name Type Default Description
applyLocally boolean true optional

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 "json" optional

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.
Versions
  • ≥ 1.1

Examples

Increment the value of a data node

// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

ref.child("numberOfCalls").transaction(function(current) {
  if (current === null) {
    return 0;           // initial value
  } else {
    return current + 1; // next values
  }
});

Write some data only if there is none

// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

ref.transaction(function(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;
  }
}, function(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:", snapshot.val());
});

unregisterAuthCallback (callback)

Webcom.js, line 814

Unregisters an authentication callback function.

Name Type Description
callback Webcom.authCallback optional

the callback function to unregister. Note that it must be a reference to a function previously registered with registerAuthCallback() (an inline function would not be recognized).
If not specified, this method unregisters all callbacks
See:
Returns:
Type Description
boolean true if the callback function to unregister was found, or false otherwise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Defined an authentication callback
var myCallback = function(error, auth) {
  console.log(auth ? "User logged in!" : "User logged out or error!");
};
// Register it
ref.registerAuthCallback(myCallback);
// Log the user in, this will end in calling the authentication callback
ref.authAnonymously();
// Unregister the callback
ref.unregisterAuthCallback(myCallback);
// Log the user out, this no longer calls the authentication callback
ref.logout();

update (newVal, onComplete)

Webcom.js, line 401

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

Name Type 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("[[baseUrl]]/base/got/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 (path, data, onComplete)

Webcom.js, line 1460

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

Name Type Description
path Object optional

The path within the profile where to update the data
data String

The data to update within the profile (as a JSON object)
onComplete function optional

A 1-argument callback function that is called after the profile update completion, which receives an Error object if it has failed or no argument otherwise.
Deprecated
Returns:
Type Description
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/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 (path, data)

Webcom.js, line 1506

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.

Name Type 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)
Versions
  • ≥ 2.6.2

Returns:
Type Description
Promise 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)
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/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);

verifyIdentity (provider, id, data)

Webcom.js, line 1427

Verifies an account newly created using the addAccount() method and if successful, log the user in with this account.

Name Type Description
provider String

The internal provider to used to create the identity. 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.
data Object

The verification data.

Name Type Description
token String

(email-based identities only) verification token received by the user at her/his email address
auth Object

(phone-based identities only) authentication data received from the addAccount() method that created the account to verify
password String

(phone-based identities only) one-time-password received by the user at her/his MSISDN
Versions
  • ≥ 2.6.2

Returns:
Type Description
Promise 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 Definitions

authCallback (error, auth)

Webcom.js, line 28

A callback function that is called when the authentication state changes.

Name Type Description
error Error

If not null, indicates that the last authentication-related operation failed. This object is provided with the following properties:

Name Type Description
code String

A machine-readable code that identifies the error
message String

A human-readable description of the error
auth Object

Relevant only when error is null.
If null, no user is currently authenticated (typically the previously authenticated user has logged out), otherwise, this object describes the authenticated user identity (which depends on the authentication method).
Here are the main properties of this object, common to all authentication methods:

Name Type Description
provider String

The authentication method used
uid String

The [[service]] account identifier of the authenticated user
expires Number

The expiration date of the authentication (in seconds since the Unix epoch)
See:
↑ ↑