Skip to content

UBI Flutter SDK接入指南

引言

在接入 SDK 之前，请您仔细阅读本引言内容。该内容非常重要！

  • 请在用户同意隐私政策之后调用初始化接口；

  • 请尽可能早的调用初始化接口；

  • 请在调用初始化接口后再调用其他接口，否则会导致早于初始化接口调用的接口执行失败；

安装

添加依赖

直接依赖开源Git库

在项目的pubspec.yaml文件中添加以下内容:

1
2
3
4
5
6
7
...
dependencies:
  ...
  flutter_ubi:
      git:
        url: git@gitee.com:baixingkefu/flutter_ubi.git
...

依赖官方仓库中的插件

后续会发布 Flutter 版 SDK 至官方仓库，引入方式也将改为如下方式（x.y.z为示例的版本号），具体版本号参见更新日志：

1
2
3
4
5
...
dependencies:
  ...
  flutter_ubi: ^x.y.z
...

安装插件

运行以下命令拉取插件：

1
$ flutter pub get

配置

Android项目配置

Android版SDK依赖的最低系统版本为21；如果打包过程中提醒 minSdkVersion 过低，请打开 android/app/build.gradle 文件，进行如下修改：

1
2
3
4
5
6
7
8
9
android{
  ...
  defaultConfig{
    ...
    minSdkVersion 21
    ...
  }
  ...
}

iOS项目配置

  1. 使用 Xcode 打开 Flutter 项目中的 iOS 子项目，勾选必要的设置项；

avatar

  1. 接着打开 iOS 子项目中的 info.plist 文件，添加定位、运动与健身的使用说明，请根据实际业务场景填写说明文字；

avatar

使用

导入依赖

在Dart代码中添加以下代码：

1
import 'package:flutter_ubi/flutter_ubi.dart';

API列表

初始化SDK

使用 userId 和 passportToken 初始化 SDK, 当 passportToken 过期之后，会回调 refreshPassportToken 方法获取新的token;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
//userId : 百姓车联服务器生成的用户ID
//passportToken : 百姓车联服务器生成的用于身份认证的token
//refreshPassportToken : 当 passportToken 过期之后，会回调该方法获得新的 passportToken
UBIResult result = await FlutterUbi.enableSDK(
  userId: "userId",
  passportToken: "passport token",
  refreshPassportToken: () => _getRefreshToken());
if(result.isSuccessful()){
  //初始化SDK成功
}else{
  //初始化SDK失败，请使用 result.code 对照后文的 ErrorCode 表查看具体错误原因
}
  • 该方法所需的 userId 和 passportToken 皆是百姓车联服务器生成的；
  • 在APP启动后，请尽可能早的调用该方法；
  • 请在调用初始化接口后再调用其他接口，否则会导致早于初始化接口调用的接口执行失败。

关闭SDK

该方法会结束行程、停止自动监测，将 SDK 重置为未初始化状态；

1
2
3
4
5
6
UBIResult result = await FlutterUbi.disableSDK();
if(result.isSuccessful()){
  //关闭 SDK 成功
}else{
  //关闭 SDK 失败，请使用 result.code 对照后文的 ErrorCode 表查看具体错误原因
}

开始手动行程

开启本地记录功能；

1
2
3
4
5
6
UBIResult result = await FlutterUbi.startTrip();
if(result.isSuccessful()){
  //开始手动行程成功
}else{
  //开始手动行程失败，请使用 result.code 对照后文的 ErrorCode 表查看具体错误原因
}
* 如果在调用该方法之前没有授予所需的权限，则会返回失败；

快速手动开启行程

申请所需权限，然后开启行程；

1
2
3
4
5
6
UBIResult result = await FlutterUbi.quickStartTrip();
if(result.isSuccessful()){
  //快速手动开启行程成功
}else{
  //快速手动开启行程失败，请使用 result.code 对照后文的 ErrorCode 表查看具体错误原因
}
  • 该功能主要包括两部分：1. 申请权限；在Android上是申请低精度、高精度、后台位置权限，以及关闭电池优化；在iOS上是申请位置权限、运动与健康、后台App刷新；2.开启手动行程；
  • 由于Android和iOS系统的申请权限的方式不同，该功能在这两个系统上的行为表现略有差异；
  • 在Android上执行的逻辑是：1.检查SDK的初始化情况，未初始化则返回错误。 2.检查相关权限，如果已经获得则开启手动行程并返回成功。 3. 如果未获得则尝试申请相关权限，如果用户拒绝授权则返回失败，如果授予权限则开始手动行程并返回成功；
  • 在iOS上执行的逻辑是：1.检查SDK的初始化情况，未初始化则返回错误。 2.检查相关权限，如果已经获得则开启手动行程并返回成功。 3. 如果未获取或未选择则弹窗引导用户开启权限，如果用户拒绝授权则返回失败，如果授予权限则开始手动行程并返回成功；；

结束手动行程

结束本地记录功能，上传数据；

1
2
3
4
5
6
UBIResult result = await FlutterUbi.stopTrip();
if(result.isSuccessful()){
  //结束手动行程成功
}else{
  //结束手动行程失败，请使用 result.code 对照后文的 ErrorCode 表查看具体错误原因
}

打开自动监测

打开自动监测功能，该功能会在后台监测用户是否处于驾驶中，如果是则开启自动行程；

1
2
3
4
5
6
UBIResult result = await FlutterUbi.startAuto();
if(result.isSuccessful()){
  //打开自动监测成功
}else{
  //打开自动监测失败，请使用 result.code 对照后文的 ErrorCode 表查看具体错误原因
}
* 该功能会使应用运行在后台，自动监测用户是否正在开车并进行记录； * 该功能默认为关闭；

快速打开自动监测

申请权限，然后打开自动监测功能；

1
2
3
4
5
6
UBIResult result = await FlutterUbi.quickStartAuto();
if(result.isSuccessful()){
  //快速打开自动监测成功
}else{
  //快速打开自动监测失败，请使用 result.code 对照后文的 ErrorCode 表查看具体错误原因
}
  • 该功能主要包括两部分：1. 申请权限：在Android上是申请低精度、高精度、后台位置权限，以及关闭电池优化；在iOS上申请位置权限、运动与健康、后台App刷新；2.开启自动监测功能；
  • 由于Android和iOS系统的申请权限的方式不同，该功能在这两个系统上的行为表现略有差异；
  • 在Android上执行的逻辑是：1.检查SDK的初始化情况，未初始化则返回错误。 2.检查相关权限，如果已经获得则开启自动监测并返回成功。 3. 如果未获得则尝试申请相关权限，如果用户拒绝授权则返回失败，如果授予权限则开始自动监测并返回成功；
  • 在iOS上执行的逻辑是：1.检查SDK的初始化情况，未初始化则返回错误。 2.检查相关权限，如果已经获得则开启自动监测并返回成功。 3. 如果未获取或未选择则弹窗引导用户开启权限，如果用户拒绝授权则返回失败，如果授予权限则开始自动监测并返回成功；
  • 该功能会使应用运行在后台，自动监测用户是否正在开车并进行记录；
  • 该功能默认为关闭；

关闭自动监测

1
2
3
4
5
6
UBIResult result = await FlutterUbi.stopAuto();
if(result.isSuccessful()){
  //关闭自动监测成功
}else{
  //关闭自动监测失败，请使用 result.code 对照后文的 ErrorCode 表查看具体错误原因
}

打开白名单/权限引导页面

引导 Android 用户打开位置权限、打开自启动权限、关闭电池优化、打开自动记录； 引导 iOS用户打开位置权限、打开运动与健康、打开自动记录；

1
FlutterUbi.showWhiteListPage();

打开权限设置页面

打开权限设置页面，在该页面会引导用户打开应用运行所需要的权限；在 Android 上，会引导用户打开低精度位置权限、高精度位置权限、后台位置权限，以及关闭电池优化；在iOS上，引导用户打开位置权限、打开运动与健康；

1
FlutterUbi.showPermissionPage();

打开历史行程页面

展示当前用户的所有的历史行程的汇总信息、单个历史行程的详细信息；

1
FlutterUbi.showTripHistoryPage();

权限检查

检查当前是否已经授予了记录行程所需的权限；在Android上是低精度位置权限、高精度位置权限、后台位置权限；在iOS上是位置权限、运动与健康权限；

1
2
//result: 是否已经授予记录行程所需的权限
bool result = await FlutterUbi.checkPermission();

判断是否开启了自动监测

1
2
//result: 是否开启了自动监测
bool result = await FlutterUbi.isAutoOn();

判断行程是否正在记录中

1
2
//result：当前是否有行程正在记录中
bool result = await FlutterUbi.isTripOnGoing();

ErrorCode 说明

值 说明
0 成功
1 未知错误
1000 调用参数错误
2000 SDK未初始化
3000 没有获取所需权限
4001 上传文件失败
4002 没有运行中的行程
4003 调用操作不是在主进程进行