webcom/README.md

Webcom library

Webcom is the Orange [Backend-as-a-Service](https://en.wikipedia.org/wiki/Mobile_Backend_as_a_service) / Serverless
solution. It provides integrated functions for:
- database,
- message exchange (publish / subscribe),
- notification on mobile devices,
- authentication federation,
- data exposure and access control.

This platform drastically reduces time and cost to implement and deploy mobile and web applications in production.

More information on [https://datasync.orange.com](https://datasync.orange.com).

#### [Webcom documentation](https://datasync.orange.com/doc)

#### [Webcom SDKs news on Plazza](https://plazza.orange.com/groups/webcom/projects/sdk-infos)

#### [Samples for Web Applications](https://datasync.orange.com/doc/tutorial-tips-examples.html)

#### [Changelog](https://datasync.orange.com/repository/webcom-sdk-js/3.10.1/doc/tutorial-changelog.html)

## Quick start

### 1. Create your own developer account on the [Webcom developer console](https://io.datasync.orange.com)

### 2. Create a Webcom application on the [Webcom developer console](https://io.datasync.orange.com)

### 3. Select the right library from the Webcom package

Several flavors of the javascript SDK are available within the Webcom package, you must select the right one depending on your execution environment and the service(s) you need. The file name must guide you in your choice:

- With a `-node` suffix the library is built for a Node.js environment, otherwise it targets a Web application.
- With an `-auth` or a `-sldb` suffix the library embeds respectively the
  [Authentication](https://datasync.orange.com/doc/tutorial-auth.html) or the
  [ServerlessDb](https://datasync.orange.com/doc/tutorial-database.html) service.
  This approach is extended for all existing (or future) services, for example `-sldbLite`.
- With a `-debug` suffix the library is usable during your development for debugging purpose (warning:
  footprint of such a library flavor is much larger, as it is neither compressed nor optimized).
- The `webcom.js` and `webcom-node.js` libraries are versions that embed **all** services and **all APIs**,
  including the deprecated ones.

Examples:

```js
// for Web Application
webcom.js                     // the full version including all deprecated APIs
webcom-auth-sldb.js           // a version with Authentication and ServerlessDb services
// for NodeJs based servers
webcom-node.js                // the full version including all deprecated APIs
webcom-auth-sldbLite-node.js  // a version with Authentication and the lite version of ServerlessDb service
```

### 4. Add the Webcom javascript library to your project

#### 4.a Web applications, directly
```html
<script type='text/javascript' src='https://cdn.jsdelivr.net/npm/webcom@3.10.1/webcom.js'></script>
```

#### 4.b Web applications, with [`npm`](https://www.npmjs.com/)

First install the Webcom package
```shell script
npm install webcom@3.10.1
```

And then reference the installed javascript library in your web application:
- either with a `script` tag
```html
<script type='text/javascript' src='<YOUR_LIBRARY_PATH>/webcom.js'></script>
```
- or with a javascript `import` directive
```javascript
import 'webcom/webcom.js';
```

#### 4.c Node.js applications

First install the Webcom package
```shell script
npm install webcom@3.10.1
```

And then load the javascript library in your Node.js application
```javascript
const Webcom = require('webcom');
```

### 5. Use Webcom in your code

#### 5.a Create a reference to your Webcom application
```javascript
const myApp = Webcom.App('<your-app>');
```

The Authentication and ServerlessDb services may then be accessed respectively through the `myApp.authentication` and
`myApp.serverlessDb` properties.

#### 5.b Listen to data within your data tree
```javascript
const node = myApp.serverlessDb.rootNode.relativeNode("the/targeted/path");
node.subscribe(Webcom.Event.ValueChange, Webcom.Callback(snapshot => {
    // this callback is called each time the data in your app at "the/targeted/path" is updated
    console.info("data in my app is now:", snapShot.val());
}));
```

You can also send notifications to a webhook instead of a javascript callback (to do so, you must configure the
"`myWebhook`" webhook on the [Webcom developer console](https://io.datasync.orange.com)):
```javascript
node.subscribe(Webcom.Event.ValueChange, Webcom.Webhook("myWebhook", "aContext"));
```

#### 5.c Write data into your data tree
```javascript
node.set({foo: 'bar'})
    .then(() => console.info("write operation succeeded"))
    .catch(error => console.info("write operation failed:", error.message));
```

While the `set` method overwrites data, the `merge` one completes existing data:
```javascript
node.merge({baz: 42});
```
The whole data tree of your application is now
```json
{
 "the": {
  "targeted": {
   "path": {
    "foo": "bar",
    "baz": 42
   }
  }
 }
}
```

### 5. Run your application
Applications hosted by a web browser should run straightforward.

If you run a Node.js application, be careful to the network configuration: behind a company proxy, you just have to
set up usual environment variables `https_proxy` and `http_proxy` (or their uppercase counterparts):
```shell script
export http_proxy="http://my-proxy.my-company.com:8080"
```
Note that the `no_proxy` environment variable is also taken into account.