编辑文档更新于 2022-03-28

Flutter SDK 安装指南

获取 SDK

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

包依赖管理工具安装

SDK 发布在 pub.dev:

使用数据存储

在 pubspec.yaml 中，将 SDK 添加到依赖项列表:

dependencies:
  flutter:
    sdk: flutter
  ...
  leancloud_storage: ^0.7.10

使用即时通信

即时通信的 Flutter 插件 SDK 基于 Swift SDK 以及 Java Unified SDK 开发。

第一步

在 pubspec.yaml 中，将 SDK 添加到依赖项列表:

dependencies:
  flutter:
    sdk: flutter
  ...
  leancloud_official_plugin: ^1.0.1

第二步

Android 开发者要配置 Gradle 安装 Java Unified SDK，打开工程目录 android/app/build.gradle，添加如下依赖：

dependencies {
  implementation 'cn.leancloud:storage-android:8.2.12'
  implementation 'cn.leancloud:realtime-android:8.2.12'
  implementation 'io.reactivex.rxjava2:rxandroid:2.1.1'
}

iOS 开发者需要通过 CocoaPods 安装 Swift SDK：

$ cd ios/
$ pod update # 或者 $ pod install --repo-update

初始化

首先进入 云服务控制台 > 设置 > 应用凭证 来获取 App ID，App Key 以及服务器地址。

数据存储

使用 SDK 时添加下列导入语句到头部：

import 'package:leancloud_storage/leancloud.dart';

然后在 lib/main.dart 设置 App ID，App Key 以及服务器地址：

LeanCloud.initialize(
    '{{appid}}', '{{appkey}}',
    server: 'https://please-replace-with-your-customized.domain.com',
    queryCache: new LCQueryCache());

请将 https://please-replace-with-your-customized.domain.com 替换为你的应用绑定的 API 域名。

国际版应用不要求绑定自定义域名。如果你的国际版应用（App ID 后缀为 -MdYXbMMI）没有绑定自定义域名，初始化 SDK 时不用传入服务器地址参数。极个别　App ID　后缀不为 -MdYXbMMI 的国际版应用，请参见这里的说明。

Android 权限设置

别忘了在 AndroidManifest.xml 里声明所需的 Android 权限：

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

即时通信

使用 SDK 时添加下列导入语句到头部：

import 'package:leancloud_official_plugin/leancloud_plugin.dart';

使用 Flutter 即时通信插件需要在 Android 和 iOS 平台分别初始化。

Android 平台初始化

首先向 Application 类的 onCreate 方法添加：

import cn.leancloud.LeanCloud;
import cn.leancloud.LCLogger;
import cn.leancloud.im.LCIMOptions;
import io.flutter.app.FlutterApplication;

public class MyLeanCloudApp extends FlutterApplication {
    @Override
    public void onCreate() {
        super.onCreate();
        //开启未读消息数更新通知
        LCIMOptions.getGlobalOptions().setUnreadNotificationEnabled(true);
        //开启调试日志
        LeanCloud.setLogLevel(LCLogger.Level.DEBUG);
        // 提供 this、App ID、App Key、Server Host 作为参数
        // 请将 xxx.example.com 替换为你的应用绑定的 API 域名
        LeanCloud.initialize(this, "{{appid}}", "{{appkey}}", "https://please-replace-with-your-customized.domain.com");
    }
}

然后指定 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" >

  <!-- 即时通讯和推送 START -->
  <!-- 即时通讯和推送都需要 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>
  <!-- 即时通讯和推送 END -->
</application>

iOS 平台初始化

在 AppDelegate.swift 中加入如下初始化代码：

import Flutter
import LeanCloud

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        do {
            LCApplication.logLevel = .all
            try LCApplication.default.set(
                id: "{{appid}}",
                key: "{{appkey}}",
                serverURL: "https://xxx.example.com")
            GeneratedPluginRegistrant.register(with: self)
            return super.application(application, didFinishLaunchingWithOptions: launchOptions)
        } catch {
            fatalError("\(error)")
        }
    }
}

开启调试日志

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

数据存储服务开启调试日志：

// 在 LeanCloud.initialize 初始化之后执行
LCLogger.setLevel(LCLogger.DebugLevel);

即时通信服务开启调试日志方式同 Swift SDK 与 Java Unified SDK。

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

验证

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

curl "https://API_BASE_URL/1.1/date"

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

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

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

然后在项目 lib/main.dart 中编写如下测试代码：

LCObject object = LCObject('TestObject');
object['words'] = 'Hello world!';
await object.save();

保存后运行程序。

然后打开 云服务控制台 > 数据存储 > 结构化数据 > 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，这样就会出现服务端鉴权失败的错误。

客户端无法访问网络

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