# 云日志服务Android SDK 云日志服务Android SDK提供了Kotlin \& Java语言上报日志的一系列方法，如果您需要收集和分析用户在网站上的信息，例如用户的浏览器、浏览行为记录、终端设备记录，设备异常记录，网络使用记录等，可以直接使用Android SDK上报日志到LTS。 ![](https://support.huaweicloud.com/usermanual-lts/public_sys-resources/note_3.0-zh-cn.png) 当前仅华北-北京四、华东-上海一、华南-广州区域的白名单用户支持使用该功能，如有需要请[提交工单](https://support.huaweicloud.com/usermanual-ticket/zh-cn_topic_0127038618.html)申请。 #### 传输协议 HTTPS #### 使用前提 - 参考[注册华为账号并开通华为云](https://support.huaweicloud.com/usermanual-account/account_id_001.html)中操作，完成注册。 - 确认云日志服务的区域，请您根据所在区域，选择RegionName。 - 获取华为云账号的项目ID（project id），步骤请参见[API凭证](https://support.huaweicloud.com/usermanual-ca/ca_01_0002.html)。 - 获取需要上报到LTS的[日志组ID](https://support.huaweicloud.com/usermanual-lts/lts_07_0055.html#lts_07_0055__zh-cn_topic_0000001817927816_zh-cn_topic_0000001672281857_li16213910519)和[日志流ID](https://support.huaweicloud.com/usermanual-lts/lts_07_0055.html#lts_07_0055__zh-cn_topic_0000001817927816_zh-cn_topic_0000001672281857_li521209751)。 #### 版本更新说明 SDK如何处理个人信息请参考[华为云日志服务移动端日志采集SDK隐私声明](https://support.huaweicloud.com/productdesc-lts/lts-07152.html)。 您集成和使用的SDK时需要遵从个人信息保护基本要求，详情请参考[华为云日志服务移动端日志采集SDK开发者合规指南](https://support.huaweicloud.com/productdesc-lts/lts-07151.html)。 表1版本更新说明 | 版本号 | 下载地址 | 检验信息下载地址 | 更新说明 | 系统 | |:---|:---|:---|:---|:---| | 1.0.31 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-ios-sdk-1.0.31.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-ios-sdk-1.0.31.zip.sha256) | 提高日志上报稳定性。 | iOS10、Xcode11及以上。 | | 1.0.28 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.28.aar) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.28.aar.sha256) | 修复了1.0.26版本以来工程配置导致的配置冲突。 | Android 7 及以上 | | 0.0.5 | 请通过mavenCentral下载。 | - | 功能与1.0.28版本相同，可支持kotlin 1.3.x。 | Android 4.3 及以上。 | | 1.0.27 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.27.aar) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.27.aar.sha256) | 优化了缓存效率。 | Android 4.3 及以上 | | 0.0.4 | 请通过mavenCentral下载。 | - | 功能与1.0.27版本相同，可支持kotlin 1.3.x。 | Android 7 及以上。 | | 1.0.26 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.26.aar) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.26.aar.sha256) | 修复了因异步修改入参导致数据异常的问题。 | Android 7 及以上。 | | 1.0.25 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.25.aar) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.25.aar.sha256) | 增强代码强壮性，添加参数保护。 | Android 7 及以上。 | | 1.0.24 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.24.aar) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.24.aar.sha256) | - 支持更多region：华东-上海一、华南-广州。 - 修改了程序目录，修改为com.cloud.lts.\*。 | Android 7 及以上。 | | 1.0.21 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.21.aar) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.21.aar.sha256) | 废弃setconfig方法，使用LTSSDK的构造方法代替。 | Android 7 及以上。 | | 1.0.19 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.19.aar) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.19.aar.sha256) | - 修改了上报时间间隔阈值。 - 修复了修改配置信息后导致无法获取缓存的问题。 | Android 7 及以上。 | | 1.0.18 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.18.aar) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.18.aar.sha256) | - 增强代码强壮性，修复多实例时可能会产生的崩溃。 - 修复最低 Android API 支持版本定义错误的问题。 - 增加设置调试日志级别接口：setLogLevel。 - 修改了 日志发送的入参 label 的类型，支持多层嵌套。 - 日志发送入参 content 支持数组类型，方便使用。 - 添加缓存存储条目最大值支持，如果超过会丢弃后再存储。 - 修改了请求失败时的控制策略，支持递进式等待。 - 对本地错误日志输出做了整理。 | Android 7 及以上。 | | 1.0.17 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.17.aar) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/lts-android-sdk-1.0.17.aar.sha256) | 首次发布，提供四个接口：初始化、配置config、上报日志report、立即上报日志reportImmediately。 | Android 7 及以上。 | #### 安装Android SDK 1. **集成接入SDK。** 1. maven仓库集成。 1. 在build.gradle中添加依赖。 ``` plugins { ... id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false // 添加kotlin插件，1.0.31版本及以上最低支持1.9.20版本，1.0.31版本以下最低支持1.6.20版本，0.0.x最低可支持1.3.61版本 ... } ``` 2. 在app/build.gradle中添加依赖。 ``` dependencies { ... implementation 'io.github.lts-sdk:lts-sdk-android:1.0.31' ... } ``` 3. 在 settings.gradle中添加maven仓库源。 ``` pluginManagement{ ... repositories { ... // 加入下面内容 mavenCentral() } } dependencyResolutionManagement { ... repositories { ... // 加入下面内容 mavenCentral() } } ``` 2. 手动集成。 1. 下载日志SDK包。 2. 下载后解压到指定目录。注：直接解压即可，不需要额外操作。 3. 将解压后的aar静态库文件添加到您的项目工程中。 4. 在build.gradle中添加依赖。 ``` plugins { ... id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false // 添加kotlin插件，1.x.x最低支持1.6.20版本，0.0.x最低可支持1.3.61版本 ... } ``` 5. 在app/build.gradle中添加依赖。 ``` dependencies { ... implementation fileTree(dir: $dir, include: ['*.aar']) // 填写aar所在的文件夹，例如'libs' implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.0' // 0.0.x版本依赖版本为1.3.3 implementation 'androidx.core:core-ktx:1.10.1'// 0.0.x版本依赖版本为1.2.0，1.0.28版本及以下为1.7.0 implementation 'com.google.code.gson:gson:2.8.9' kapt 'androidx.room:room-compiler:2.6.1' // 0.0.x版本依赖版本为2.2.6，1.0.28版本及以下为2.4.0 api 'androidx.room:room-runtime:2.6.1' // 0.0.x版本依赖版本为2.2.6，1.0.28版本及以下为2.4.0 api 'androidx.room:room-common:2.6.1' // 0.0.x版本依赖版本为2.2.6，1.0.28版本及以下为2.4.0 ... } ``` 6. 在 settings.gradle中添加maven仓库源。 如果您的Gradle版本低于7.0 则需要将maven仓库源添加到build.gradle文件中。 ``` pluginManagement{ ... repositories { ... // 加入下面内容 google() mavenCentral() } } dependencyResolutionManagement { ... repositories { ... // 加入下面内容 google() mavenCentral() } } ``` 2. **初始化，详细参数请参考[表4]。** 1. 添加依赖 ``` import com.cloud.lts.UserConfig import com.cloud.lts.LTSSDK ``` 2. Kotlin：初始化代码示例。 ``` //注意：认证用的账号AK、SK硬编码到代码中或者明文存储都有很大的安全风险，建议密文存放，使用时解密，确保安全。 val ak: String = getData("HUAWEICLOUD_SDK_AK") val sk: String = getData("HUAWEICLOUD_SDK_SK") // LTS参数配置 val userConfig = UserConfig.Builder() // 必填参数 .setRegion(USER_REGION) // 云日志服务的区域 .setProjectId(PROJECT_ID) // 账号的项目ID .setGroupId(LOG_GROUP_ID) // LTS的日志组ID .setStreamId(LOG_STREAM_ID) // LTS的日志流ID .setAccessKey(ak) // 访问密钥 .setSecretKey(sk) // 秘密访问密钥 // 选填参数 .setUrlHost(url) // LTS的公网地址域名 .setCacheThreshold(200) .setTimeInterval(60) .setIsReportBackground(true) .setIsReportLaunch(false) .build() // LTS初始化方法 ltssdk = LTSSDK( , userConfig) ``` 3. Java：初始化代码示例。LTSSDK支持多实例日志上报机制，根据不同配置创建实例进行上报。 ``` // 注意：认证用的账号AK、SK硬编码到代码中或者明文存储都有很大的安全风险，建议密文存放，使用时解密，确保安全。 String ak = getData("HUAWEICLOUD_SDK_AK") String sk = getData("HUAWEICLOUD_SDK_SK") // LTS参数配置 UserConfig userConfig = new UserConfig.Builder() // 必填参数 .setRegion(USER_REGION) // 云日志服务的区域 .setProjectId(PROJECT_ID) // 账号的项目ID .setGroupId(LOG_GROUP_ID) // LTS的日志组ID .setStreamId(LOG_STREAM_ID) // LTS的日志流ID .setAccessKey(ak) // 访问密钥 .setSecretKey(sk) // 秘密访问密钥 // 选填参数 .setUrlHost(url) // LTS的公网地址域名 .setCacheThreshold(200) .setTimeInterval(60) .setIsReportBackground(true) .setIsReportLaunch(false) .build()； // LTS初始化方法 ltssdk = new LTSSDK( , userConfig); ``` 3. **上报日志。** LTS提供两种上报日志的方法。 表2两种上报日志的方法 | Method | Description | |:---|:---| | report(content, labels) | 上报日志：先存入本地数据库，根据配置中设定的策略实时上报。 | | reportImmediately(content, labels) | 立即上报日志。 | 表3Parameters参数 | Name | Description | |:---|:---| | content | 日志内容，支持字典和字典数组；键值对最多300个；content转JSON字符串最大支持长度为30\*1024，超出部分被截断。 | | labels | 日志标签。 - 支持字典或空值。 - 最外层键值对最多50个。 - 最外层key最大长度为64。 - 支持字母、数字和下划线组合，首字符须是字母。 - 字典转JSON字符串最大支持长度为30720，超出则该条日志无法上报。 | - Kotlin代码示例如下： ``` var ltssdk: LTSSDK val food = hashMapOf(Pair("food_1", "rice"), Pair("food_2", "wheat"), Pair("food_3", "egg")) val fruit = hashMapOf(Pair("fruit_1", "apple"), Pair("fruit_2", "pear"), Pair("fruit_3", "banana")) val label = hashMapOf( Pair("date","2023-10-01")) val contents = listOf(food, fruit).toTypedArray() ltssdk.report(food, label) // 缓存上报单条 带标签 ltssdk.report(food) // 缓存上报单条 不带标签 ltssdk.reportImmediately(food, label) // 立即上报单条 带标签 ltssdk.reportImmediately(food) // 立即上报单条 不带标签 ltssdk.report(contents, label) // 缓存上报多条 带标签 ltssdk.report(contents) // 缓存上报多条 不带标签 ltssdk.reportImmediately(contents , label) // 立即上报多条 带标签 ltssdk.reportImmediately(contents) // 立即上报多条 不带标签 ``` - Java代码示例如下： ``` LTSSDK ltssdk; HashMap fruit = new HashMap(){{ put("fruit_1", "apple"); put("fruit_2", "pear"); put("fruit_3", "banana"); }}; HashMap food = new HashMap(){{ put("food_1", "rice"); put("food_2", "wheat"); put("food_3", "egg"); }}; HashMap labels = new HashMap(){{ put("date","2023-10-01"); }}; HashMap[] contents = {food, fruit}; ltssdk.report(food); // 缓存上报单条 不带标签 ltssdk.report(food, labels); // 缓存上报单条 带标签 ltssdk.reportImmediately(food); // 立即上报单条 不带标签 ltssdk.reportImmediately(food, labels); // 立即上报单条 带标签 ltssdk.report(contents); // 缓存上报多条 不带标签 ltssdk.report(contents, labels); // 缓存上报多条 带标签 ltssdk.reportImmediately(contents); // 立即上报多条 不带标签 ltssdk.reportImmediately(contents, labels); // 立即上报多条 带标签 ``` #### 配置参数说明 表4初始化参数说明 | 参数名称 | 类型 | 是否必填 | 默认值 | 描述 | |:---|:---|:---|:---|:---| | projectId | String | 必填 | - | 账号的项目ID。 | | accessKey | String | 必填 | - | 账号的访问密钥，简称AK。 认证用的账号AK、SK硬编码到代码中或者明文存储都有很大的安全风险，建议密文存放，使用时解密，确保安全。 | | secretKey | String | 必填 | - | 账号的秘密访问密钥，简称SK。注意：认证用的华为云账号AK、SK硬编码到代码中或者明文存储都有很大的安全风险，建议密文存放，使用时解密，确保安全。 | | region | String | 必填 | - | LTS的服务区域。 | | groupId | String | 必填 | - | LTS的日志组ID。 | | streamId | String | 必填 | - | LTS的日志流ID。 | | url | String | 选填 | null | 用于上报的公网地址域名，如未设置，将根据region自动生成链接，格式如下：https://lts-access.{region}.myhuaweicloud.com | | cacheThreshold | Long | 选填 | 200条 | 当本地数据库日志存储条数达到该值会触发上报，取值范围为30-1000条。 | | timeInterval | Long | 选填 | 3秒 | 定时器每隔该值会触发上报，取值范围为1-1800秒。 | | isReportBackground | boolean | 选填 | true | 是否开启APP切入后台时上报功能。 | | isReportLaunch | boolean | 选填 | false | 是否开启APP启动时上报功能。 | #### 上报日志策略说明 LTSSDK支持四种日志上报策略：阈值上报、定时上报、应用切后台和启动时上报，根据场景选择合适的值配置cacheThreshold、timeInterval、isReportBackground、isReportLaunch等参数。 #### 权限配置 LTSSDK需要Android的网络权限，如果您没有配置，请将下面内容的写入APP的Manifest.xml文件中： ``` manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools"> ... // 加入下面的内容 ... ``` #### 混淆配置 如App对代码进行乱序混淆，则在混淆配置文件中添加代码段： ``` -keep class com.cloud.**{*;} ``` #### 接入调试 在开发过程中可以启用调试模式，借助控制台日志实时查看上报日志的记录情况，观察具体结果并根据需要进行调整。 需要通过调用LTSSDK的静态方法来修改，SDK支持5个级别Debug、Info、Warning、Error和Off，默认值Off。5个级别分别对应的参数：LogLevel.DEBUG、LogLevel.INFO、LogLevel.WARNING、LogLevel.ERROR、LogLevel.OFF。代码示例如下： ``` LTSSDK.setLogLevel(LogLevel.DEBUG) ``` #### 参数获取方式 - 区域表 表5区域表 | 区域名称 | 区域 | |:---|:---| | 华北-北京四 | cn-north-4 | | 华东-上海一 | cn-east-3 | | 华南-广州 | cn-south-1 | - 日志组ID：登录云日志服务页面，选择"日志管理"，鼠标悬浮在日志组名称上，可查看日志组名称和日志组ID。 - 日志流ID：单击"日志组名称"可查看日志流列表，鼠标悬浮在日志流名称上，可查看日志流名称和日志流ID。