Version: v3

Installing Java SDK for Data Storage and Instant Messaging

The Relationships Between the SDK and Different Platforms

The following content shows the libraries included in the Java SDK as well as their relationships with different platforms:

Basic Libraries (Can Be Used in Pure Java Environment)

storage-core: Provides features for the Data Storage service, which include:
- Data Storage (LCObject)
- TDS Authentication (LCUser)
- Queries (LCQuery)
- File Storage (LCFile)
- Friends (LCFriendship; not available in the current version yet)
- Moments (LCStatus; not available in the current version yet)
- SMS (LCSMS)
- And more
realtime-core: Partially depending on the storage-core library, provides features like LiveQuery and Instant Messaging, which include:
- LiveQuery
- LCIMClient
- LCIMConversation and different types of conversations
- LCIMMessage and multimedia messages
- And more

Libraries for Android Only

storage-android: The storage-core library customized for Android. Offers exactly the same interfaces as storage-core.
realtime-android: The realtime-core library customized for Android. Contains interfaces for push notifications for Android.
mixpush-android: The mixpush library supporting the official push services of Huawei, Xiaomi, Meizu, vivo, and OPPO.
leancloud-fcm: An encapsulation of Firebase Cloud Messaging for Push Notification services.

Dependencies

The Java SDK contains the following modules:

Directory	Module name	Platform	Dependency
./core	storage-core (for Data Storage)	Java	None
./realtime	realtime-core (for LiveQuery and Instant Messaging)	Java	storage-core
./android-sdk/storage-android	storage-android (Data Storage for Android)	Android	storage-core
./android-sdk/realtime-android	realtime-android (for Android push notifications, LiveQuery, and Instant Messaging)	Android	storage-android, realtime-core
./android-sdk/mixpush-android	Android mixpush	Android	realtime-android
./android-sdk/leancloud-fcm	Firebase Cloud Messaging library	Android	realtime-android

Installing SDK

There are several ways for you to install our SDK and the most convenient one is to use a package manager.

We have published all the libraries to Maven. You can use any package manager to install the SDK.

Data Storage

Android
Maven
Ivy
SBT
Gradle

Use the following packages if you are building an Android app:

implementation 'cn.leancloud:storage-android:8.2.24'
implementation 'io.reactivex.rxjava2:rxandroid:2.1.1'

<dependency>
    <groupId>cn.leancloud</groupId>
    <artifactId>storage-core</artifactId>
    <version>8.2.24</version>
</dependency>

<dependency org="cn.leancloud" name="storage-core" rev="8.2.24" />

libraryDependencies += "cn.leancloud" %% "storage-core" % "8.2.24"

implementation 'cn.leancloud:storage-core:8.2.24'

Instant Messaging and Push Notification

Android
Maven
Ivy
SBT
Gradle

Use the following packages if you are building an Android app:

implementation 'cn.leancloud:realtime-android:8.2.24'
implementation 'io.reactivex.rxjava2:rxandroid:2.1.1'

To use mixpush:

implementation 'cn.leancloud:mixpush-android:8.2.24'
implementation 'io.reactivex.rxjava2:rxandroid:2.1.1'

<dependency>
    <groupId>cn.leancloud</groupId>
    <artifactId>realtime-core</artifactId>
    <version>8.2.24</version>
</dependency>

<dependency org="cn.leancloud" name="realtime-core" rev="8.2.24" />

libraryDependencies += "cn.leancloud" %% "realtime-core" % "8.2.24"

implementation 'cn.leancloud:realtime-core:8.2.24'

Special notes about Maven

We noticed that sometimes the cache policy of the CDN provided by Maven may not work properly, which makes it unable for certain versions (or certain formats of a version) of our library to be downloaded. If this happens to you, you can try to specify a Sonatype repository in your configuration.

To do so, update pom.xml for Maven:

<repositories>
    <repository>
        <id>oss-sonatype</id>
        <name>oss-sonatype</name>
        <url>https://oss.sonatype.org/content/groups/public/</url>
    </repository>
</repositories>

Update build.gradle for Gradle:

buildscript {
    repositories {
        google()
        jcenter()
        // Add the following configuration
        maven {
            url "https://oss.sonatype.org/content/groups/public/"
        }
    }
}

allprojects {
    repositories {
        google()
        jcenter()
        // Add the following configuration
        maven {
            url "https://oss.sonatype.org/content/groups/public/"
        }
    }
}

Installing Manually

Run the following command to download and install the Java SDK:

$ git clone https://github.com/leancloud/java-unified-sdk.git
$ cd java-unified-sdk/
$ mvn clean install

Download and install the Android SDK:

$ cd java-unified-sdk/
$ cd android-sdk/
$ gradle clean assemble

Initializing Your Project

Credentials

You can view the credentials of your app by going to Developer Center > Your game > Game Services > Configuration:

Client ID, also called App ID, will be used when you initialize the SDK.
Client Token, also called App Key, will be used when you initialize the SDK on the client side.
Server Secret, also called Master Key, will be used when you interact with admin interfaces on trusted environments including your own server and Cloud Engine. When you use it, all the permission checks will be skipped. Make sure to keep it private and never use it in the code for the client.

See Domain for setting up the domain.

Initializing for Android

If you are working on an Android project, add the following lines to the onCreate method of the Application class:

import cn.leancloud.LeanCloud;

public class MyLeanCloudApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // Do not call the initialize method of cn.leancloud.core.LeanCloud, or you will see errors like NetworkOnMainThread.
        LeanCloud.initialize(this, "your-client-id", "your-client-token", "https://your_server_url");
    }
}

Then specify the permissions needed by the SDK and declare the MyLeanCloudApp class in AndroidManifest.xml:

<!-- Basic modules (required) START -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!--  Basic modules END -->

<application
  …
  android:name=".MyLeanCloudApp" >

  <!-- Instant Messaging and Push Notification START -->
  <!-- Both Instant Messaging and Push Notification require PushService -->
  <service android:name="cn.leancloud.push.PushService"/>
  <receiver android:name="cn.leancloud.push.LCBroadcastReceiver">
    <intent-filter>
      <action android:name="android.intent.action.BOOT_COMPLETED"/>
      <action android:name="android.intent.action.USER_PRESENT"/>
      <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
    </intent-filter>
  </receiver>
  <!-- Instant Messaging and Push Notification END -->
</application>

Note: If you’re using Instant Messaging without Push Notification, you can set the LCIMOptions#disableAutoLogin4Push when initializing the SDK so that it will take less time for the users to log in:

// Call after LeanCloud.initialize to disable the automatic login request for Push Notification
LCIMOptions.getGlobalOptions().setDisableAutoLogin4Push(true);

A Safer Way to Initialize the SDK for the Client

For Android developers, starting from version 6.1.0 of our SDK, you can initialize the SDK with a safer method besides using the appId and the appKey. With this method, you can initialize the SDK with the appId only:

import cn.leancloud.LeanCloud;

public class MyLeanCloudApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // Provide `this`, App ID, and the custom API domain as arguments
        LeanCloud.initializeSecurely(this, "{{appid}}", "https://your_server_url");
    }
}

Initializing for Java

If you are working on a Java project, add the following lines to the beginning of your code;

import cn.leancloud.core.LeanCloud;

LeanCloud.initialize("your-client-id", "your-client-token", "https://your_server_url");

Keep in mind that if you are using the SDK within Cloud Engine, you do not need to set the serverUrl. If you are initializing your project with our boilerplate, you will see that the serverUrl is not provided. Please do not call the setServer method as it will make the APIs go through the internet rather than the intranet, which increases the time each request needs to take.

The realtime-core library can be used in Java apps as well, but the way it is used is different than that for Android apps. You will have to explicitly establish a persistent connection (which is handled automatically by PushService in Android). The following code shows how you can establish a persistent connection:

LCConnectionManager.getInstance().startConnection(new LCCallback() {
  @Override
  protected void internalDone0(Object o, LCException e) {
    if (e == null) {
      System.out.println("WebSocket connection established");
    } else {
      System.out.println("Failed to establish WebSocket connection: " + e.getMessage());
    }
  }
});

The messaging functions can be used with the persistent connection established.

Domain

To use TDS cloud services, you must set server_url with the API domain when initializing the SDK. You can obtain a shared domain provided by TDS by going to Developer Center > Your Game > Game Services > Configuration > Domain.

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 your IDE, your browser console, or your Cloud Engine instances’ logs.

// execute before initializing SDK
LeanCloud.setLogLevel(LCLogger.Level.DEBUG);

caution

Make sure debug logs are turned off before your app is published. Failure to do so may lead to the exposure of sensitive data.

Verifying

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

curl "https://{{host}}/1.1/date"

{{host}} is the custom API domain.

If everything goes well, it will return the current date:

{ "__type": "Date", "iso": "2020-10-12T06:46:56.000Z" }

Now add the following code to your project:

LCObject testObject = new LCObject("TestObject");
testObject.put("words", "Hello world!");
testObject.saveInBackground().blockingSubscribe();

Save and run your program.

Then go to Developer Center > Your game > Game Services > Cloud Services > Data Storage > Data > TestObject. If you see a row with its words column being Hello world!, 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 errors, 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 an error.

The Client Cannot Access the Internet

Make sure you have granted the required permissions to your mobile app.

Android Code Obfuscation

To make sure the SDK still works after you obfuscate your code, certain classes and third-party libraries should not be obfuscated:

# proguard.cfg
-keepattributes Signature
-dontwarn com.jcraft.jzlib.**
-keep class com.jcraft.jzlib.**  { *;}
-dontwarn sun.misc.**
-keep class sun.misc.** { *;}
-dontwarn retrofit2.**
-keep class retrofit2.** { *;}
-dontwarn io.reactivex.**
-keep class io.reactivex.** { *;}
-dontwarn sun.security.**
-keep class sun.security.** { *; }
-dontwarn com.google.**
-keep class com.google.** { *;}
-dontwarn cn.leancloud.**
-keep class cn.leancloud.** { *;}
-keep public class android.net.http.SslError
-keep public class android.webkit.WebViewClient
-dontwarn android.webkit.WebView
-dontwarn android.net.http.SslError
-dontwarn android.webkit.WebViewClient
-dontwarn android.support.**
-dontwarn org.apache.**
-keep class org.apache.** { *;}
-dontwarn okhttp3.**
-keep class okhttp3.** { *;}
-keep interface okhttp3.** { *; }
-dontwarn okio.**
-keep class okio.** { *;}
-keepattributes *Annotation*

The Relationships Between the SDK and Different Platforms​

Basic Libraries (Can Be Used in Pure Java Environment)​

Libraries for Android Only​

Dependencies​

Installing SDK​

Data Storage​

Instant Messaging and Push Notification​

Installing Manually​

Initializing Your Project​

Credentials​

Initializing for Android​

A Safer Way to Initialize the SDK for the Client​

Initializing for Java​

Domain​

Enabling Debug Logs​

Verifying​

Debugging​

401 Unauthorized​

The Client Cannot Access the Internet​

Android Code Obfuscation​