---
code: golang_sdk_installation
name: "Golang"
wikiToken: LopRwvKpWiKdXdkB9YSck9ImnVf
parentWikiToken: O3YxwgHGiiEnvYkHCcIcX51inkf
updateTime: 1745310918000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=golang_sdk_installation
---
# Golang

::: tip 提示

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

 :::

**最新版本为**：v2.1.0

**更新时间为**：2024-12-19

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

::: warning 注意

当前文档适用于 v2.0.0 及以后的版本，历史版本请参考 Go SDK 接入指南（V1）

::: 

### 一、集成SDK

1. 我们提供两种方案集成SDK：
方案一: 执行以下命令获取最新版 Golang SDK

```
# 获取 SDK
go get github.com/ThinkingDataAnalytics/go-sdk/v2

# 更新 SDK
go get -u github.com/ThinkingDataAnalytics/go-sdk/v2
```

方案二: Module模式

```
//在代码文件开头引入thinkingdata
import "github.com/ThinkingDataAnalytics/go-sdk/v2/src/thinkingdata"

# 拉取最新SDK模块
go mod tidy
```

1. 安装LogBus
我们推荐使用SDK+LogBus的形式，完成服务端数据的采集上报.您可以参考以下文档完成Logbus的安装:LogBus使用指南 

### 二、初始化

以下是SDK初始化的示例代码:

```
// 创建 LogConfig 配置文件
config := thinkingdata.TDLogConsumerConfig {
    FileNamePrefix: "test_prefix", // log file prefix
    Directory: "LOG_DIRECTORY", // 事件采集的文件路径
}
// 初始化 logConsumer
consumer, _ := thinkingdata.NewLogConsumerWithConfig(config)
// 创建 te 对象
te := thinkingdata.New(consumer)
```

`LOG_DIRECTORY`为写入本地的文件夹地址。您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传

### 三、常用功能

为了保证访客 ID 与账号 ID 能够顺利进行绑定，如果您的游戏中会用到访客 ID 与账号 ID，我们极力建议您同时上传这两个 ID，否则将会出现账号无法匹配的情况，导致用户重复计算，具体的 ID 绑定规则可参考用户识别规则一章。

#### 3.1 发送事件

您可以调用`track`来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，以下是发送事件的示例代码:

```
accountId := "te_account_id"
distinctId := "te_distinct_id"//accountId和distinctId不能全部为空
properties := map[string]interface{}{
   //设置用户的ip地址，TE系统会根据IP地址解析用户的地理位置信息
   "#ip":       "123.123.123.123",
   "channel":   "te",       // 字符串
   "age":       1,          // 数字
   "is_success": true,       // 布尔
   "birthday":  time.Now(), // 时间
   // 对象
   "object": map[string]interface{}{
      "key": "value",
   }, 
   //对象组
   "objectArr": []interface{}{
      map[string]interface{}{
         "key": "value",
      },
   },
   "arr":     []string{"value"}, // 数组
}
// track事件
err := te.Track(accountId, distinctId, "payment", properties)
```

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

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

#### 3.2 设置用户属性

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

```
// 此时username为TA
err := te.UserSet("accountId", "distinctId", map[string]interface{}{
   "user_name": "TA",
})
// 此时username为TE
err = te.UserSet("accountId", "distinctId", map[string]interface{}{
   "user_name": "TE",
})
```

#### 3.3 数据上报

使用 TDLogConsumer 时，SDK 会实时的将采集到的数据写入磁盘。

`TDAnalytics` 对象的 `Flush()` 方法内部是将文件系统中默认的内存缓存实时同步到磁盘。一般不需要手动调用 `Flush()` 方法。

#### 3.4 关闭SDK

```
// 关闭并退出 SDK
te.Close()
```

<!-- unsupported block: 34 -->

关闭并退出 sdk，请在关闭服务器前调用本接口，以避免缓存内的数据丢失

### 四、最佳实践

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

```
// 创建 LogConfig 配置文件
config := thinkingdata.TDLogConsumerConfig {
    Directory: "./log_directory", // 事件采集的文件路径
}
// 初始化 logConsumer
consumer, _ := thinkingdata.NewLogConsumerWithConfig(config)
// 创建 te 对象
te := thinkingdata.New(consumer)

accountId := "te_account_id"
distinctId := "te_distinct_id"//accountId和distinctId不能全部为空
properties := map[string]interface{}{
    //设置用户的ip地址，TE系统会根据IP地址解析用户的地理位置信息
    "#ip":       "123.123.123.123",
    "channel":   "te",       // 字符串
    "age":       1,          // 数字
    "isSuccess": true,       // 布尔
    "birthday":  time.Now(), // 时间
    // 对象
    "object": map[string]interface{}{
       "key": "value",
    },
    //对象组
    "objectArr": []interface{}{
       map[string]interface{}{
          "key": "value",
       },
    },
    "arr":     []string{"value"}, // 数组
}
// 上传事件
err := te.Track(accountId, distinctId, "payment", properties)
if err != nil {
    fmt.Println(err)
}
//设置用户属性
err = te.UserSet("accountId", "distinctId", map[string]interface{}{
    "user_name": "TE",
})
if err != nil {
    fmt.Println(err)
}
```
