云日志服务Android SDK

传输协议

HTTPS

使用前提

• 参考注册华为账号并开通华为云中操作，完成注册。

• 确认云日志服务的区域，请您根据所在区域，选择RegionName。
• 获取华为云账号的项目ID（project id），步骤参考：请参见“我的凭证 > API凭证”。
• 获取需要上报到LTS的日志组ID和日志流ID。
• 日志流需要开启匿名写入功能。详细操作请参考管理日志流。

版本更新说明

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

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

安装Android SDK

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

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

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

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

      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.7.0'// 0.0.x版本依赖版本为1.2.0
             implementation 'com.google.code.gson:gson:2.8.9'
             kapt 'androidx.room:room-compiler:2.3.0'    // 0.0.x版本依赖版本为2.2.6
             api 'androidx.room:room-runtime:2.3.0'      // 0.0.x版本依赖版本为2.2.6
             api 'androidx.room:room-common:2.3.0'       // 0.0.x版本依赖版本为2.2.6
             ...
         }

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

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

         

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

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

   3. 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);

      

      1. 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)

参数获取方式

• 区域表

  表5 区域表

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

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