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 调用操作不是在主进程进行