跳到主要内容
版本：v3

数据存储、即时通讯 Unreal SDK 配置指南

安装 SDK​

下载 SDK​

可以从 GitHub 获取 SDK 。

导入插件​

从下载的 SDK 中将 LeanCloud 插件拷贝到自己项目的插件目录中，如果下载的是项目工程，那么 LeanCloud 插件路径如下：LeanCloudProject/Plugins/LeanCloud

给 Module 添加依赖​

在使用 LeanCloud 功能的 Module 中添加依赖，找到项目当前 Module 的配置文件，即 Module.build.cs 文件。可以在该文件中的 PublicDependencyModuleNames 或者 PrivateDependencyModuleNames 数组中添加 LeanCloud 的依赖

这样 SDK 就集成完毕了。

初始化​

初始化的方式有两种：配置初始化 和 代码初始化

配置初始化​

你可以通过编辑器 Project Setting 中的 LeanCloud 的配置来设置：

在上面打码的地方填上相关的配置。

代码初始化​

导入头文件：

#include "LCApplication.h"

初始化代码：

FLCApplicationSettings Settings = FLCApplicationSettings();
Settings.AppId = "your-client-id";
Settings.AppKey = "your-client-token";
Settings.ServerUrl = "https://your_server_url";
FLCApplication::Register(Settings);

初始化多个应用​

Unreal 支持多个应用的初始化：

  • 在 配置初始化 中，可以点 + 号，然后填写多个应用的配置。
  • 在 代码初始化 中，多次调用FLCApplication::Register方法来初始化就行。

初始化的应用对象（Application）会当成单例保存起来，多次初始化相同配置只会保存一份，我们通过如下代码来获取应用对象（Application）：

TSharedPtr<FLCApplication> AppPtr = FLCApplication::Get("your-client-id");

我们会把第一个注册的配置设为默认配置，你也可以通过对象 FLCApplication::DefaultPtr 来设置或获取默认配置。

因为支持初始化多个应用，所以后续在 FLCObject、FLCQuery等类中，需要指定应用的配置，如果不指定，那么会使用默认的配置。

应用凭证​

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

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

域名​

使用 TDS 提供的云服务需要绑定 API 自定义域名，以便和其他厂商的应用隔离入口，避免其他应用受到 DDoS 攻击时相互牵连。

初始化客户端 SDK 时 server_url 处填入的就是 API 域名。

绑定 API 域名​

绑定 API 域名的前提是，你拥有一个已经完成备案的域名。

点击查看 API 域名绑定步骤

假设你的域名为 example.com，API 域名绑定步骤和状态如下：

domain guide

  • 进入 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 > 域名配置 > API ，点击 「绑定新域名」 按钮。API 域名不支持直接绑定裸域名，需要在主域名的前面添加自定义名称，也就是绑定一个子域名，比如这里你可以绑定 api.example.com。
  • 控制台显示 「正在检查备案信息」，请等待一会儿。
  • 如果域名没有完成备案，将会显示 「绑定失败」。
  • 域名备案检查通过，域名下方显示 「请配置 DNS」。
  • 此时需要到你的域名服务商控制台，进入域名解析设置页面，添加一条记录，记录类型为 A（A 记录可以将域名指向一个 IP 地址），请将前面填到开发者后台的自定义域名和 「推荐 DNS 配置」 下方 A 记录值复制到对应位置。
  • DNS 解析记录和证书申请（如果选择了自动管理 SSL 证书）都需要一定时间，请耐心等待。记录生效后，控制台便会显示 「已绑定」。

绑定成功后，初始化 SDK 时请传入绑定的自定义域名 https://api.example.com。这里用的是示例，请换成你自己绑定的 API 域名，注意不要遗漏前面的 https://。

配置域名需要一定的时间，TDS 为开发者提供了 共享域名 在游戏测试时使用，但共享域名没有可用性保证，容易受到 DDoS 攻击影响。游戏上线前，一定要确认使用的 API 访问域名是开发者自己绑定的域名，请勿将共享域名用于生产环境。

绑定文件域名​

如果使用了数据存储中的文件服务，包括即时通讯的多媒体消息（图像、音频、视频等），需要绑定文件访问域名。

可前往 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 > 域名配置 > 文件 绑定文件域名，步骤和 API 自定义域名基本相同。但有两点不一样：

  1. API 域名解析使用 A 记录，文件域名解析使用 CNAME 记录。文件域名同样不支持绑定裸域名，需要绑定子域名。例如你的主域名是 example.com，可以绑定文件域名为 files.example.com。
  2. 绑定成功后，还需在 开发与构建 > 数据存储 > 文件 > 设置 > 文件访问地址 点击「修改」按钮进行切换。
信息

每个子域名只能绑定到一个游戏，且 API 域名和文件域名不可使用同样的子域名。如果你已经在 TDS 控制台绑定了某个子域名，重复绑定时控制台会显示「该域名已经被其他应用所绑定」，此时可以更换同一主域名下不同的子域名，来完成后续绑定步骤。

开启日志​

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

// 最好在 Application 初始化代码执行之前执行
FLCApplication::SetLogDelegate(FLeanCloudLogDelegate::CreateLambda([](ELCLogLevel LogLevel, const FString& LogMsg) {
switch (LogLevel) {
case ELCLogLevel::Error: 
  UE_LOG(LogTemp, Error, TEXT("%s"), *LogMsg);
  break;
case ELCLogLevel::Warning: 
  UE_LOG(LogTemp, Warning, TEXT("%s"), *LogMsg);
  break;
case ELCLogLevel::Debug:
  UE_LOG(LogTemp, Display, TEXT("%s"), *LogMsg);
  break;
case ELCLogLevel::Verbose:
  UE_LOG(LogTemp, Display, TEXT("%s"), *LogMsg);
  break;
default: ;
}
警告

在应用发布之前，请调高打印日志的级别，以免暴露敏感数据。

验证​

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

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

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

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

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

问题排查​

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

401 Unauthorized​

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

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

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

客户端无法访问网络​

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