编辑文档更新于 2019-09-18

Android / Java SDK 安装指南

平台与 SDK 对应关系

LeanCloud Java SDK 主要包含以下几个 library，其层次结构以及平台对应关系如下：

基础包（可以在纯 Java 环境下调用）

storage-core：包含所有数据存储的功能，如
- 结构化数据（AVObject）
- 内建账户系统（AVUser）
- 查询（AVQuery）
- 文件存储（AVFile）
- 社交关系（AVFriendship，当前版本暂不提供）
- 朋友圈（AVStatus，当前版本暂不提供）
- 短信（AVSMS）
- 等等
realtime-core：部分依赖 storage-core library，实现了 LiveQuery 以及即时通讯功能，如：
- LiveQuery
- AVIMClient
- AVIMConversation 以及多种场景对话
- AVIMMessage 以及多种子类化的多媒体消息
- 等等

Android 特有的包

storage-android：是 storage-core 在 Android 平台的定制化实现，接口与 storage-core 完全相同。
realtime-android：是 realtime-core 在 Android 平台的定制化实现，并且增加 Android 推送相关接口。
mixpush-android：是 LeanCloud 混合推送的 library，支持华为、小米、魅族、vivo 以及 oppo 的官方推送。
leancloud-fcm：是 Firebase Cloud Messaging 的封装 library，供美国节点的 app 使用推送服务。

模块依赖关系

Java SDK 一共包含如下几个模块：

目录	模块名	适用平台	依赖关系
./core	storage-core，存储核心 library	java	无，它是 LeanCloud 最核心的 library
./realtime	realtime-core，LiveQuery 与实时通讯核心 library	java	storage-core
./android-sdk/storage-android	storage-android，Android 存储 library	Android	storage-core
./android-sdk/realtime-android	realtime-android，Android 推送、LiveQuery、即时通讯 library	Android	storage-android, realtime-core
./android-sdk/mixpush-android	Android 混合推送 library	Android	realtime-android
./android-sdk/leancloud-fcm	Firebase Cloud Messaging library	Android	realtime-android

获取 SDK

获取 SDK 有多种方式，较为推荐的方式是通过包依赖管理工具下载最新版本。

包依赖管理工具安装

可以用以下任意包管理工具来安装 SDK。

使用存储功能

Maven：

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

Ivy：

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

SBT：

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

Gradle：

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

如果是 Android 项目，则换成以下这些包：

implementation ('cn.leancloud:storage-android:5.0.26'){
    exclude group: 'com.alibaba', module: 'fastjson'
    exclude group: 'org.ligboy.retrofit2', module: 'converter-fastjson'
}
implementation 'io.reactivex.rxjava2:rxandroid:2.1.0'
implementation 'com.alibaba:fastjson:1.1.70.android'
implementation 'org.ligboy.retrofit2:converter-fastjson-android:2.1.0'

使用即时通讯 / 推送服务

Example for Maven：

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

and for Ivy:

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

and for SBT:

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

and for Gradle:

    implementation('cn.leancloud:realtime-android:5.0.26') {
        exclude group: 'com.alibaba', module: 'fastjson'
        exclude group: 'org.ligboy.retrofit2', module: 'converter-fastjson'
    }
    implementation 'io.reactivex.rxjava2:rxandroid:2.1.0'
    implementation 'com.alibaba:fastjson:1.1.70.android'
    implementation "org.ligboy.retrofit2:converter-fastjson-android:2.1.0"

使用混合推送服务

Example for Gradle：

implementation('cn.leancloud:mixpush-android:5.0.26') {
    exclude group: 'com.alibaba', module: 'fastjson'
    exclude group: 'org.ligboy.retrofit2', module: 'converter-fastjson'
}
implementation 'io.reactivex.rxjava2:rxandroid:2.1.0'
implementation 'com.alibaba:fastjson:1.1.70.android'
implementation "org.ligboy.retrofit2:converter-fastjson-android:2.1.0"

手动安装

下载 SDK

从源码编译

可以执行以下命令获取 Java SDK 并安装：

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

获取和安装 Android SDK：

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

初始化

首先进入控制台 > 设置 > 应用 Key 来获取 App ID 以及 App Key。

Java 平台初始化代码

如果是一个普通 Java 项目，则在代码开头添加：

import cn.leancloud.core.AVOSService;

// 配置 SDK 储存
AVOSCloud.setServer(AVOSService.API, "https://xxx.example.com");
// 配置 SDK 云引擎（用于访问云函数，使用 API 自定义域名，而非云引擎自定义域名）
AVOSCloud.setServer(AVOSService.ENGINE, "https://xxx.example.com");
// 配置 SDK 推送
AVOSCloud.setServer(AVOSService.PUSH, "https://xxx.example.com");
// 配置 SDK 即时通讯
AVOSCloud.setServer(AVOSService.RTM, "https://xxx.example.com");
AVOSCloud.initialize("{{appid}}", "{{appkey}}");

注意，云引擎内部访问 API 是通过内网，所以不需要也不应该配置 API 自定义域名。模板项目和云引擎网站托管开发指南中的示例代码均未配置 API 自定义域名，请勿多此一举 setServer，否则会变成公网访问，影响性能。在使用命令行工具（lean up）本地调试云引擎托管项目时，虽然是公网访问，但命令行工具会自动设置相应的环境变量，供 SDK 访问 API，所以也不需要 setServer。

在自己的服务器上通过 Java SDK 调用云函数，需要在初始化 SDK 时配置 API 自定义域名。

Android 平台初始化

如果是一个 Android 项目，则向 Application 类的 onCreate 方法添加：

import cn.leancloud.AVOSCloud;

public class MyLeanCloudApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // 配置 SDK 储存
        AVOSCloud.setServer(AVOSService.API, "https://xxx.example.com");
        // 配置 SDK 云引擎（用于访问云函数，使用 API 自定义域名，而非云引擎自定义域名）
        AVOSCloud.setServer(AVOSService.ENGINE, "https://xxx.example.com");
        // 配置 SDK 推送
        AVOSCloud.setServer(AVOSService.PUSH, "https://xxx.example.com");
        // 配置 SDK 即时通讯
        AVOSCloud.setServer(AVOSService.RTM, "https://xxx.example.com"); 

        // 提供 this、App ID 和 App Key 作为参数
        // 注意这里千万不要调用 cn.leancloud.core.AVOSCloud 的 initialize 方法，否则会出现 NetworkOnMainThread 等错误。
        AVOSCloud.initialize(this, "{{appid}}", "{{appkey}}");
    }
}

然后指定 SDK 需要的权限并在 AndroidManifest.xml 里面声明 MyLeanCloudApp 类：

<!-- 基本模块（必须）START -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- 基本模块 END -->

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

  <!-- 即时通讯和推送 START -->
  <!-- 即时通讯和推送都需要 PushService -->
  <service android:name="cn.leancloud.push.PushService"/>
  <receiver android:name="cn.leancloud.push.AVBroadcastReceiver">
    <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>
  <!-- 即时通讯和推送 END -->
</application>

开启调试日志

在应用开发阶段，你可以选择开启 SDK 的调试日志（debug log）来方便追踪问题。调试日志开启后，SDK 会把网络请求、错误消息等信息输出到 IDE 的日志窗口，或是浏览器 Console 或是 LeanCloud 控制台的云引擎日志中。

// 在 AVOSCloud.initialize() 之前调用
AVOSCloud.setLogLevel(AVLogger.Level.DEBUG);

在应用发布之前，请关闭调试日志，以免暴露敏感数据。

验证

首先，确认本地网络环境是可以访问 LeanCloud 服务器的，可以执行以下命令：

ping "API_BASE_URL"

API_BASE_URL 为绑定的 API 自定义域名。

如果当前网路正常将会得到如下响应：

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

然后在项目中编写如下测试代码：

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

保存后运行程序。

然后打开控制台 > 存储 > 数据 > TestObject，如果看到如下内容，说明 SDK 已经正确地执行了上述代码，安装完毕。

数据表中出现一行「words」值为「Hello world!」的数据。

如果控制台没有发现对应的数据，请参考问题排查。

问题排查

SDK 安装指南基于当前最新版本的 SDK 编写，所以排查问题前，请先检查下安装的 SDK 是不是最新版本。

`401 Unauthorized`

如果 SDK 抛出 401 异常或者查看本地网络访问日志存在：

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

则可认定为 App ID 或者 App Key 输入有误，或者是不匹配，很多开发者同时注册了多个应用，导致拷贝粘贴的时候，用 A 应用的 App ID 匹配 B 应用的 App Key，这样就会出现服务端鉴权失败的错误。

客户端无法访问网络

客户端尤其是手机端，应用在访问网络的时候需要申请一定的权限。