Class: Webcom

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

Extends

• api.Query

Members

App :api.WebcomApp

Type:

• api.WebcomApp

Version:

• 2.8+

authState :Object

Type:

• Object

Version:

• 2.8+

Methods

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

Parameters:

Version:

• 2.6.2+

Deprecated:

• use Webcom#addIdentity instead

Returns:

Type

Promise

addAuthCallback(callback) → {Webcom.authCallback}

Parameters:

Version:

• 2.8+

See:

• Webcom#removeAuthCallback

Returns:

Type

Webcom.authCallback

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

Parameters:

Version:

• 2.8+

See:

• Signing up using internal login

Returns:

Type

Promise

auth(cred, onCompleteopt)

Parameters:

Deprecated:

• use authWithToken() instead.

authAnonymously(onCompleteopt) → {Promise}

Parameters:

Version:

• 1.1+

See:

• Guest login

Returns:

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}

Parameters:

Version:

• 2.8+

See:

• Webcom#sendOtp

• Login with email or phone

Returns:

Type

Promise

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

Parameters:

Version:

• 2.2.2+

See:

• Custom login

Returns:

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}

Parameters:

Version:

• 1.3+

See:

• Login with OAuth2.0

Returns:

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}

Parameters:

Deprecated:

• use Webcom#authInternally instead

Returns:

Type

Promise

authWithPhone(credentials) → {Promise}

Parameters:

Version:

• 2.6.2+

Deprecated:

• use Webcom#authInternally instead

Returns:

Type

Promise

authWithToken(token, onCompleteopt) → {Promise}

Parameters:

Version:

• 1.3+

Returns:

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}

Parameters:

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}

Parameters:

Returns:

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/pR/3a/fH/john"

createUser(details, onCompleteopt) → {Promise}

Parameters:

Deprecated:

• use addAccount() instead

Returns:

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) → {api.Query}

Parameters:

Version:

• 2.2+

Inherited From:

• api.Query#endAt

Returns:

Type

api.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());
});

equalTo(nameopt) → {api.Query}

Parameters:

Version:

• 2.2+

Inherited From:

• api.Query#equalTo

Returns:

Type

api.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()

goOnline()

limit(lim) → {api.Query}

Parameters:

Version:

• 2.2+

Inherited From:

• api.Query#limit

Returns:

Type

api.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 whoses names (keys) come after john display the following 5
lastfriends.on("value", function(snapshot){
     console.log(snapshot.val());
});

logout(onCompleteopt)

Parameters:

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() → {String}

Returns:

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(eventTypeopt, callbackopt, contextopt)

Parameters:

Inherited From:

• api.Query#off

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

on(eventType, callback, cancelCallbackopt, contextopt) → {api.Query~watchCallback}

Parameters:

Inherited From:

• api.Query#on

Returns:

Type

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

Parameters:

Inherited From:

• api.Query#once

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() → {api.OnDisconnect}

Returns:

Type

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

Returns:

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}

Version:

• 2.6.2+

Inherited From:

• api.Query#pathString

Returns:

Type

String

persist()

Version:

• 2.6+

Returns:

push(valueopt, onCompleteopt) → {Webcom}

Parameters:

Returns:

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) {
  if (error) {
    console.log("synchronisation error:", error);
  } else {
    console.log("synchronisation ok.");
  }
});

ref() → {Webcom}

Inherited From:

• api.Query#ref

Returns:

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) → {Webcom.authCallback}

Parameters:

Version:

• 2.1+

Deprecated:

• use Webcom#addAuthCallback instead

Returns:

Type

Webcom.authCallback

remove(onCompleteopt)

Parameters:

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}

Version:

• 2.6.2+

See:

• Webcom#removeIdentity

• Deleting accounts

Returns:

Type

Promise

removeAuthCallback(callbackopt) → {boolean}

Parameters:

Version:

• 2.8+

See:

• Webcom#addAuthCallback

Returns:

Type

boolean

removeIdentity() → {Promise}

Version:

• 2.6.2+

See:

• Webcom#removeAccount

Returns:

Type

Promise

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

Parameters:

Deprecated:

• use Webcom#removeAccount or Webcom#removeIdentity instead

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)

Parameters:

Deprecated:

• This method no longer needs to be called

root() → {Webcom}

Returns:

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}

Parameters:

Deprecated:

• use Webcom#sendVerificationCode instead

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}

Parameters:

Version:

• 2.6.2+

Returns:

Type

Promise

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

Parameters:

Version:

• 2.6.2+

Returns:

Type

Promise

sendPasswordResetEmail(email, onCompleteopt) → {Promise}

Parameters:

Deprecated:

• use Webcom#sendPasswordResetCode instead

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}

Parameters:

Version:

• 2.6.2+

Returns:

Type

Promise

set(newVal, onCompleteopt)

Parameters:

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);

setPriority(priority, onCompleteopt)

Parameters:

Version:

• 9999.0+

Example

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

// Priority is changed to 50
ref.setPriority(50);

setWithPriority(newVal, newPriority, onCompleteopt)

Parameters:

Version:

• 9999.0+

Deprecated:

• Like set(), writes data at the data node referred to by this Webcom instance and sets an associated priority.

Example

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

var johnValue = {
  name: {
    first: "John",
    last: "Doe"
  },
  numberOfCalls: 100
};

// "name" and "numberOfCalls" data nodes are written, with 100 as associated priority, so that the "john" data
// node will be ordered using this value with respect to other sibling data nodes
ref.setWithPriority(johnValue, 100);

shouldBeOnline() → {boolean}

Version:

• 2.6.2+

Returns:

Type

boolean

startAt(nameopt) → {api.Query}

Parameters:

Version:

• 2.2+

Inherited From:

• api.Query#startAt

Returns:

Type

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

Returns:

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)

Parameters:

Version:

• 1.1+

Examples

Increment the value of a data node

// Get a reference to the "john" data node
var ref = new Webcom("contacts").child("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("contacts").child("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(callbackopt) → {boolean}

Parameters:

Version:

• 2.1+

Deprecated:

• use Webcom#removeAuthCallback instead

Returns:

Type

boolean

update(newVal, onCompleteopt)

Parameters:

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}

Parameters:

Deprecated:

• use Webcom#updateIdentityProfile instead

Returns:

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}

Parameters:

Version:

• 2.6.2+

Returns:

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()

Version:

• 2.8+

useNewContextForNextAuthOperation()

Version:

• 2.8+

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

Parameters:

Version:

• 2.6.2+

Returns:

Type

Promise

Type Definitions

authCallback(error, auth)

Parameters:

See:

• More details on authentication callbacks

• More details on the authentication model