• Getting Started with the Backend Services JavaScript SDK

Getting Started with the Backend Services JavaScript SDK

Getting Started with the Backend Services JavaScript SDK

The Backend Services JavaScript SDK library can be used for development of Apache Cordova hybrid mobile applications, NativeScript mobile applications, server-side applications, or mobile web applications. It builds an abstraction layer around the Backend Services RESTful API, providing a simple API for CRUD operations over plain objects. It is well integrated with the Telerik Kendo UI framework.

Some of the features that the Backend Services JavaScript SDK adds over the RESTful API are:

Any operations that are not directly supported by the SDK can be accessed through the RESTful API.

This article is organized as follows:

Source the JavaScript SDK

You can choose between several ways of sourcing the Backend Services JavaScript SDK SDK files, including downloading a local copy or directly referencing an online copy.

Online Copy

For easy setup, you can directly reference the SDK from a Content Delivery Network (CDN).

For production apps, we recommend that you install a local copy of the SDK package inside your application. Doing so ensures that the SDK will instantiate even without a network connection.

Specific SDK Version

You can reference a specific SDK version to ensure stability on API level. Use any of these files:

  • Bundled minified version—for production code use:

    https://bs-static.cdn.telerik.com/latest/everlive.all.min.js
  • Bundled non-minified version—for development and debugging:

    https://bs-static.cdn.telerik.com/latest/everlive.all.js

Latest SDK Version

In a production app, avoid using a CDN reference to the latest distribution. While we always strive to maintain backward compatibility, new versions may contain breaking changes or produce unwanted results in existing apps.

Using a specific Backend Services JavaScript SDK version for production code is recommended, but if you want to try the latest features you can request the latest version using these URLs:

  • Bundled minified version:

    https://bs-static.cdn.telerik.com/latest/everlive.all.min.js
  • Bundled non-minified version:

    https://bs-static.cdn.telerik.com/latest/everlive.all.js

Bower Package

You can consume the Backend Services JavaScript SDK as a bower package.

Installing from AppBuilder

To install the bower package while working with AppBuilder, follow the procedure in Add New Frameworks in Your App. Type 'everlive' in the Search box to find the package.

Installing from the Command Line

To install the bower package using the command line, navigate to your project's folder and run this command from the command line:

bower install everlive

This will install the contents of the JavaScript SDK in the current folder under bower_components, unless you have changed Bower's default settings.

NPM Package

You can consume the Backend Services JavaScript SDK as an npm package compatible with Node.js and NativeScript. To install it, navigate to your project's folder and run this command from the command line:

npm install --save everlive-sdk

This will install the contents of the Backend Services JavaScript SDK in the current folder under node_modules.

ZIP Archive

If you want to, you can download the latest version of the Backend Services JavaScript SDK compressed in a ZIP archive.

Check the SDK version

To check what version of the SDK you have, you can open everlive.all.js or everlive.all.min.js and search for text "Everlive SDK" in the file. After the text "Everlive SDK" you will find the exact version of the file.

Add the JavaScript SDK to Your Project

After downloading the Backend Services JavaScript SDK files or acquiring a reference to them, you need to specify their location in your project. This depends on your development framework:

Hybrid and Web Apps

When using HTML, add the following script tag to your code:

<!-- File name can be everlive.all.min.js or everlive.all.js -->
<script src="./everlive/min/everlive.all.min.js"></script>

Server-Side Apps

In Node.js apps, add the following lines of code:

//If installed as a Node.js module
var Everlive = require('everlive-sdk');
//If downloaded to an arbitrary path
//File name can be everlive.all.min.js or everlive.all.js
var Everlive = require('path/to/everlive.js');

NativeScript Apps

In NativeScript apps, you can choose to:

  • Install the SDK as an npm package.
  • Download the ZIP Archive and install it in your NativeScript project's app folder.

See NativeScript and the JavaScript SDK for more information on using the Backend Services JavaScript SDK with NativeScript.

Initialize the JavaScript SDK

After you add the Backend Services JavaScript SDK to your project, initialize the SDK with this line of code:

var el = new Everlive('your-app-id');

An Everlive instance is instantiated by passing your Telerik Platform app's App ID. The App ID is a unique identifier for your Telerik Platform app. See Introduction to Security for more information, including how to obtain it.

The Everlive instance is the starting point for the SDK. It keeps information about the Telerik Platform app (the App ID, the authentication token of the currently logged-in user, etc.) You can pass additional initialization settings as follows:

var el = new Everlive({
    appId: 'your-app-id',
    scheme: 'https'
});

The next table summarizes the full list of initialization settings:

Setting Description
appId The App ID of the Telerik Platform app.
scheme The URI scheme to be used when making requests. Set to https for encrypted client-server communication (availability subject to Telerik Platform licensing). Set to null if you use the Backend Services JavaScript SDK in a browser app and you want to inherit its default scheme. Default: http.
token A security token of an authenticated user. Set it if the user is already logged in and you keep their token. Default: null.
masterKey The master key of the Telerik Platform app. Use this authorization scheme for operations that require it or to override you app's access control. Use only for development purposes. Do not deploy it with your app.

The first created Everlive instance can be accessed through the Everlive.$ field so it is not necessary to hold an explicit reference to it.

Asynchronous Execution

The Backend Services JavaScript SDK supports asynchronous execution through callbacks or promises. Most operations can be used with either of them.

Use of Callbacks

You can pass callback functions to most methods of the JavaScript SDK.

For example:

var el = new Everlive('your-app-id');
el.authentication.login('jsmith', // username
    'password', // password
    function (data) { // success callback
        alert(JSON.stringify(data));
    },
    function(error) { // error callback
        alert(JSON.stringify(error));
    });

Use of Promises

The Backend Services JavaScript SDK utilizes the rsvp library to implement CommonJS Promises A specification.

With many operations you can choose to return a promise as an alternative to using callbacks. For example:

var el = new Everlive('your-app-id');
el.authentication.login('jsmith', // username
    'password') // password
    .then(function (data) { // success callback
        alert(JSON.stringify(data));
    },
    function(error) { // error callback
        alert(JSON.stringify(error));
    });

Debugging

The minified JavaScript SDK file comes along with a source map to aid debugging. The source map allows compliant debuggers to recover the source bits that were lost during file combination and minimization and to work as if you have included the everlive.all.js version. This way you get references to the original lines of code and can even view them.

The source map is referenced from the minified version of the SDK; compliant debuggers will use it automatically. It is also available in the same folder as the everlive.all.min.js file, for example:

https://bs-static.cdn.telerik.com/latest/everlive.all.map

Source map support is provided by the latest versions of all major browsers' developer's tools. Refer to your favorite browser's documentation to learn how to enable and use source maps.

Checking the SDK version

The JavaScript SDK version is included inside each everlive.all.js or everlive.all.min.js file.

To check the version of the file that you have, open the file and search for "Everlive SDK". Depending on the file, the version line or lines will look like this:

Everlive SDK Version: latest
Everlive SDK
Version: latest

Using TypeScript Definitions

First introduced in Backend Services JavaScript SDK version 1.8.0

If you are using NativeScript, Angular 2, or another TypeScript framework you might want to download the TypeScript definitions for the Backend Services JavaScript SDK. The definitions enable you to compile TypeScript projects and to enjoy intelligent code completion, type checking, and other benefits that IDE features like Microsoft IntelliSense in Microsoft Visual Studio offer.

Compatibility

The Backend Services JavaScript SDK is compatible with TypeScript versions 2.0 and later.

Getting the Definitions

You need to source the Backend Services JavaScript SDK from NPM to be able to use its TypeScript definitions. They will be automatically downloaded along with the SDK files to the dist/declarations/typings folder.

Using the Definitions

The TypeScript definitions packaged with the Backend Services JavaScript SDK come in two flavors:

  • Base definitions—for the Backend Services JavaScript SDK itself. Referenced by default.
  • Optional definitions—for external libraries used by the SDK. Not automatically referenced to prevent conflicts with definitions that you might have already referenced in your project. These include:
    • es6-promise
    • json-stable-stringify
    • node
    • underscore
    • node-localstorage

Only reference optional definitions if you are not already referencing compatible TypeScript definitions from libraries that you installed yourself.

Next Steps

See Also

You can find mode information about the benefits of using promises from these resources:

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.