Skip to content

UBI Android SDK接入指南

依赖条件

Android SDK Version : 21 到 29

Kotlin Version : 1.5.31 +

安装

在项目的build.gradle添加：

1
2
3
4
5
6
7
buildscript {
    repositories {
        ...
        mavenCentral()
        ...
    }
}
在module的build.gradle中添加：

1
2
3
4
5
6
7
8
dependencies {
    ...
    //请替换 latest_version 为更新日志中的最新版本号
    implementation('io.github.yaoina:UbmLib:latest_version@aar'){
        transitive = true
    }
    ...
}
注意：该仓库地址为测试仓库地址，仅供此次接入联调使用。

配置

开启dataBinding功能，在module 的 build.gradle中添加如下片段：

1
2
3
4
5
6
7
android {
    ...
    dataBinding {
        enabled = true
    }
    ...
}

在接入方应用AndroidManifest.xml文件中添加如下tag：

1
2
 <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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
/**
* 关闭SDK时除了关闭本地功能，还涉及到数据异步上传
* 利用回调告知App端异步数据处理结果
*/
UBITracking.disableSDK(onSuccess = {
    //调用成功
},
onFailure = { code, msg ->
    //调用失败，code详见下表说明，msg为错误原因
})

手动开启行程

1
2
3
4
5
6
UBITracking.startTrip(onSuccess = {
    //调用成功
},
onFailure = { code, msg ->
    //调用失败，code详见下表说明，msg为错误原因
})

快速手动开启行程

1
2
3
4
5
6
UBITracking.quickStartTrip(onSuccess = {
    //调用成功
},
onFailure = { code, msg ->
    //调用失败，code详见下表说明，msg为错误原因
})
* 该功能主要包括两部分：1. 申请位置权限（包括低精度、高精度、后台位置权限），提醒用户关闭电池优化；2.开启行程； * 该功能具体说明：1.检查SDK的初始化情况，未初始化回调错误。 2.检查相关权限，如果已经获得则开启行程并回调成功结果。 3. 如果未获得则尝试申请相关权限，如果用户拒绝则返回失败。

手动结束行程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
/**
* 手动结束行程时除了结束本地记录功能，还涉及到数据异步上传；
* 利用回调告知App端异步数据处理结果；
*/
UBITracking.stopTrip(onSuccess = {
    //调用成功
},
onFailure = { code, msg ->
    //调用失败，code详见下表说明，msg为错误原因
})

开启自动监测

1
2
3
4
5
6
UBITracking.startAuto(onSuccess = {
    //调用成功
},
onFailure = { code, msg ->
    //调用失败，code详见下表说明，msg为错误原因
})
* 该功能会使应用运行在后台 自动监测用户是否正在开车并进行记录 * 该功能默认为关闭

快速开启自动监测

1
2
3
4
5
6
UBITracking.quickStartAuto(onSuccess = {
    //调用成功
},
onFailure = { code, msg ->
    //调用失败，code详见下表说明，msg为错误原因
})
* 该功能主要包括两部分：1. 申请位置权限（包括低精度、高精度、后台位置权限），提醒用户关闭电池优化；2.开启自动检测功能； * 该功能具体说明：1.检查SDK的初始化情况，未初始化回调错误。 2.检查相关权限，如果已经获得则开启自动记录并回调成功结果。 3. 如果未获得则尝试申请相关权限，如果用户拒绝则返回失败； * 该功能会使应用运行在后台 自动监测用户是否正在开车并进行记录； * 该功能默认为关闭；

关闭自动监测

1
2
3
4
5
6
UBITracking.stopAuto(onSuccess = {
    //调用成功
},
onFailure = { code, msg ->
    //调用失败，code详见下表说明，msg为错误原因
})

检查是否已获取所需权限

1
val permission = PermissionWizard.checkPermissionGranted(context)

判断行程是否正在记录

1
UBITracking.isTripOnGoing()

判断自动行程是否打开

1
UBITracking.isAutoOn()

权限申请页面

1
2
ActivityResultLauncher.launch()
PermissionWizardActivity::class.java
* 调用方使用ActivityResultLauncher启动该页面，用户设置完权限退出该页面时，调用方可以收到用户是否给予所有权限的回调 - PermissionWizardActivity.PERMISSION_GRANTED --> 用户给予所有权限 - PermissionWizardActivity.PERMISSION_DENIED --> 用户未给予所有权限 * 详细使用方式请参考demo工程 * 该页面暂时只做功能展示 后续会有更完善的页面进行替换

白名单引导页面

1
context.startActivity(Intent(context, UbmWebActivity::class.java))
* 国产Android Rom需要进行允许应用在后台运行的相关配置 该页面用于根据机型引导用户进行设置 * 该页面包含开启/关闭自动监测的按钮

历史行程页面

1
context.startActivity(Intent(context, UbmTripHistorySumActivity::class.java))
* 通过历史行程页面可以点击列表进入行程详情页面 * 该页面是好好开车app的页面 因此某些ui展示与此次紫金接入无关 点击这些UI不会触发响应。待双方产品团队进行讨论后再进行UI的整理、调整。

ErrorCode 说明

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