UBI Flutter SDK接入指南
引言
在接入 SDK 之前,请您仔细阅读本引言内容。该内容非常重要!
- 请在Flutter项目的
main()
中调用初始化接口FlutterUbi.init()
;在Android子项目的Appliation.onCreate()中调用FlutterUbiPlugin.init()
; - 请在初始化成功之后再调用其他接口,否则其他的接口调用会失败;
- 在用户登录和登出后需要分别调用
FlutterUbi.login()
和FlutterUbi.logout()
接口,详见下文API列表说明;
安装
添加依赖
直接依赖开源Git库
在项目的pubspec.yaml文件中添加以下内容:
1 2 3 4 5 6 7 |
|
依赖官方仓库中的插件
后续会发布 Flutter 版 SDK 至官方仓库,引入方式也将改为如下方式(x.y.z为示例的版本号),具体版本号参见更新日志:
1 2 3 4 5 |
|
安装插件
运行以下命令拉取插件:
1 |
|
配置
Android项目配置
Android版SDK依赖的最低系统版本为21;如果打包过程中提醒 minSdkVersion 过低,请打开 android/app/build.gradle 文件,进行如下修改:
1 2 3 4 5 6 7 8 9 |
|
iOS项目配置
- 使用 Xcode 打开 Flutter 项目中的 iOS 子项目,勾选必要的设置项;
- 接着打开 iOS 子项目中的 info.plist 文件,添加定位、运动与健身的使用说明,请根据实际业务场景填写说明文字;
使用
导入依赖
在Dart代码中添加以下代码:
1 |
|
初始化
-
请在Flutter项目的
main()
中调用初始化接口FlutterUbi.init()
; -
在Android子项目的
Appliation.onCreate()
中调用FlutterUbiPlugin.init()
;
API列表
初始化SDK
该方法会进行一些初始化操作,然后开启SDK。如果开启SDK失败,则不能调用开启手动行程、快速开启手动行程、打开自动检测、快速打开自动检测等方法。该方法需要传入一个 RefreshPassportToken
类型的静态方法或者顶级方法作为参数。
接入方需要实现 RefreshPassportToken
用于刷新用户的 Passport Token。供参考的实现逻辑:如果APP处于未登录状态,返回null即可,否则从接入方的后端服务器请求ubiUserId和ubiPassportToken并返回。 RefreshPassportToken定义如下:
1 |
|
调用示例:
1 2 3 4 5 6 7 8 9 10 11 12 |
|
注意:
- 请在
main()
中调用初始化接口; - 请在调用初始化接口成功之后再调用其他接口,否则会导致早于初始化接口调用的接口执行失败;
- 由于RefreshPassportToken会运行在非主Isolate中,所以需要在RefreshPassportToken方法中进行第三方库的初始化工作;
用户登录
当用户登录成功后,调用该方法,该方法会开启SDK;
调用示例:
1 2 3 4 5 6 |
|
用户登出
当用户登出后,调用该方法,该方法会关闭SDK;
调用示例:
1 2 3 4 5 6 |
|
开启SDK
使用 userId 和 passportToken 开启SDK, 当 passportToken 过期之后,会回调 refreshPassportToken 方法获取新的token;
1 2 3 4 5 6 7 8 9 10 11 12 |
|
注意:
- 该方法所需的 userId 和 passportToken 皆是由百姓车联服务器生成的;
- 一般情况先不需要直接调用该API;
关闭SDK
该方法会结束行程、停止自动监测,然后将 SDK 重置为未初始化状态;
1 2 3 4 5 6 |
|
注意:
- 一般情况先不需要直接调用该API;
开始手动行程
开启本地记录功能;
1 2 3 4 5 6 |
|
- 如果在调用该方法之前没有授予所需的权限,则会返回失败;
快速手动开启行程
申请所需权限,然后开启行程;
1 2 3 4 5 6 |
|
- 该功能主要包括两部分:1. 申请权限;在Android上是申请低精度、高精度、后台位置权限,以及关闭电池优化;在iOS上是申请位置权限、运动与健康、后台App刷新;2.开启手动行程;
- 由于Android和iOS系统的申请权限的方式不同,该功能在这两个系统上的行为表现略有差异;
- 在Android上执行的逻辑是:1.检查SDK的初始化情况,未初始化则返回错误。 2.检查相关权限,如果已经获得则开启手动行程并返回成功。 3. 如果未获得则尝试申请相关权限,如果用户拒绝授权则返回失败,如果授予权限则开始手动行程并返回成功;
- 在iOS上执行的逻辑是:1.检查SDK的初始化情况,未初始化则返回错误。 2.检查相关权限,如果已经获得则开启手动行程并返回成功。 3. 如果未获取或未选择则弹窗引导用户开启权限,如果用户拒绝授权则返回失败,如果授予权限则开始手动行程并返回成功;;
结束手动行程
结束本地记录功能,上传数据;
1 2 3 4 5 6 |
|
打开自动监测
打开自动监测功能,该功能会在后台监测用户是否处于驾驶中,如果是则开启自动行程;
1 2 3 4 5 6 |
|
快速打开自动监测
申请权限,然后打开自动监测功能;
1 2 3 4 5 6 |
|
- 该功能主要包括两部分:1. 申请权限:在Android上是申请低精度、高精度、后台位置权限,以及关闭电池优化;在iOS上申请位置权限、运动与健康、后台App刷新;2.开启自动监测功能;
- 由于Android和iOS系统的申请权限的方式不同,该功能在这两个系统上的行为表现略有差异;
- 在Android上执行的逻辑是:1.检查SDK的初始化情况,未初始化则返回错误。 2.检查相关权限,如果已经获得则开启自动监测并返回成功。 3. 如果未获得则尝试申请相关权限,如果用户拒绝授权则返回失败,如果授予权限则开始自动监测并返回成功;
- 在iOS上执行的逻辑是:1.检查SDK的初始化情况,未初始化则返回错误。 2.检查相关权限,如果已经获得则开启自动监测并返回成功。 3. 如果未获取或未选择则弹窗引导用户开启权限,如果用户拒绝授权则返回失败,如果授予权限则开始自动监测并返回成功;
- 该功能会使应用运行在后台,自动监测用户是否正在开车并进行记录;
- 该功能默认为关闭;
关闭自动监测
1 2 3 4 5 6 |
|
打开白名单/权限引导页面
引导 Android 用户打开位置权限、打开自启动权限、关闭电池优化、打开自动记录; 引导 iOS用户打开位置权限、打开运动与健康、打开自动记录;
1 |
|
打开权限设置页面
打开权限设置页面,在该页面会引导用户打开应用运行所需要的权限;在 Android 上,会引导用户打开低精度位置权限、高精度位置权限、后台位置权限,以及关闭电池优化;在iOS上,引导用户打开位置权限、打开运动与健康;
1 |
|
打开历史行程页面
展示当前用户的所有的历史行程的汇总信息、单个历史行程的详细信息;
1 |
|
权限检查
检查当前是否已经授予了记录行程所需的权限;在Android上是低精度位置权限、高精度位置权限、后台位置权限;在iOS上是位置权限、运动与健康权限;
1 2 |
|
是否开启了自动监测
1 2 |
|
行程是否正在记录中
1 2 |
|
SDK是否已经开启
SDK开启之后调用开启手动行程、快速开启手动行程、打开自动检测、快速打开自动检测等API才能获得有效的结果;
1 2 |
|
ErrorCode 说明
值 | 说明 |
---|---|
0 | 成功 |
1 | 未知错误 |
1000 | 调用参数错误 |
2000 | SDK未初始化 |
3000 | 没有获取所需权限 |
4001 | 上传文件失败 |
4002 | 没有运行中的行程 |
4003 | 调用操作不是在主进程进行 |