菜单

Java

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

一、集成 SDK

Gradle

项目 build.gradle 中加入源：

Java 复制代码

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

模块 build.gradle 中加入依赖：

Java 复制代码

dependencies {
    implementation 'com.github.datatower-ai:dt-java-sdk:{最新版本}'
}

Maven

加入源：

Java 复制代码

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

加入依赖：

Java 复制代码

<dependency>
    <groupId>com.github.datatower-ai</groupId>
    <artifactId>dt-java-sdk</artifactId>
    <version>{最新版本}</version>
</dependency>

sbt

在 build.sbt 尾部添加：

复制代码

resolvers += "jitpack" at "https://jitpack.io"

添加依赖：

复制代码

libraryDependencies += "com.github.datatower-ai" % "dt-java-sdk" % "{最新版本}"

leiningen

在 project.clj 尾部添加：

复制代码

:repositories [["jitpack" "https://jitpack.io"]]

添加依赖：

复制代码

:dependencies [[com.github.datatower-ai/dt-java-sdk "Tag"]]

二、初始化

SDK 初始化示例代码

Kotlin 复制代码

import ai.datatower.sdk.*

// Outputs to "log" folder in execution path with file prefix "dt_java" 
// for every 200 events, the ideal maximum size for each log file is 10MB 
// (will be larger if size of a single event is over such limit).
val consumer = DTLogConsumer("log", 200, "dt_java", (10 * 1024 * 1024).toLong())
// with debug: False
val dt: DTAnalytics = DTAnalytics.init(consumer, false)

三、基础功能

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

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

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

3.1 设置事件上报

数据说明文档：当您将要上报的事件/属性在数据说明文档中已存在时，强烈建议您使用文档中的对应属性名，比如您要上报 APP 的操作系统属性，请使用文档里预置的属性名”#os”，不要自定义取名，避免跟客户端上报的预置属性不一致
用户识别规则：为了让访客 ID（dt_id）与帐号 ID（acid）能够顺利绑定，其中访客 ID（dt_id）为必填

该接口是使用最频繁的接口，通过调用 track 来上报自定义事件，在上报事件之前，建议您根据梳理的文档来设置事件属性，以下是示例代码：

Kotlin 复制代码

val acId = "account_id_111"
val dt_id = "dt_id_222"

val properties = mapOf(
    "#app_id" to "appid_1234567890",
    "#bundle_id" to "com.example.app",
    "#os" to "android",
    "user_level" to 20,
    "coin" to 1000,
    "from" to "entry"
)

dt.track(acId, dt_id, "eventName", properties)

注意：

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

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

Kotlin 复制代码

var properties = mapOf("name" to "abc")
# 设置用户属性，"name" 的值为 "abc"
dt.userSet(acid, dt_id, properties)

properties = { "name": "xyz" }
# 再次设置用户属性，此时 "name" 的值会被覆盖为 "xyz"
dt.userSet(acid, dt_id, properties)

3.2.2 userSetOnce

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

Kotlin 复制代码

var properties = mapOf("name" to "abc")
# 一次性设置用户属性，"name" 的值为 "abc"
dt.userSetOnce(acid, dt_id, properties)

properties = mapOf("name" to "xyz")
# 再次一次性设置用户属性，此时 "name" 的值不会被覆盖为 "xyz"
dt.userSetOnce(acid, dt_id, properties)

3.2.3 userAdd

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

Kotlin 复制代码

val properties = mapOf(
    "total_count" to 10,
    "level" to 3
)
# 对用户属性进行累加，数据上传完成后，由于该属性还没有被设置，此时 "total_count" 的值为 10,"level" 的值为 3
dt.userAdd(acid, dt_id, properties)

val properties2 = mapOf("total_count": 20)
# 对用户属性进行累加，数据上传完成后，此时 "total_count" 的值为 30, "level" 的值为 3
dt.userAdd(acid, dt_id, properties2)

3.2.4 userUnset

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

Kotlin 复制代码

val delSet = mapOf("name" to 0, "actime_time" to 0)
# 设置后，会删除 name 和 actime_time 两个用户属性
dt.userUnset(acid, dt_id, delSet)

3.2.5 userAppend

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

kotlin 复制代码

var properties = mapOf(
    "pet" to listOf("cat", "dog")
)
# 设置用户属性，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog"]
dt.userSet(acid, dt_id, properties)

properties = mapOf(
    "pet" to listOf("ratbbit")
)
# 对用户列表类型属性追加元素，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog", "rabbit"]
dt.userAppend(acid, dt_id, properties)

3.2.6 userUniqAppend

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

Kotlin 复制代码

var properties = mapOf(
    "pet" to listOf("cat", "dog")
)
# 设置用户属性，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog"]
dt.userSet(acid, dt_id, properties)

properties = mapOf(
    "pet" to listOf("ratbbit", "dot")
)
# 对用户列表类型属性追加元素并去重，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog", "rabbit]
dt.userUniqAppend(acid, dt_id, properties)

3.2.7 userDelete

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

koltin 复制代码

dt.userDelete(acid, dt_id, mapOf())

四、进阶功能

4.1 设置用户ip地址

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

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

Kotlin 复制代码

properties["#ip"] = "127.0.0.1"

五、数据传输

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

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

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

5.1 DTLogConsumer

参数（按顺序）：

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

Kotlin 复制代码

val consumer = DTLogConsumer("./log", 200, "dt", 1000)
# 开启 debug 标志
val dt = DTAnalytics(consumer, true)
# 关闭 debug 标志
#val dt = DTAnalytics(consumer, false)

5.2 提交数据

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

Kotlin 复制代码

# 立即上报数据
dt.flush()

5.3 关闭 SDK

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

Kotlin 复制代码

dt.close()

六、完整示例

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

Koltin 复制代码

package org.example

import ai.datatower.sdk.*

fun main() {
    DTAnalytics.preload()
    DTAnalytics.toggleLogger(true)
    val consumer = DTLogConsumer("log", 1000, "dt_java", (10 * 1024 * 1024).toLong())
    val dt: DTAnalytics = DTAnalytics.init(consumer, true)
    DTAnalytics.toggleLogger(false)

    val properties: java.util.HashMap<String, Any> = java.util.HashMap<String, Any>()
    properties["productNames"] = listOf("Java", "hello")
    properties["productType"] = "Java book"
    properties["producePrice"] = 80
    properties["shop"] = "xx-shop"
    properties["#os"] = "1.1.1.1"
    properties["sex"] = "female"
    properties["#app_id"] = "appid_1234567890"
    properties["#bundle_id"] = "com.example"

    dt.track("xxx", null, "eventName", properties)

    dt.flush()
    dt.close()
}

上一个

Lua

下一个

Node.js

最近修改: 2024-12-10

大纲