How to Install JavaScript SDK

Installing SDK

Depending on the platform you're using, there are different ways for you to install the SDK.

Web	Node.js	React Native	Electron

Web

The following method can be used if your project runs in browser, WebView, or other in-app HTML platforms.

Installing and Referencing SDK

npm

The easiest way to integrate our SDK into your project is to use npm:

# LeanStorage (including push notification services)
$ npm install leancloud-storage --save
# LeanMessage
$ npm install leancloud-realtime --save

Create references to the SDK with require:

// LeanStorage
var AV = require('leancloud-storage');
var { Query, User } = AV;
// LeanMessage
var { Realtime, TextMessage } = require('leancloud-realtime');

If you plan to use LiveQuery, include the following npm module instead:

var AV = require('leancloud-storage/live-query');
// No need to require('leancloud-storage') if this line is present

CDN

You can also import the SDK with a script tag:

<!-- LeanStorage -->
<script src="//cdn.jsdelivr.net/npm/leancloud-storage@4.5.2/dist/av-min.js"></script>
<!-- LeanMessage -->
<script src="//cdn.jsdelivr.net/npm/leancloud-realtime@5.0.0-rc.2/dist/im-browser.min.js"></script>

If you plan to use LiveQuery, use the following URL instead:

<script src="//cdn.jsdelivr.net/npm/leancloud-storage@4.5.2/dist/av-live-query-min.js"></script>
<!-- No need to import av-min.js if this line is present -->

When using this method, you can reference the SDK with the global variable AV:

// LeanStorage
var { Query, User } = AV;
AV.init("{{appid}}", "{{appkey}}");
// LeanMessage
var { Realtime, TextMessage } = AV;

Node.js

JavaScript SDK also works with Node.js. If you plan to use LeanStorage within LeanEngine, you can import leanengine into your project by following instructions in LeanEngine Quick Start.

Installing and Referencing SDK

You can use npm to install and reference our SDK for Node.js as well. See npm for more details.

React Native

You can use npm to install and reference our SDK for React Native. See npm for more details.

Electron

Electron uses npm for managing dependencies. You can install our SDK with the following command:

# LeanStorage (including push notification services)
$ npm install leancloud-storage --save
# LeanMessage
$ npm install leancloud-realtime --save

Importing SDK as Browser Scripts

You can import the SDK by adding a script tag into index.html:

<!-- LeanStorage -->
<script src="./node_modules/leancloud-storage/dist/av-min.js"></script>
<!-- LeanMessage -->
<script src="./node_modules/leancloud-realtime/dist/im-browser.min.js"></script>

If you plan to use LiveQuery, use the following path for LeanStorage:

<script src="./node_modules/leancloud-storage/dist/av-live-query-min.js"></script>

Importing SDK as Node.js Modules

The way of using script to import the SDK works in most scenarios. However, if you have the following needs, you can also use require('leancloud-storage') to import the SDK as Node.js modules:

• Using the SDK in the main process
• Constructing AV.File with Buffer or Stream provided by Node.js

Initializing Your Project

To begin with, get your App ID and App Key from your app's Dashboard > Settings > App Keys.

If you are importing the SDK into your web project with CDN, you can call AV.init when loading the page to initialize the SDK:

var APP_ID = '{{appid}}';
var APP_KEY = '{{appkey}}';

AV.init({
  appId: APP_ID,
  appKey: APP_KEY
});

If you are installing the SDK with npm, you can initialize the SDK with the same way, but make sure to import the SDK with require:

var AV = require('leancloud-storage');
var { Realtime } = require('leancloud-realtime'); // No need to import if not using LeanMessage

var APP_ID = '{{appid}}';
var APP_KEY = '{{appkey}}';

AV.init({
  appId: APP_ID,
  appKey: APP_KEY
});

Enabling Debug Logs

You can easily trace the problems in your project by turning debug logs on during the development phase. Once enabled, details of every request made by the SDK along with errors will be output to IDE, browser console, or your app's Dashboard > LeanEngine > App logs.

If you are using Node.js, you can set the environment variable DEBUG=leancloud* (LeanStorage) or DEBUG=LC* (LeanMessage) when starting the app with npm:

// LeanStorage
DEBUG=leancloud* npm start
// LeanMessage
DEBUG=LC* npm start

If you are using Node.js with LeanEngine, you can set the environment variable by going to Dashboard > LeanEngine > Settings > Custom environment variables, put DEBUG in the first field and leancloud:* in the second field (make sure to include the colon between leancloud and *). When debugging locally with command-line interface, you can set the environment variable DEBUG=leancloud:* to have logs output to your app's Dashboard > LeanEngine > App logs:

DEBUG=leancloud:* lean up

You can output logs to your browser console by setting localStorage:

localStorage.setItem('debug', 'leancloud*');

// Enable debug logs for LeanMessage and LiveQuery
localStorage.setItem('debug', 'LC*');

Recent versions of SDK also support enabling and disabling debug mode within the code.

To enable/disable debug mode for LeanStorage (javascript-sdk >= v3.14.0):

AV.debug.enable();
AV.debug.disable();

To enable/disable debug mode for LeanMessage (js-realtime-sdk >= v5.0.0-alpha.1):

const { debug } = require('leancloud-realtime');
debug.enable();
debug.disable();

Verifying

First of all, make sure you are able to connect to LeanCloud server. You can test it by running the following command:

ping "{{domain}}"

If everything goes well, you will see the following response:

PING api-ucloud.leancloud.cn (123.59.41.31): 56 data bytes
64 bytes from 123.59.41.31: icmp_seq=0 ttl=51 time=9.032 ms
64 bytes from 123.59.41.31: icmp_seq=1 ttl=51 time=7.290 ms
64 bytes from 123.59.41.31: icmp_seq=2 ttl=51 time=8.131 ms
64 bytes from 123.59.41.31: icmp_seq=3 ttl=51 time=9.689 ms
64 bytes from 123.59.41.31: icmp_seq=4 ttl=51 time=6.559 ms
64 bytes from 123.59.41.31: icmp_seq=5 ttl=51 time=8.665 ms
64 bytes from 123.59.41.31: icmp_seq=6 ttl=51 time=8.041 ms
64 bytes from 123.59.41.31: icmp_seq=7 ttl=51 time=8.203 ms
64 bytes from 123.59.41.31: icmp_seq=8 ttl=51 time=6.288 ms
64 bytes from 123.59.41.31: icmp_seq=9 ttl=51 time=7.938 ms

--- api-ucloud.leancloud.cn ping statistics ---
10 packets transmitted, 10 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 6.288/7.984/9.689/0.997 ms

Then add the following code into your project:

var TestObject = AV.Object.extend('TestObject');
var testObject = new TestObject();
testObject.set('words', 'Hello world!');
testObject.save().then(function (testObject) {
  console.log('Object saved.')
})

Save the file and run it.

Then go to your app's Dashboard > LeanStorage > Data > TestObject. If you see the following content, it means that you have correctly installed the SDK.

See Debugging if you're not seeing the content.

Debugging

This guide is written for the latest version of our SDK. If you encounter any error, please first make sure you have the latest version installed.

401 Unauthorized

If you get a 401 error or see the following content in network logs:

{
  "code": 401,
  "error": "Unauthorized."
}

It means that the App ID or App Key might be incorrect or don't match. If you have multiple apps, you might have used the App ID of one app with the App Key of another one, which will lead to such error.

Client Cannot Access the Internet

Make sure you have granted enough permissions for your mobile app.