---
code: android_sdk_installation
name: "Android"
wikiToken: EnSPwbQvsi8Vm4km9JqcbhQ6nv2
parentWikiToken: FTcTwinIOi3OiRkK4MPc2Ex7neg
updateTime: 1773209364000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=android_sdk_installation
---
# Android

::: tip 提示

 在接入前, 请先阅读接入前准备。

Android SDK 要求最低系统版本为 Android 4.0（API 14）

Android SDK ( aar 格式) 大小约为 200 KB

SDK名称：数数科技SDK

开发者：数数信息科技(上海)有限公司

版本号：3.3.6

功能：SDK采用事件、用户属性的方式收集客户端日志，具有统计日活、使用时长、留存行为分析等方面的能力。

隐私声明：数数科技SDK隐私声明

 :::

**最新版本:** 3.3.6

**更新时间:** 2026-03-05

**资源下载: **源代码 下载  

::: warning 注意

当前文档适用于 v3.0.0 及以后的版本，历史版本请参考 Android 接入指南（V2），SDK下载（V2）

::: 

### 一、集成 SDK

#### 1.1 自动集成

- 在 `Project` 级别的 `build.gradle` 文件中添加如下配置依赖
```
buildscript {
    repositories {
        jcenter()
        mavenCentral()
    }
}
```

- 在 `Module` 工程目录下的 `build.gradle`文件中添加依赖项：
```
dependencies {
    implementation 'cn.thinkingdata.android:ThinkingAnalyticsSDK:3.3.6'
}
```

#### 1.2 手动集成 

1. 下载并解压 Android SDK
1. libs 文件夹中添加 TDAnalytics.aar和TDCore.aar
<!-- unsupported block: 24 -->

<!-- unsupported block: 25 -->

<!-- unsupported block: 25 -->

1. 在 build.gradle 添加如下配置
```
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])
}
```

### 二、 初始化

:::: el-tabs

::: el-tab-pane label=Java

```
// 在主线程中初始化 SDK 
//方式一
TDAnalytics.*init*(this, APPID, SERVER_URL);
//方式二
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.*init*(config);
```

:::

::: el-tab-pane label=Kotlin

```
// 在主线程中初始化 SDK 
//方式一
TDAnalytics.*init*(this, APPID, SERVER_URL)
//方式二
val config = TDConfig.getInstance(this,APPID,TE_SERVER_URL)
TDAnalytics.*init*(config);
```

:::

::::

参数说明:

- `APPID`: 您的项目的 APPID，可通过在 AE 项目管理页面获取
- `SERVER_URL`: 数据上传的 URL
- 如果您对接的是云服务，请在项目管理->接入配置中查看上报地址。
- 如果您使用私有化部署版本,您可以自定义数据采集地址。
<!-- unsupported block: 34 -->

由于 Android 9.0+ 默认限制 HTTP 请求，因此请务必使用 HTTPS 协议

### 三、 常用功能

在使用常用功能之前，建议你先了解用户识别规则；SDK默认会生成随机数作为访客ID，并持久化存储访客ID在本地；用户未登录之前，会以访客ID作为身份识别ID。注意:访客 ID 在用户重新安装 App 以及更换设备时将会变更。

#### 3.1 设置账号ID

在用户进行登录时，可调用 `login` 来设置用户的账号 ID， AE 平台将会以账号 ID 作为身份识别 ID，并且设置的账号 ID 将会在调用 `logout` 之前一直保留。多次调用 `login` 将覆盖先前的账号 ID 。

:::: el-tabs

::: el-tab-pane label=Java

```
// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
TDAnalytics.*login*("TA");
```

:::

::: el-tab-pane label=Kotlin

```
// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
TDAnalytics.*login*("TA")
```

:::

::::

<!-- unsupported block: 34 -->

**该方法不会上传登录事件**

#### 3.2 设置公共事件属性

公共事件属性指的就是每个事件都会带有的属性，您可以调用 `setSuperProperties` 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。对于一些重要的属性，譬如用户的会员等级、来源渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。

:::: el-tabs

::: el-tab-pane label=Java

```
try {
        JSONObject superProperties = new JSONObject();
        superProperties.put("channel","ta");//字符串
        superProperties.put("age",1);//数字
        superProperties.put("isSuccess",true);//布尔
        superProperties.put("birthday",new Date());//时间
    
        JSONObject object = new JSONObject();
        object.put("key", "value");
        superProperties.put("object",object);//对象
        
        JSONObject object1 = new JSONObject();
        object1.put("key", "value");
        JSONArray  arr    = new JSONArray();
        arr.put(object1);
        superProperties.put("object_arr",arr);//对象组
        
        JSONArray  arr1    = new JSONArray();
        arr1.put("value");
        superProperties.put("arr",arr1);//数组
        //设置公共事件属性
        TDAnalytics.*setSuperProperties*(superProperties);
    } catch (JSONException e) {
        e.printStackTrace();
    }
```

:::

::: el-tab-pane label=Kotlin

```
val superProperties = JSONObject().*apply ***{**
**    **put("channel", "ta") //字符串
    put("age", 1) //数字
    put("isSuccess", true) //布尔
    put("birthday", Date()) //时间
    put("object",JSONObject().*apply ***{ **//对象
        put("key", "value")
    **}**)
    put("object_arr",JSONArray().*apply ***{ **//对象组
        put(JSONObject().*apply ***{**
**            **put("key", "value")
        **}**)
    **}**)
    put("arr",JSONArray().*apply ***{ **//数组
        put("value")
    **}**)
**}**
TDAnalytics.setSuperProperties(superProperties)
```

:::

::::

公共事件属性将会被保存到缓存中，无需每次启动 App 时调用。如果调用 `setSuperProperties` 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。

- Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,AE 会统一转化为小写字母
- Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组
<!-- unsupported block: 34 -->

**事件属性、用户属性的要求与公共事件属性保持一致**

#### 3.3 开启自动采集

以下代码示例开启安装、启动、关闭事件，如果您想详细了解SDK的自动采集能力，可以查看自动采集功能详细介绍

:::: el-tabs

::: el-tab-pane label=Java

```
//TDAnalytics.TDAutoTrackEventType.*APP_START*  APP安装事件
//TDAnalytics.TDAutoTrackEventType.*APP_START* APP启动事件
//TDAnalytics.TDAutoTrackEventType.*APP_END*  APP关闭事件

//开启自动采集事件
TDAnalytics.*enableAutoTrack*(TDAnalytics.TDAutoTrackEventType.*APP_START *| TDAnalytics.TDAutoTrackEventType.*APP_END*
*        *| TDAnalytics.TDAutoTrackEventType.*APP_INSTALL*);
```

:::

::: el-tab-pane label=Kotlin

```
//TDAnalytics.TDAutoTrackEventType.*APP_START*  APP安装事件
//TDAnalytics.TDAutoTrackEventType.*APP_START* APP启动事件
//TDAnalytics.TDAutoTrackEventType.*APP_END*  APP关闭事件

//开启自动采集事件
TDAnalytics.enableAutoTrack(
    TDAnalytics.TDAutoTrackEventType.*APP_START *or TDAnalytics.TDAutoTrackEventType.*APP_END*
*            *or TDAnalytics.TDAutoTrackEventType.*APP_INSTALL*
)
```

:::

::::

#### 3.4 发送事件

您可以调用 `track` 来上传事件，建议您根据先前梳理的埋点文档来设置事件的属性，此处以用户购买某商品作为范例：

:::: el-tabs

::: el-tab-pane label=Java

```
try {
    JSONObject properties = new JSONObject();
    properties.put("product_name","商品名");
    TDAnalytics.*track*("product_buy", properties);
} catch (JSONException e) {
    e.printStackTrace();
}
```

:::

::: el-tab-pane label=Kotlin

```
val properties = JSONObject()
properties.put("product_name", "商品名")
TDAnalytics.track("product_buy", properties)
```

:::

::::

事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。

#### 3.5 设置用户属性

对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值；如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：

:::: el-tabs

::: el-tab-pane label=Java

```
try {
    //此时username为TA
    JSONObject properties = new JSONObject();
    properties.put("username","TA");
    TDAnalytics.*userSet*(properties);
    //此时userName为TE
    JSONObject newProperties = new JSONObject();
    newProperties.put("username","TE");
    TDAnalytics.*userSet*(newProperties);
} catch (JSONException e) {
    e.printStackTrace();
}
```

:::

::: el-tab-pane label=Kotlin

```
//此时username为TA
val properties = JSONObject()
properties.put("username", "TA")
TDAnalytics.userSet(properties)
//此时userName为TE
val newProperties = JSONObject()
newProperties.put("username", "TE")
TDAnalytics.userSet(newProperties)
```

:::

::::

### 四、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

:::: el-tabs

::: el-tab-pane label=Java

```
if (授权隐私政策) {
    TDAnalytics.*init*(this, APPID, SERVER_URL);
    
    //开启自动采集事件
    TDAnalytics.*enableAutoTrack*(TDAnalytics.TDAutoTrackEventType.*APP_START *| TDAnalytics.TDAutoTrackEventType.*APP_END*
*        *| TDAnalytics.TDAutoTrackEventType.*APP_INSTALL*);
        
    //如果用户已登录，可以设置用户的账号ID作为身份唯一标识
    TDAnalytics.*login*("TA");
    //设置公共事件属性以后，每个事件都会带有公共事件属性
    try {
    JSONObject superProperties = new JSONObject();
    superProperties.put("channel","ta");//字符串
    superProperties.put("age",1);//数字
    superProperties.put("isSuccess",true);//布尔
    superProperties.put("birthday",new Date());//时间
    
    JSONObject object = new JSONObject();
    object.put("key", "value");
    superProperties.put("object",object);//对象
    
    JSONObject object1 = new JSONObject();
    object1.put("key", "value");
    JSONArray  arr    = new JSONArray();
    arr.put(object1);
    superProperties.put("object_arr",arr);//对象组
    
    JSONArray  arr1    = new JSONArray();
    arr1.put("value");
    superProperties.put("arr",arr1);//数组
    //设置公共事件属性
    TDAnalytics.*setSuperProperties*(superProperties);
    } catch (JSONException e) {
    e.printStackTrace();
    }
        
    //发送事件
    try {
    JSONObject properties = new JSONObject();
    properties.put("product_name","商品名");
    TDAnalytics.*track*("product_buy", properties);
    } catch (JSONException e) {
    e.printStackTrace();
    }
    
    //设置用户属性
    try {
    JSONObject userProperties = new JSONObject();
    userProperties.put("username","TA");
    TDAnalytics.*userSet*(userProperties);
    } catch (JSONException e) {
     e.printStackTrace();
    }
}

```

:::

::: el-tab-pane label=Kotlin

```
if (授权隐私政策) {
    TDAnalytics.*init*(this, APPID, SERVER_URL);
    //如果用户已登录，可以设置用户的账号ID作为身份唯一标识
    TDAnalytics.*login*("TA");
    //设置公共事件属性以后，每个事件都会带有公共事件属性
    val superProperties = JSONObject().*apply ***{**
    **    **put("channel", "ta") //字符串
        put("age", 1) //数字
        put("isSuccess", true) //布尔
        put("birthday", Date()) //时间
        put("object",JSONObject().*apply ***{ **//对象
            put("key", "value")
        **}**)
        put("object_arr",JSONArray().*apply ***{ **//对象组
            put(JSONObject().*apply ***{**
    **            **put("key", "value")
            **}**)
        **}**)
        put("arr",JSONArray().*apply ***{ **//数组
            put("value")
        **}**)
    **}**
    //设置公共事件属性
    TDAnalytics.*setSuperProperties*(superProperties);
    
    //开启自动采集事件
    TDAnalytics.enableAutoTrack(
        TDAnalytics.TDAutoTrackEventType.*APP_START *or TDAnalytics.TDAutoTrackEventType.*APP_END*
    *            *or TDAnalytics.TDAutoTrackEventType.*APP_INSTALL*
    )
    
    //发送事件
    val properties = JSONObject()
    properties.put("product_name", "商品名")
    TDAnalytics.track("product_buy", properties)
    
    //设置用户属性
    JSONObject properties = new JSONObject();
    properties.put("username","TA");
    TDAnalytics.*userSet*(properties);
}

```

:::

::::
