JSDoc: Class: Webcom

(static, constant) Authentication :Authentication.API

Gets the entry point for accessing all relevant constants and functions related to the Authentication service.

Type:

Authentication.API

Since:

3.5

(static) Constraint :ServerlessDb.Constraint

Convenient link to the ServerlessDb.Constraint class. This property is intended to access the static members None, First, Last, StartAt, EndAt and Between to build instances of this class.

Type:

ServerlessDb.Constraint

Since:

3.0

Deprecated:

Since 3.5 - Moved to Webcom.ServerlessDb.

(static, constant) Event :ServerlessDb.EventDescriptor

Convenient link to the ServerlessDb.EventDescriptor class. This property is intended to access the ServerlessDb.EventDescriptor.ValueChange and ServerlessDb.EventDescriptor.Child static members to build instances of this class.

Type:

ServerlessDb.EventDescriptor

Since:

2.10

Deprecated:

Since 3.5 - Moved to Webcom.ServerlessDb.

(static, constant) FORGET :ServerlessDb.FORGET

Gets the ServerlessDb.FORGET constant.

Type:

ServerlessDb.FORGET

Deprecated:

Since 3.5 - Moved to Webcom.ServerlessDb.

(static, constant) KEEP :ServerlessDb.KEEP

Gets the ServerlessDb.KEEP constant.

Type:

ServerlessDb.KEEP

Deprecated:

Since 3.5 - Moved to Webcom.ServerlessDb.

(static, constant) KEEP_UPDATING :ServerlessDb.KEEP_UPDATING

Gets the ServerlessDb.KEEP_UPDATING constant.

Type:

ServerlessDb.KEEP_UPDATING

Deprecated:

Since 3.5 - Moved to Webcom.ServerlessDb.

(static, constant) Log :LogManager

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

Type:

LogManager

Since:

2.11

(static, constant) NEXT_DISCONNECTION :ServerlessDb.NEXT_DISCONNECTION

Gets the ServerlessDb.NEXT_DISCONNECTION constant.

Type:

ServerlessDb.NEXT_DISCONNECTION

Deprecated:

Since 3.5 - Moved to Webcom.ServerlessDb.

(static, constant) NOW :ServerlessDb.NOW

Gets the ServerlessDb.NOW constant.

Type:

ServerlessDb.NOW

Deprecated:

Since 3.5 - Moved to Webcom.ServerlessDb.

(static, constant) ON_DISCONNECTION :ServerlessDb.ON_DISCONNECTION

Gets the ServerlessDb.ON_DISCONNECTION constant.

Type:

ServerlessDb.ON_DISCONNECTION

Since:

3.3

Deprecated:

Since 3.5 - Moved to Webcom.ServerlessDb.

(static, constant) SDK_VERSION :string

Version of the current Webcom SDK.

Type:

string

(static, constant) ServerlessDb :ServerlessDb.API

Gets the entry point for accessing all relevant constants and functions related to the ServerlessDb service.

Type:

ServerlessDb.API

Since:

3.5

(static, constant) ServerValue :Object

Dictionary of special objects intended to be replaced by a value computed by the Webcom back end when written into a ServerlessDb.ServerlessDbNode:

the TIMESTAMP property gives a value that will be replaced with the actual timestamp of the Webcom back end.

Type:

Object

Deprecated:

Since 3.5 - Moved to Webcom.ServerlessDb.

(readonly) authenticator :Authentication

Authentication service that manages this instance.

Type:

Authentication

Overrides:

Query#authenticator

Deprecated:

Since 3.0 - Use WebcomApp#authentication instead.

authState :Authentication.State

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

Type:

Authentication.State

Since:

2.8

Deprecated:

Since 2.11 -Use the currentState property of Query#authenticator instead.

(readonly) datasync :ServerlessDb

ServerlessDb service that manages this instance.

Type:

ServerlessDb

Overrides:

Query#datasync

Deprecated:

Since 3.0 - Use WebcomApp#serverlessDb instead.

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

Creates an instance of WebcomApp.

Parameters:

Name Type Attributes Description

Name	Type	Attributes	Description
`appId`	string		The identifier of the Webcom application the `WebcomApp` object to be created will refer to.
`config`	WebcomApp.Configuration \| string	<optional>	Configuration of the `WebcomApp` object to create. It consists in a collection of keys mapped to the configurations of each available Webcom service: `Authentication` maps to a `Authentication.Configuration` object, `ServerlessDb` maps to a `ServerlessDb.Configuration` object, `ServerlessDbLite` maps to a `ServerlessDbLite.Configuration` object. A simpler configuration may be provided as a string representing the base URL of the targeted hosting Webcom platform (following the syntax: `{protocol}?{host}(:{port})?`). It is then equivalent to the following configuration: `{Authentication:{baseUrl:"hostingPf"},ServerlessDb:{baseUrl:"hostingPf"},ServerlessDbLite:{baseUrl:"hostingPf"}}` If not set, an empty `WebcomApp.Configuration` is used, resulting in default configuration values.

appId

string

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

config

WebcomApp.Configuration | string

Configuration of the WebcomApp object to create. It consists in a collection of keys mapped to the configurations of each available Webcom service:

Authentication maps to a Authentication.Configuration object,
ServerlessDb maps to a ServerlessDb.Configuration object,
ServerlessDbLite maps to a ServerlessDbLite.Configuration object.

A simpler configuration may be provided as a string representing the base URL of the targeted hosting Webcom platform (following the syntax: {protocol}?{host}(:{port})?). It is then equivalent to the following configuration: {Authentication:{baseUrl:"hostingPf"},ServerlessDb:{baseUrl:"hostingPf"},ServerlessDbLite:{baseUrl:"hostingPf"}}

If not set, an empty WebcomApp.Configuration is used, resulting in default configuration values.

Since:

2.8

Returns:

Type: WebcomApp

(static) avatarURL(user) → {string|undefined}

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

Parameters:

Name	Type	Description
`user`	Authentication.AuthenticationDetails	The authentication details of the user (can be found in authentication state objects).

Since:

2.8

Deprecated:

Since 3.5 - Moved to Webcom.Authentication.

Returns:

the user's avatar URL if known or undefined otherwise

Type: string | undefined

(static) Callback(callback, cancelationPolicyopt) → {ServerlessDb.Callback}

Creates an instance of ServerlessDb.Callback notification channel, which is intended to be registered with the ServerlessDb.ServerlessDbNode#subscribe method and to receive notifications of data changes in real time (through the ServerlessDb websocket).

Parameters:

Name	Type	Attributes	Default	Description
`callback`	ServerlessDb.SubscriptionCallback			The function that will receive notifications each time the subscribed event is raised.
`cancelationPolicy`	ServerlessDb.FORGET \| ServerlessDb.KEEP \| ServerlessDb.KEEP_UPDATING	<optional>	ServerlessDb.KEEP	The policy to apply on the local cache when the corresponding subscription will end.

Since:

3.0

Deprecated:

Since 3.5 - Moved to Webcom.ServerlessDb.

Returns:

Type: ServerlessDb.Callback

(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

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#timestamp instead.

Returns:

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

Type: number

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

Creates an instance of ServerlessDb.Webhook notification channel, which is intended to be registered with the ServerlessDb.ServerlessDbNode#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: ServerlessDb.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

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:

Since 2.8 - Use Webcom#addIdentity instead.

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

Adds an authentication callback function to the set of functions that watch 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`	Authentication.authCallback	the callback function to add.

Since:

2.8

Deprecated:

Since 3.0 - Use Authentication#subscribe instead.

See:

Webcom#removeAuthCallback

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

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

Deprecated:

Since 3.0 - Use Authentication#addIdentity instead.

See:

Signing up using internal login

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 as 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`	Authentication.authCallback	<optional>	Callback function to be called when the authentication completes.

Deprecated:

Since 1.3.2 - Use authWithToken() instead.

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`	Authentication.authCallback	<optional>	Callback function to be called when the authentication completes. Deprecated: Consider rather using the returned `Promise`.

Since:

1.1

Deprecated:

Since 3.0 - Use Authentication#signInAsGuest instead.

See:

Guest login

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 as the auth (resp. error) parameter of authentication callbacks.

Type: Promise

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

Deprecated:

Since 3.0 - Use Authentication#signInWithCredentials instead.

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 as 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`	Authentication.authCallback	<optional>	Callback function to be called when the authentication completes. Deprecated: Consider rather using the returned `Promise`.

Since:

2.2.2

Deprecated:

Since 3.0 - Use Authentication#signInWithCustomProvider instead.

See:

Custom login

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 as the auth (resp. error) parameter of authentication callbacks.

Type: Promise

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. Please refer to Login with OAuth2.0 for more details.

Currently, supported providers are:

facebook
google
apple
github
gitlab
orange
mobileconnectOFR (Orange France)
mobileconnectOJO (Orange Jordan)
mobileconnectOMG (Orange Madagascar)
mobileconnectOMA (Orange Morocco)
mobileconnectOCI (Orange Ivory Coast)
mobileconnectOEG (Orange Egypt)
mobileconnectOCD (Orange Congo)
mobileconnectOBW (Orange Botswana)
mobileconnectOGN (Orange Guinea Conakry)
mobileconnectOTN (Orange Tunisia)
mobileconnectOSN (Orange Senegal)
mobileconnectOGW (Orange Guinea Bissau)
mobileconnectOCM (Orange Cameroon)
mobileconnectOLR (Orange Liberia)
mobileconnectOML (Orange Mali)
mobileconnectONE (Orange Niger)
mobileconnectOBF (Orange Burkina Faso)

options

Object

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

Authentication.authCallback

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

Since:

1.3

Deprecated:

Since 3.0 - Use Authentication#signInWithOAuth instead.

See:

Login with OAuth2.0

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 as the auth (resp. error) parameter of authentication callbacks.

Type: Promise

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

Authentication.authCallback

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

Deprecated:

Since 2.8 - Use Webcom#authInternally instead.

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 as 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:

Since 2.8 - Use Webcom#authInternally instead.

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

Parameters:

Name	Type	Attributes	Description
`token`	string		The Webcom authentication token to use
`onComplete`	Authentication.authCallback	<optional>	Callback function to be called when the authentication completes. Deprecated: Consider rather using the returned `Promise`.

Since:

1.3

Deprecated:

Since 3.0 - Use Authentication#signInWithToken instead.

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 as the auth (resp. error) parameter of authentication callbacks.

Type: Promise

authWithWassup(options, onCompleteopt) → {Promise}

Authenticates the user implicitly based on the Orange Wassup Translator service. This method works only for mobile devices connected through the Orange mobile data network. It is rather intended to Webcom mobile SDKs, it should not be needed in pure JavaScript applications.

Parameters:

Name Type Attributes Description

options

The authentication options to use, with the following properties:

Properties

Name	Type	Description
`mcc`	string	The Mobile Country Code of the SIM card used by the device to connect the data network. The `"wisp"` value may also be used for countries that don't use a WaaaT server.

onComplete

Authentication.authCallback

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

Since:

1.4

Deprecated:

Since 3.0 - Use Authentication#signInWithWassup instead.

See:

Mobile implicit login

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 as the auth (resp. error) parameter of authentication callbacks.

Type: Promise

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

Deprecated:

Since 3.0 - Use Authentication#updatePassword instead.

Returns:

Type: Promise

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

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

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:

Query#child

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#relativeNode instead.

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

Authentication.authCallback

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

Deprecated:

Since 2.7 - Use addAccount() instead.

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 as the auth (resp. error) parameter of authentication callbacks.

Type: Promise

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:

Query#endAt

Deprecated:

Since 3.0 - Use ServerlessDb.Constraint.EndAt or ServerlessDb.Constraint.Between instead.

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:

Query#equalTo

Deprecated:

Since 3.0 - Use ServerlessDb.Constraint.Between instead.

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

Query#get

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#get instead.

Returns:

A promise that will be resolved with the read data.

Type: Promise.<ServerlessDb.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() → {ServerlessDb.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 as the one passed to watch callbacks.

Since:

2.15

Overrides:

Query#getCache

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#getCache instead.

Returns:

Type: ServerlessDb.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 re-established until Webcom#goOnline is called.

Deprecated:

Since 2.11 - Use ServerlessDb#disconnect instead.

goOnline()

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

Deprecated:

Since 2.11 - Use ServerlessDb#connect instead.

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

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#increment instead.

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:

Query#limit

Deprecated:

Since 3.0 - Use ServerlessDb.Constraint.First or ServerlessDb.Constraint.Last instead.

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

Deprecated:

Since 3.0 - Use Authentication#signOut instead.

Returns:

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

Type: Promise

name() → (nullable) {string}

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

Overrides:

Query#name

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#key instead.

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:

Query#off

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#unsubscribe instead.

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(eventTypesopt, 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 ServerlessDb#cleanOfflineData method.

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 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 `eventTypes` 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:

Query#offPreservingOfflineData

Deprecated:

Since 2.15 - Make the completion callbacks passed to the Query#on function return Query.KEEP_UPDATING.

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 at this node or any sub-node) change.

The ServerlessDb.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 ServerlessDb.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 ServerlessDb.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 ServerlessDb.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 ServerlessDb.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 ServerlessDb.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 `ServerlessDb.completeSubscriptionOnCancelation` option set to `true`.
`context`	Object	<optional>	Context object for binding of the callback functions

Overrides:

Query#on

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#subscribe instead.

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(eventTypes, 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
`eventTypes`	string \| Array.<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:

Query#once

Deprecated:

Since 2.14 - Use Query#get instead.

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.

Deprecated:

Since 3.0 - Use the "write policy" parameter of the ServerlessDb.ServerlessDbNode#set, ServerlessDb.ServerlessDbNode#merge and ServerlessDb.ServerlessDbNode#clear methods instead.

Returns:

Type: OnDisconnect

parent() → {Webcom}

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

Overrides:

Query#parent

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#parent instead.

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:

Query#pathString

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#path instead.

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

Deprecated:

Since 3.0 - Use ServerlessDb#persist instead.

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.

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#push instead.

Returns:

A Webcom instance referring to the added child.

Type: Webcom

ref() → {Webcom}

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

Overrides:

Query#ref

Deprecated:

Since 3.0 - Use WebcomApp#serverlessDb instead.

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

Adds an authentication callback function to the set of functions that watch 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`	Authentication.authCallback	the callback function to add.

Since:

2.1

Deprecated:

Since 2.8 - Use Webcom#addAuthCallback instead.

Returns:

the added callback function.

Type: Authentication.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.

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#clear instead.

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

Deprecated:

Since 3.0 - Use Authentication#removeAccount instead.

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 success, 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 that watch 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`	Authentication.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

Deprecated:

Since 3.0 - Use Authentication#unsubscribe instead.

See:

Webcom#addAuthCallback

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

Deprecated:

Since 3.0 - Use Authentication#removeIdentity instead.

See:

Webcom#removeAccount

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 success, 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`	Authentication.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:

Since 2.7 - Use Webcom#removeAccount or Webcom#removeIdentity instead.

Returns:

Type: Promise

resume(callbackopt)

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

Parameters:

Name	Type	Attributes	Description
`callback`	Authentication.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:

Since 2.8 - 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:

Query#root

Deprecated:

Since 3.0 - Use ServerlessDb#rootNode instead.

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 sent to
`onComplete`	Authentication.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:

Since 2.7 - Use Webcom#sendVerificationCode instead.

Returns:

Type: Promise

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

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

Deprecated:

Since 3.0 - Use Authentication#sendOtp instead.

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 OTP identifier or challenge that has been sent (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

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

Deprecated:

Since 3.0 - Use Authentication#sendPasswordResetCode instead.

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`	Authentication.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:

Since 2.7 - Use Webcom#sendPasswordResetCode instead.

Returns:

Type: Promise

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

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

Deprecated:

Since 3.0 - Use Authentication#sendVerificationCode instead.

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(valuenullable, onCompleteopt)

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

Parameters:

Name	Type	Attributes	Description
`value`	Object \| string \| number \| boolean	<nullable>	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.

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#set instead.

shouldBeOnline() → {boolean}

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

Since:

2.6.2

Deprecated:

Since 2.11 - Use ServerlessDb#shouldBeConnected instead.

Returns:

the current expected state of the ServerlessDb 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:

Query#startAt

Deprecated:

Since 3.0 - Use ServerlessDb.Constraint.StartAt or ServerlessDb.Constraint.Between instead.

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

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 ServerlessDb.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 ServerlessDb.Subscription#cancel method on the ServerlessDb.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 ServerlessDb.Subscription instance).

Parameters:

Name	Type	Description
`event`	ServerlessDb.EventDescriptor	The descriptor of data events to subscribe to. Such descriptors must be created using the `Webcom.Event` property.
`target`	ServerlessDb.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

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#subscribe instead.

See:

Webcom#unsubscribe

Returns:

The returned Promise is resolved with a ServerlessDb.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.<ServerlessDb.Subscription>

toString() → {string}

Returns a string representation of this Webcom instance as the absolute URL of the data node it represents.

Deprecated:

Since 3.0 - No longer useful.

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)

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

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 ServerlessDb.DataSnapshot object containing the resulting value of the data node (this value is passed even in case of error).

options

Object

{}

Properties

Name Type Attributes Default Description

applyLocally

boolean

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

"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 (i.e. arrays occur as objects with 0, 1, 2... keys).
With "snapshot", the passed value is a ServerlessDb.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

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#runTransaction instead.

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 that watch changes of the authentication state.

Parameters:

Name	Type	Attributes	Description
`callback`	Authentication.authCallback	<optional>

Since:

2.1

Deprecated:

Since 2.8 - Use Webcom#removeAuthCallback instead.

Returns:

Type: boolean

unsubscribe(target, receivesRevocationsopt) → {Promise.<ServerlessDb.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 as the one used with the Webcom#subscribe method to create the subscription to cancel.

Parameters:

Name	Type	Attributes	Default	Description
`target`	ServerlessDb.Webhook			The target that unsubscribes events.
`receivesRevocations`	boolean	<optional>	false	Indicates whether to receive the corresponding revocation.

Since:

2.10

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#unsubscribe instead.

See:

Webcom#subscribe

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

Deprecated:

Since 3.0 - Use ServerlessDb.ServerlessDbNode#merge instead.

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`	Authentication.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:

Since 2.7 -Use Webcom#updateIdentityProfile instead

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

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

Deprecated:

Since 3.0 - Use Authentication#updateIdentityProfile instead.

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

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

Deprecated:

Since 3.0 - Use Authentication#useCurrentContextForNextAuthOperation instead.

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

Deprecated:

Since 3.0 - Use Authentication#useNewContextForNextAuthOperation instead.

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

Deprecated:

Since 3.0 - Use Authentication#verifyIdentity instead.

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 as the auth (resp. error) parameter of authentication callbacks.

Type: Promise

Class: Webcom

Constructor

new Webcom(app, configopt)

Parameters:

Properties

Extends

Members

(static, constant) Authentication :Authentication.API

Type:

(static) Constraint :ServerlessDb.Constraint

Type:

(static, constant) Event :ServerlessDb.EventDescriptor

Type:

(static, constant) FORGET :ServerlessDb.FORGET

Type:

(static, constant) KEEP :ServerlessDb.KEEP

Type:

(static, constant) KEEP_UPDATING :ServerlessDb.KEEP_UPDATING

Type:

(static, constant) Log :LogManager

Type:

(static, constant) NEXT_DISCONNECTION :ServerlessDb.NEXT_DISCONNECTION

Type:

(static, constant) NOW :ServerlessDb.NOW

Type:

(static, constant) ON_DISCONNECTION :ServerlessDb.ON_DISCONNECTION

Type:

(static, constant) SDK_VERSION :string

Type:

(static, constant) ServerlessDb :ServerlessDb.API

Type:

(static, constant) ServerValue :Object

Type:

(readonly) authenticator :Authentication

Type:

authState :Authentication.State

Type:

(readonly) datasync :ServerlessDb

Type:

Methods

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

Parameters:

Returns:

(static) avatarURL(user) → {string|undefined}

Parameters:

Returns:

(static) Callback(callback, cancelationPolicyopt) → {ServerlessDb.Callback}

Parameters:

Returns:

(static) pushIdToDateTime(id) → {number}

Parameters:

Returns:

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

Parameters:

Returns:

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

Parameters:

Properties

Properties

Returns:

addAuthCallback(callback) → {Authentication.authCallback}

Parameters:

Returns:

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

Parameters:

Properties

Properties

Returns:

auth(cred, onCompleteopt)

Parameters:

authAnonymously(onCompleteopt) → {Promise}

Parameters:

Returns:

authInternally(provider, credentials) → {Promise}

Parameters:

Properties

Returns:

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

Parameters:

Returns: