菜单

Go

更新时间：2024-12-10
⚠️ 此 SDK 需搭配 FileScout 使用

一、集成 SDK

命令行

获取 SDK

bash 复制代码

go get github.com/datatower-ai/dt-golang-sdk

更新 SDK

bash 复制代码

go get -u github.com/datatower-ai/dt-golang-sdk

Module

在代码开头引入 SDK

go 复制代码

import "github.com/datatower-ai/dt-golang-sdk"

用命令行拉取 SDK

bash 复制代码

go mod tidy

二、初始化

SDK 初始化示例代码

go 复制代码

import "github.com/datatower-ai/dt-golang-sdk"

path := "log/"			// log 文件的文件夹路径
maxBatchLen := 1000		// 最大单次写入条数
logPrefix := "my_project"	// log 文件的前缀
maxLogSize := 0			// 理论单个文件的最大大小（单位：Byte）
debug := false                  // 是否为 debug 

consumer := dtAnalytics.NewDTLogConsumer(path, maxBatchLen, logPrefix, maxLogSize)
dt, _ := dtAnalytics.New(consumer, debug)

dtAnalytics.ToggleLogger(true) 	// 如需开启 Logger

三、基础功能

事件上报和用户属性的所有接口会对事件名/属性名/类型进行校验

如果校验通过会返回 nil，并进行记录上报

未通过则会返回 error，不进行记录上报

3.1 设置事件上报

数据说明文档：当您将要上报的事件/属性在数据说明文档中已存在时，强烈建议您使用文档中的对应属性名，比如您要上报 APP 的操作系统属性，请使用文档里预置的属性名”#os”，不要自定义取名，避免跟客户端上报的预置属性不一致
用户识别规则：为了让访客 ID（dt_id）与帐号 ID（acid）能够顺利绑定，其中访客 ID（dt_id）为必填
T
该接口是使用最频繁的接口，通过调用 Track 来上报自定义事件，在上报事件之前，建议您根据梳理的文档来设置事件属性，以下是示例代码：

go 复制代码

dtId := "dt_id"
acid := ""
eventName := "sample_event"
properties := map[string]interface{}{
	"productName": "Book A"
}

err := dt.Track(dtId, acid, eventName, properties)

if err != nil {
	// 处理失败 ...
}

注意：

以#开头命名的事件/属性，必须按照预置事件/属性规则进行上报，否则将无法上报
以$开头的事件/属性都被视为非法字段，将无法上报

3.2 设置用户属性

DT 系统支持的用户属性设置类型总览说明如下

操作	对应事件名	处理规则
覆盖用户属性	`#user_set`	对用户表进行操作，覆盖用户的原有属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与覆盖操作传入属性的类型一致
初始化用户属性	`#user_set_once`	对用户表进行操作，初始化用户属性，如果该属性已有值存在，系统忽略本次操作
累加用户属性	`#user_add`	对用户表进行操作，对数值型的用户属性做累加计算，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值等同于相减操作
清空用户属性值	`#user_unset`	对用户表进行操作，清空用户属性的属性值，即设置成 NULL，如果被清空的属性不存在也不会新建该属性
追加列表型用户属性的元素	`#user_append`	对用户表进行操作，对列表类型的用户属性追加元素，如果被追加的列表属性不存在，系统将自动生成并进行追加
追加并去重列表类型用户属性的元素	`#user_uniq_append`	对用户表进行操作，对列表类型的用户属性值追加元素，并会进行一次全列表去重（去重保证前后原有的元素顺序不变），如果被追加的列表属性不存在，系统将自动生成并进行追加再去重
删除用户	`#user_delete`	对用户表进行操作，删除对应用户，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

3.2.1 userSet

UserSet 是常用的功能，您可以调用它来进行用户属性的设置，调用该操作时，会覆盖原有的属性值，如果用户不存在该属性，则会创建新用户属性，类型与传入属性的类型一致

go 复制代码

properties := map[string]interface{}{ "name": "abc" }
// 设置用户属性，"name" 的值为 "abc"
dt.UserSet(acid, dtId, properties)

properties2 := map[string]interface{}{ "name": "xyz" }
// 再次设置用户属性，此时 "name" 的值会被覆盖为 "xyz"
dt.UserSet(acid, dtId, properties2)

3.2.2 userSetOnce

如果您希望用户属性只设置一次，则可以调用 UserSetOnce 进行设置，当该属性没有值时，则会创建该属性并赋值，但该属性已经有值时，将不会设置成功

go 复制代码

properties := map[string]interface{}{ "name": "abc" }
// 一次性设置用户属性，"name" 的值为 "abc"
dt.UserSetOnce(acid, dtId, properties)

properties2 := map[string]interface{}{ "name": "xyz" }
// 再次一次性设置用户属性，此时 "name" 的值不会被覆盖为 "xyz"
dt.UserSetOnce(acid, dtId, properties2)

3.2.3 userAdd

当您要对数值类型的属性进行累加操作时，可以调用 UserAdd 来实现，如果该属性还没有被设置，则会赋值为 0 再进行计算，可传入负值等同于相减操作

go 复制代码

properties := map[string]interface{}{
    "total_count": 10,
    "level": 3
}
// 对用户属性进行累加，数据上传完成后，由于该属性还没有被设置，此时 "total_count" 的值为 10,"level" 的值为 3
dt.UserAdd(acid, dtId, properties)

properties2 := map[string]interface{}{ "total_count": 20 }
// 对用户属性进行累加，数据上传完成后，此时 "total_count" 的值为 30, "level" 的值为 3
dt.UserAdd(acid, dtId, properties2)

3.2.4 userUnset

当您要清空用户属性时，可以调用 UserUnset 来实现，如果属性存在，则会删除属性，如果属性不存在，则不会做任何操作

go 复制代码

delSet := map[string]interface{}{
    "name": 0,
    "actime_time": 0
}
dt.UserUnset(acid, dtId, delSet)

3.2.5 userAppend

当您要追加列表类型用户属性元素时，可以调用 UserAppend 来实现，如果被追加的列表属性不存在，系统将自动生成并进行追加

go 复制代码

properties := map[string]interface{}{
    "pet": []string{"cat", "dog"}
}
// 设置用户属性，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog"]
dt.UserSet(acid, dtId, properties)

properties2 := map[string]interface{}{
    "pet": []string{"ratbbit"}
}
// 对用户列表类型属性追加元素，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog", "rabbit"]
dt.UserAppend(acid, dtId, properties2)

3.2.6 userUniqAppend

当您要追加列表类型用户属性元素并去重时，可以调用 UserUniqAppend 来实现，如果被追加的列表属性不存在，系统将自动生成并进行追加和去重

go 复制代码

properties := map[string]interface{}{
    "pet": []string{"cat", "dog"}
}
// 设置用户属性，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog"]
dt.UserSet(acid, dtId, properties)

properties2 := map[string]interface{}{
    "pet": []string{"ratbbit", "dot"}
}
// 对用户列表类型属性追加元素并去重，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog", "rabbit]
dt.UserUniqAppend(acid, dtId, properties2)

3.2.7 userDelete

如果您要删除某个用户，可以调用 UserDelete 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

go 复制代码

dt.UserDelete(acid, dtId, make(map[string]interface{}))

四、进阶功能

4.1 设置用户ip地址

在服务端上报数据时，如果您想设置用户的ip地址,可以通过在properties中添加#ip属性，DT会根据您上报的IP地址解析用户的地理位置信息

注：如果是用户事件，仅userSetOnce可上报#ip属性

go 复制代码

properties := map[string]interface{}{
	"#ip": "127.0.0.1"
}

五、数据传输

可能使用的数据传输方式：

DTLogConsumer：写入文件 + 通过 FileScout 传输

如果生产的数据都是调试数据，建议您开启 debug 标志，当 debug 标志开启时，数据将不会进入生产环境

5.1 DTLogConsumer

参数（按顺序）：

log 文件的文件夹路径
最大单次写入条数
log 文件的前缀
单个文件的最大大小（单位：Byte）

go 复制代码

path := "log/"			// log 文件的文件夹路径
maxBatchLen := 1000		// 最大单次写入条数
logPrefix := "my_project"	// log 文件的前缀
maxLogSize := 0			// 理论单个文件的最大大小（单位：Byte）

consumer := dtAnalytics.NewDTLogConsumer(path, maxBatchLen, logPrefix, maxLogSize)

// 初始化，debug：true
dt, _ := dtAnalytics.New(consumer, true)

// 初始化，debug：false
// dt, _ := dtAnalytics.New(consumer, false)

5.2 提交数据

如果您期望数据立即上报到 DT 服务器，可以通过 flsuh 完成

go 复制代码

dt.Flush()

5.3 关闭 SDK

请在退出程序前调用本接口，以避免缓存的数据丢失（重要！)

go 复制代码

dt.Close()

六、完整示例

从 SDK 初始化、上报到关闭，整个上报流程示例

go 复制代码

package main

import (
	"fmt"
	dtAnalytics "github.com/datatower-ai/dt-golang-sdk"
)

func main() {
	dtAnalytics.ToggleLogger(true)
	consumer := dtAnalytics.NewDTLogConsumer("log", 1000, "dt_go_demo", 0)
	dt, _ := dtAnalytics.New(consumer, true)
	dtAnalytics.ToggleLogger(false)

	properties := map[string]interface{}{
		"productNames": []string{"Lua", "hello"},
		"productType":  "Lua book",
		"producePrice": 80,
		"shop":         "xx-shop",
		"#os":          "1.1.1.1",
		"sex":          "female",
		"#app_id":      "appid_1234567890",
		"#bundle_id":   "com.example",
	}

    err := dt.Track("the_dt_id", "acid123456789", "simple_event", properties)
    if err != nil {
        println(err)
    }

    dt.Flush()
    dt.Close()
}

上一个

Node.js

下一个

Restful API 使用指南

最近修改: 2024-12-10

大纲