数据存储 Java SDK 配置指南

获取 SDK

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

使用包管理工具下载

我们已经将所有的 library 发布到了 maven 中心仓库，开发者可以用以下任意包管理工具来安装 SDK。

Android

如果是 Android 项目，使用这些包：

implementation 'com.taptap:lc-storage-android:8.2.24'
implementation 'io.reactivex.rxjava2:rxandroid:2.1.1'

Maven

<dependency>
    <groupId>com.taptap</groupId>
    <artifactId>lc-storage-core</artifactId>
    <version>8.2.24</version>
</dependency>

Ivy

<dependency org="com.taptap" name="lc-storage-core" rev="8.2.24" />

SBT

libraryDependencies += "com.taptap" %% "lc-storage-core" % "8.2.24"

Gradle

implementation 'com.taptap:lc-storage-core:8.2.24'

点击查看对 maven 源的特别说明

我们发现有时候 Maven 源的 CDN 缓存同步策略出现问题，可能会导致我们某个版本或者该版本下某种格式的 library 文件无法下载，这时候你可以在配置文件中显式增加一个 Sonatype 的源，就可以解决找不到文件的问题。

Maven pom.xml 的修改示例如下：

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

Gradle build.gradle 的修改示例如下：

buildscript {
    repositories {
        google()
        jcenter()
        // 增加下面的配置
        maven {
            url "https://oss.sonatype.org/content/groups/public/"
        }
    }
}

allprojects {
    repositories {
        google()
        jcenter()
        // 增加下面的配置
        maven {
            url "https://oss.sonatype.org/content/groups/public/"
        }
    }
}

手动安装

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

$ git clone https://github.com/taptap/TapSDK-LC-Java.git
$ cd TapSDK-LC-Java/
$ mvn clean install

获取和安装 Android SDK：

$ cd TapSDK-LC-Java/
$ cd android-sdk/
$ gradle clean assemble

初始化

应用凭证

在 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 可以查看应用的基本信息：

• Client ID：又称 App ID，在 SDK 初始化时用到。
• Client Token：又称 App Key，客户端对服务端的调用凭证，在 SDK 初始化时用到。
• 域名配置 > 云服务 API：又称 API 域名或 Server URL，在客户端 SDK 初始化时用到。域名配置参考下一节域名。
• Server Secret：又称 Master Key，用于在自有服务器、云引擎等受信任环境调用管理接口，具备跳过一切权限验证的超级权限。所以一定注意保密，千万不要在客户端代码中使用该凭证。

Android 平台初始化

信息

TapSDK 初始化时，会自动执行这一节的初始化方法。

如果已经参考 快速开始 文档完成了 TapSDK 初始化，则不需要参考这里的初始化。

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

import com.tapsdk.lc.LeanCloud;

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

        // 注意这里千万不要调用 com.tapsdk.lc.core.LeanCloud 的 initialize 方法，否则会出现 NetworkOnMainThread 等错误。
        LeanCloud.initialize(this, "your-client-id", "your-client-token", "https://your_server_url");
    }
}

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

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

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

</application>

Java 平台初始化

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

import com.tapsdk.lc.core.LeanCloud;

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

注意，云引擎内部访问 API 是通过内网，所以不需要也不应该配置 API 自定义域名（serverUrl）。 模板项目和示例代码均未配置 API 自定义域名， 请勿调用 setServer，否则会变成公网访问，影响性能。

域名

使用 TDS 提供的云服务，初始化客户端 SDK 需要在 server_url 处填入 API 域名，可前往 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 > 域名配置 获取 TDS 提供的 共享域名。

开启调试日志

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

// 在初始化之前调用
LeanCloud.setLogLevel(LCLogger.Level.DEBUG);

详细调试流程可以参考Android SDK 调试指南。

警告

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

验证

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

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

{{host}} 为绑定的 API 自定义域名。

如果当前网络正常会返回当前时间：

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

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

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

保存后运行程序。

然后打开 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 数据存储 > 结构化数据 > TestObject，如果看到数据表中出现一行「words」列的值为「Hello world!」的数据，说明 SDK 已经正确地执行了上述代码，配置完毕。

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

问题排查

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

401 Unauthorized

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

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

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

客户端无法访问网络

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

Android 代码混淆

为了保证 SDK 在代码混淆后能正常运作，需要保证部分类和第三方库不被混淆，参考下列配置：

# 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 com.tapsdk.lc.**
-keep class com.tapsdk.lc.** { *;}
-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*