mnubo-sdk

SmartObjects JavaScript Client

Quickstart

Getting the client library

The client library is available on NPM.

Below is an example of how you can install everything:

    
npm install --save es6-shim  # if you run node < 4.0.0
npm install --save mnubo-sdk
    

For more information, visit GitHub.

Create a client instance

The following JavaScript code can be used to create an instance:

    
var mnubo = require('mnubo-sdk');

/* Create a new client with client id and client secret. */
var client = new mnubo.Client({
  id: '',
  secret: '',
  httpOptions = {
    protocol: 'https',
    hostname: "",
    port: 443
  };
});
    

Introduction

This is a JavaScript opinionated version of the original API documentation. Use classes Owners, Objects, Events, and Search to manage your owners, objects, events and perform searches using the API.

Prerequisites

The current SDK version only works in a NodeJS environment. For security reasons, it is not recommended to use this SDK in a browser environment because the client id and secret could easily be discovered.

The minimum requirement is node>=0.10.40 but because the code uses Promise and Map, if you are not running node>=4.0.0, you need to require es6-shim or any other library that polyfills those structures.

npm install --save es6-shim

require('es6-shim'); // before loading mnubo-sdk

Installation

npm install --save mnubo-sdk

Usage

Because the platform supports UTF-8 for ingesting data, the encoding to use in the client must be UTF-8 as well.

Authentication

The authentication is wrapped for every SDK call. The library will first fetch a new Access Token and make the API call. There is nothing to do from a developer's perspective besides setting the client id, client secret and environment during initialization.

Initialization

The initialization of the SDK client requires two mandatory fields:

• id (mandatory): The client id.
• secret (mandatory): The client secret.
• env (optional): The environment where the API calls will be sent. It can be either sandbox or production. By default the env is sandbox.
• compression (optional): If you want to use gzip compression for both inbound and outbound data, set the value to true. By default this parameter is false.
• exponentialBackoff (optional): If you want to use exponential back off retries. By default, the feature is off (null).

/* Load mnubo SDK. */
require('es6-shim'); /* only if running node < 4.0.0 */
var mnubo = require('mnubo-sdk');

/* Create a new client with client id and client secret. */
var client = new mnubo.Client({
  id: 'KyR2LipTvH2ltAML4ScOTZ7TPLZvjV6oVYIYyx6CZORsoa131d',
  secret: 'B0KcvAeSZJuSXg9Hi0IYZKcsCNNUkw8bxsZ0GSgAW5cWKARa6m',
  env: 'production'
});

You can generate an App Token from the web application and use it with this SDK.

Note: App Tokens can have restricted access to specific APIs and can be disabled by an administrator at any given time. This means that some API provided in this SDK may not work correctly.

/* Create a new client with an access token. */
var client = new mnubo.Client({
  token: 'token...',
  env: 'sandbox'
});

Compression

You can also fine grain the compression by using this syntax:

compression: {
  requests: true,  /* sets Accept-Encoding: gzip */
  responses: true, /* sets Content-Encoding: gzip */
}

Note that, when using compression, the data being resolved in the Promise will always be JSON. The compression/decompression is done behind the scenes using NodeJS zlib library.

Exponential backoff retries

Exponential backoff retries allows a user of the client to automatically retry requests when a 503 HTTP error is returned from the SmartObjects platform. It will gradually increase the interval between retries to allow the server to recover. The configuration to turn on the feature looks like this:

exponentialBackoff: {
  numberOfAttempts: 2, /* How many retries to make before failing. Default to 5 if undefined. */
  initialDelayInMillis: 100, /* The number of ms to wait before the first retry. Default to 500 if undefined. */
  onRetry: (attempt: number) => { /* A callback function called for every retry. Default to nothing if undefined. */
    console.log('Attempt #' + attempt);
  }
}

API Calls

All the API calls return a Promise.

• When a promise is successful, you can call the .then() function to get the data returned by the mnubo servers. If there is no data, the value is null. ex: client.events.send({...}).then(function(data) { console.log(data); });

• When a promise has failed, you can call the .catch() function to get the error returned by the mnubo servers. If there is no data, the value is null. ex: client.events.send({...}).catch(function(error) { console.log(error); });

If you are not familiar with promises, there is an excellent article on html5rocks.

Examples

If you need some examples to get started with the SDK, you can check out the wiki page.

Development

With Visual Studio code, you can use the development container extension. This will open the editor in a container that has all the requirement while leaving your workstation untouched.

From the editor, you can then, open a terminal and do the following to run the tests:

root@4d7a461e5fbc:/workspaces/smartobjects-js-client# source scripts/test-setup.sh YOUR_KEY YOUR_SECRET
root@4d7a461e5fbc:/workspaces/smartobjects-js-client# npm install
root@4d7a461e5fbc:/workspaces/smartobjects-js-client# npm run build
root@4d7a461e5fbc:/workspaces/smartobjects-js-client# npm test

References

mnubo documentation

Promise

Map

Examples