UBI Android SDK接入指南
依赖条件
Android SDK Version : 21 到 29
Kotlin Version : 1.5.31 +
安装
在项目的build.gradle添加:
| buildscript {
repositories {
...
mavenCentral()
...
}
}
|
在module的build.gradle中添加:
| dependencies {
...
//请替换 latest_version 为更新日志中的最新版本号
implementation('io.github.yaoina:UbmLib:latest_version@aar'){
transitive = true
}
...
}
|
注意:该仓库地址为测试仓库地址,仅供此次接入联调使用。
配置
开启dataBinding功能,在module 的 build.gradle中添加如下片段:
| android {
...
dataBinding {
enabled = true
}
...
}
|
在接入方应用AndroidManifest.xml文件中添加如下tag:
| <application
android:requestLegacyExternalStorage="true"/>
|
API使用
开启SDK
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28 | /**
* 调用sdk任何方法前请先调用该方法,否则调用sdk其他方法会产生错误。
* UBICredentialProvider提供获取UBI passport token与刷新该token的方法,
* 需要App端实现该类,SDK会在与服务器交互时使用passport token以及
* 在passport token过期时自动调用refreshPassportToken()进行刷新。
* 建议使用网络库的同步接口实现该回调,SDK会在子线程中执行该请求,
* 接口失败时return null即可。
*
* userId为该用户的唯一标识
*/
val passportToken = "UBI passport token"
val provider = object : UBICredentialProvider(passportToken) {
override fun refreshPassportToken(): String? {
// 刷新passport token
}
}
val userId = "UBI user id"
UBITracking.enableSDK(
userId,
provider,
onSuccess = {
//调用成功
},
onFailure = { code, msg ->
//调用失败,code详见下表说明,msg为错误原因
})
|
* 该方法为开启UBI功能的方法 在调用其他方法前请先调用此方法 否则会抛出异常
* 建议在Application.onCreate()
中调用该方法
* 失败时回调的code详细说明见 ErrorCode说明
关闭SDK
| /**
* 关闭SDK时除了关闭本地功能,还涉及到数据异步上传
* 利用回调告知App端异步数据处理结果
*/
UBITracking.disableSDK(onSuccess = {
//调用成功
},
onFailure = { code, msg ->
//调用失败,code详见下表说明,msg为错误原因
})
|
手动开启行程
| UBITracking.startTrip(onSuccess = {
//调用成功
},
onFailure = { code, msg ->
//调用失败,code详见下表说明,msg为错误原因
})
|
快速手动开启行程
| UBITracking.quickStartTrip(onSuccess = {
//调用成功
},
onFailure = { code, msg ->
//调用失败,code详见下表说明,msg为错误原因
})
|
* 该功能主要包括两部分:1. 申请位置权限(包括低精度、高精度、后台位置权限),提醒用户关闭电池优化;2.开启行程;
* 该功能具体说明:1.检查SDK的初始化情况,未初始化回调错误。 2.检查相关权限,如果已经获得则开启行程并回调成功结果。 3. 如果未获得则尝试申请相关权限,如果用户拒绝则返回失败。
手动结束行程
| /**
* 手动结束行程时除了结束本地记录功能,还涉及到数据异步上传;
* 利用回调告知App端异步数据处理结果;
*/
UBITracking.stopTrip(onSuccess = {
//调用成功
},
onFailure = { code, msg ->
//调用失败,code详见下表说明,msg为错误原因
})
|
开启自动监测
| UBITracking.startAuto(onSuccess = {
//调用成功
},
onFailure = { code, msg ->
//调用失败,code详见下表说明,msg为错误原因
})
|
* 该功能会使应用运行在后台 自动监测用户是否正在开车并进行记录
* 该功能默认为关闭
快速开启自动监测
| UBITracking.quickStartAuto(onSuccess = {
//调用成功
},
onFailure = { code, msg ->
//调用失败,code详见下表说明,msg为错误原因
})
|
* 该功能主要包括两部分:1. 申请位置权限(包括低精度、高精度、后台位置权限),提醒用户关闭电池优化;2.开启自动检测功能;
* 该功能具体说明:1.检查SDK的初始化情况,未初始化回调错误。 2.检查相关权限,如果已经获得则开启自动记录并回调成功结果。 3. 如果未获得则尝试申请相关权限,如果用户拒绝则返回失败;
* 该功能会使应用运行在后台 自动监测用户是否正在开车并进行记录;
* 该功能默认为关闭;
关闭自动监测
| UBITracking.stopAuto(onSuccess = {
//调用成功
},
onFailure = { code, msg ->
//调用失败,code详见下表说明,msg为错误原因
})
|
检查是否已获取所需权限
| val permission = PermissionWizard.checkPermissionGranted(context)
|
判断行程是否正在记录
| UBITracking.isTripOnGoing()
|
判断自动行程是否打开
权限申请页面
| ActivityResultLauncher.launch()
PermissionWizardActivity::class.java
|
* 调用方使用ActivityResultLauncher启动该页面,用户设置完权限退出该页面时,调用方可以收到用户是否给予所有权限的回调
- PermissionWizardActivity.PERMISSION_GRANTED --> 用户给予所有权限
- PermissionWizardActivity.PERMISSION_DENIED --> 用户未给予所有权限
* 详细使用方式请参考demo工程
* 该页面暂时只做功能展示 后续会有更完善的页面进行替换
白名单引导页面
| context.startActivity(Intent(context, UbmWebActivity::class.java))
|
* 国产Android Rom需要进行允许应用在后台运行的相关配置 该页面用于根据机型引导用户进行设置
* 该页面包含开启/关闭自动监测的按钮
历史行程页面
| context.startActivity(Intent(context, UbmTripHistorySumActivity::class.java))
|
* 通过历史行程页面可以点击列表进入行程详情页面
* 该页面是好好开车app的页面 因此某些ui展示与此次紫金接入无关 点击这些UI不会触发响应。待双方产品团队进行讨论后再进行UI的整理、调整。
ErrorCode 说明
值 |
说明 |
0 |
成功 |
1 |
未知错误 |
1000 |
调用参数错误 |
2000 |
SDK未初始化 |
3000 |
没有获取所需权限 |
4001 |
上传文件失败 |
4002 |
没有运行中的行程 |
4003 |
调用操作不是在主进程进行 |