云日志服务Android SDK

传输协议

HTTPS

使用前提

• 使用云日志SDK前，您需要注册华为账号，并开通云日志服务。
  

  当用户修改权限后，权限信息在一天后生效。

• 确认云日志服务的区域，请用户根据所在区域，选择region。
• 获取华为账号的AK/SK。
• 获取华为云账号的项目ID（project id），步骤参考：请参见“我的凭证 > API凭证”。
• 获取需要上报到LTS的日志组ID和日志流ID。

版本更新说明

SDK如何处理个人信息请参考华为云日志服务移动端日志采集SDK隐私声明。

您集成和使用我们的SDK时需要遵从个人信息保护基本要求，详情请参考华为云日志服务移动端日志采集SDK开发者合规指南。

操作步骤

1. 集成接入SDK。
   1. maven仓库集成。
      • 在build.gradle中添加依赖。

        plugins {
            ...
            id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false  // 添加kotlin插件，最低支持1.6.20版本
            ...
        }

      • 在app/build.gradle中添加依赖。

        dependencies {
            ...
            implementation 'io.github.lts-sdk:lts-sdk-android:1.0.26'
            ...
        }

      • 在 settings.gradle中添加maven仓库源。

        pluginManagement{
            ...
            repositories {
                ...
                // 加入下面内容
                mavenCentral()
           }
        }
        dependencyResolutionManagement {
            ...
            repositories {
                ...
                // 加入下面内容
                mavenCentral()
           }
        }

   2. 手动集成。
      • 下载日志SDK包。
      • 下载后解压到指定目录。注：直接解压即可，不需要额外操作。
      • 将解压后的aar静态库文件添加到您的项目工程中。
      • 在build.gradle中添加依赖。

        plugins {
            ...
            id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false  // 添加kotlin插件，最低支持1.6.20版本
            ...
        }

      • 在app/build.gradle中添加依赖。

        dependencies {
            ...
            implementation fileTree(dir: $dir, include: ['*.aar']) // 填写aar所在的文件夹，例如'libs'
            implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.0'
            implementation 'org.greenrobot:eventbus:3.3.1'
            implementation 'androidx.core:core-ktx:1.5.0'
            implementation 'com.google.code.gson:gson:2.8.9'
            kapt 'androidx.room:room-compiler:2.3.0'
            api 'androidx.room:room-runtime:2.3.0'
            api 'androidx.room:room-common:2.3.0'
            ...
        }

      • 在 settings.gradle中添加maven仓库源。

        pluginManagement{
            ...
            repositories {
                ...
                // 加入下面内容
                google()
                mavenCentral()
           }
        }
        dependencyResolutionManagement {
            ...
            repositories {
                ...
                // 加入下面内容
                google()
                mavenCentral()
           }
        }

        

        • 如果你的Gradle版本低于7.0 则需要将mavan仓库源添加到build.gradle文件中。

2. 初始化，详细参数请参考表4。
   • 添加依赖

     import com.cloud.lts.UserConfig
     import com.cloud.lts.LTSSDK

   • 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( </* Application Instance */> , userConfig)

   • Java：初始化代码示例。

     // 注意：认证用的华为云账号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( </* Application Instance */> , userConfig);

     

     LTSSDK支持多实例日志上报机制，根据不同配置创建实例进行上报。

3. 上报日志。

   LTS提供两种上报日志的方法。

   表2 上报日志的方法

   Method	Description
   report(content, labels)	上报日志：先存入本地数据库，根据配置中设定的策略实施上报。
   reportImmediately(content, labels)	立即上报日志。

   表3 Parameters参数

   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<String, String>(food)    // 缓存上报单条 不带标签
   ltssdk.reportImmediately(food, label)    // 立即上报单条 带标签
   ltssdk.reportImmediately<String, String>(food)    // 立即上报单条 不带标签
   ltssdk.report(contents, label)    // 缓存上报多条 带标签
   ltssdk.report<String, String>(contents)    // 缓存上报多条 不带标签
   ltssdk.reportImmediately(contents , label)    // 立即上报多条 带标签
   ltssdk.reportImmediately<String, String>(contents)    // 立即上报多条 不带标签

   Java代码示例如下：

   LTSSDK ltssdk;
   HashMap fruit = new HashMap<String, String>(){{
       put("fruit_1", "apple");
       put("fruit_2", "pear");
       put("fruit_3", "banana");
   }};
   HashMap food = new HashMap<String, String>(){{
       put("food_1", "rice");
       put("food_2", "wheat");
       put("food_3", "egg");
   }};
   HashMap<String, String> 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);  // 立即上报多条 带标签

配置参数说明

上报日志策略说明

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">
...
// 加入下面的内容
<uses-permission android:name="android.permission.INTERNET" />
...
</manifest>

混淆配置

如App对代码进行乱序混淆，则在混淆配置文件中添加代码段：

-keep class com.cloud.**{*;} 

接入调试

在开发过程中可以启用调试模式，借助控制台日志实时查看上报日志的记录情况，观察具体结果并根据需要进行调整。

需要通过调用LTSSDK的静态方法来修改，SDK支持Debug、Info、Warning 、 Error 和 Off 5个级别的 默认为静默输出（Off）。5个级别分别对应的参数：LogLevel.DEBUG、LogLevel.INFO、LogLevel.WARNING、LogLevel.ERROR、LogLevel.OFF。代码示例如下：

LTSSDK.setLogLevel(LogLevel.DEBUG)

参数获取方式

• 区域表

  区域名称	RegionName
  华北-北京四	cn-north-4
  华东-上海一	cn-east-3
  华南-广州	cn-south-1

• 日志组ID：登录云日志服务页面，选择“日志管理”，鼠标悬浮在日志组名称上，可查看日志组名称和日志组ID。
• 日志流ID：单击“日志组名称”可查看日志流列表，鼠标悬浮在日志流名称上，可查看日志流名称和日志流ID。