菜单

Android

ⓘ 提示
Android SDK 要求最低系统版本为 Android 4.4

⚠️ 迁移须知
目前 SDK 的全部功能已完成迁移（3.0.0+）

新包名：ai.datatower:core

? 如何迁移到新 SDK？
请查看《快速迁移指南》。

Maven Central

一、集成

  • 在项目根目录下 build.gradle 文件中添加 mavenCentral
kotlin 复制代码 
allprojects {
    repositories {
        ...
        mavenCentral()
    }
}
  • 在项目模块目录下 build.gradle 文件中添加 SDK 依赖
kotlin 复制代码 
dependencies {
    ...
    implementation 'ai.datatower:core:{最新版本}'
}

二、初始化

  • 说明

DataTower.ai Core SDK 唯一初始化入口

  • 方法
Kotlin 复制代码 
fun initSDK(
    context: Context,
    appId: String,
    serverUrl: String,
    channel: String = "",
    isDebug: Boolean = false,
    logLevel: Int = Log.VERBOSE,
    manualEnableUpload: Boolean = false
)
  • 参数
参数名 类型 是否必传 说明 示例
context Context 是 Context 上下文 getApplication()
appId String 是 项目唯一标识，创建项目后 DT 后台自动分配，请在【项目设置-项目详情】中获取 dt_test
serverUrl String 是 数据上报地址，创建项目后 DT 后台自动分配，请在【项目设置-项目详情】中获取 https://xxx.roiquery.com
channel String 否 渠道，打多渠道包时需要用到，可使用 SDK 内部提供的实现， 默认为“” DTChannel.GP
isDebug Boolean 否 是否打开调试，调试模式下将打印 log，默认为 false，log 标签为 DataTower true/false
logLevel Int 否 log 的级别，默认为 Log.VERBOSE，仅在 isDebug = true 有效 Log.VERBOSE、Log.DEBUG、Log.ERROR 等
manualEnableUpload Boolean 否 是否手动启动上报, 如设为 true, 则需要自行调用 enableUpload 开启上报 true/false
  • 使用
kotlin 复制代码 
// 在 Application onCreate() 调用

//  DT SDK 初始化
DT.initSDK(this, "app id", "serverUrl", DTChannel.GP, ture, Log.DEBUG, false)

三、基础功能

基础功能的API均在DTAnalytics类下

3.1 ID 体系

3.1.1 设置账号 ID

  • 说明

可以在用户每一次登录时，调用 setAccountId 设置用户的账号 ID， DT 系统将会以账号 ID 作为身份识别 ID，多次调用 setAccountId 将覆盖先前的账号 ID

若您的应用没有账号体系可以不设置

  • 方法
kotlin 复制代码 
fun setAccountId(id: String)
  • 参数
参数名 类型 是否必传 说明
id String 是 自有用户系统的 id
  • 使用
kotlin 复制代码 
DTAnalytics.setAccountId("123456");

如果需要清除账号 ID，请传入空字符串

kotlin 复制代码 
DataTower.setAccountId("");

3.1.2 获取 DT ID

  • 说明

获取由 SDK 生成的设备标识 DT ID。

  • 方法
kotlin 复制代码 
fun getDataTowerId(onDataTowerIDListener: OnDataTowerIdListener)
  • 参数
参数名 类型 是否必传 说明
onDataTowerIDListener OnDataTowerIdListener 是 用户接收 dt id 的回调
  • 使用
kotlin 复制代码 
DTAnalytics.getDataTowerId(object: OnDataTowerIdListener {
    override fun onDataTowerIdCompleted(dataTowerId: String) {
        // ...
    }
})

3.2 设置事件上报

  • 说明

调用 track 设置自动上报的埋点事件和事件属性

  • 方法
kotlin 复制代码 
fun track(
    eventName: String,
    properties: Map<String, Any>?
  )
  • 参数
参数名 类型 是否必传 说明
eventName String 是 事件名称
properties Map<String， Any> 或者 JSONObject 否 自定义事件属性
  • 使用
kotlin 复制代码 
HashMap<String, Object> properties = new HashMap<>();
properties.put("test_property_3", false);
properties.put("test_property_4", 2.3);

DTAnalytics.track("test_track", properties);
// or 不传属性
DTAnalytics.track("test_track");

3.3 设置用户属性

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

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

3.3.1 user_set

  • 说明

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

  • 方法
kotlin 复制代码 
fun userSet(properties: JSONObject?)
  • 参数
参数名 类型 是否必传 说明
properties JSONObject 是 事件属性
  • 使用
kotlin 复制代码 
JSONObject pro = new JSONObject();
pro.put("user_sex_man", false);
pro.put("user_pwd", "1111111");
pro.put("user_age", 23);

DTAnalytics.userSet(pro);

3.3.2 user_set_once

  • 说明

如果您要上传的用户属性只要设置一次，则可以调用 userSetOnce 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息

  • 方法
kotlin 复制代码 
fun userSetOnce(properties: JSONObject?)
  • 参数
参数名 类型 是否必传 说明
properties JSONObject 是 事件属性
  • 使用
kotlin 复制代码 
JSONObject pro = new JSONObject();
pro.put("user_first_paid_time", "2020-09-23");

DTAnalytics.userSetOnce(pro);

3.3.3 user_add

  • 说明

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

  • 方法
kotlin 复制代码 
fun userAdd(properties: JSONObject?)
  • 参数
参数名 类型 是否必传 说明
properties JSONObject 是 事件属性 设置的属性 key 为字符串，Value 只允许为数值，否则操作不生效
  • 使用
kotlin 复制代码 
JSONObject properties = new JSONObject();
properties.put("TotalRevenue",30);
DTAnalytics.userAdd(properties);
// 此时"TotalRevenue"为30

JSONObject newProperties = new JSONObject();
newProperties.put("TotalRevenue",648);
DTAnalytics.userAdd(newProperties);
// 此时"TotalRevenue"为678

3.3.4 user_unset

  • 说明

当您要清空用户的用户属性值时，您可以调用 userUnset 来对指定属性进行清空操作，如果该属性还未创建，则 userUnset 不会创建该属性

  • 方法
kotlin 复制代码 
fun userUnset( vararg properties: String?)
  • 参数
参数名 类型 是否必传 说明
properties vararg String 是 用户属性名称集
  • 使用
kotlin 复制代码 
// 重置单个用户属性
DTAnalytics.userUnset("key1");

// 重置多个用户属性
DTAnalytics.userUnset("key1", "key2", "key3");

// 重置多个用户属性，传入字符串数组
String[] keys = {"key1", "key2"};
DTAnalytics.userUnset(keys);

3.3.5 user_delete

  • 说明 如果您要删除某个用户，可以调用 user_delete 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
  • 方法
kotlin 复制代码 
fun userDelete()

3.3.6 user_append

  • 说明

您可以调用 userAppend 对列表类型的用户数据追加元素

  • 方法
kotlin 复制代码 
fun userAppend(properties: JSONObject?)
  • 参数
参数名 类型 是否必传 说明
properties vararg String 是 用户属性名称集，value 仅支持 JSONArray
  • 使用
kotlin 复制代码 
DTAnalytics.userAppend({ user_list: ["apple", "ball"] });

3.3.7 user_uniq_append

  • 说明

您可以调用 userUniqAppend 对列表的用户数据追加唯一元素。调用 userUniqAppend 接口会对追加的用户属性进行去重， userAppend 接口不做去重，用户属性可存在重复

  • 方法
kotlin 复制代码 
fun userUniqAppend()
  • 参数
参数名 类型 是否必传 说明
properties vararg String 是 用户属性名称集，value 仅支持 JSONArray
  • 使用
kotlin 复制代码 
// 此时user_list的属性值为["apple"，"ball"]
DTAnalytics.userAppend({ user_list: ["apple", "ball"] });
// 此时user_list的属性值为["apple","apple","ball","cube"]
DTAnalytics.userAppend({ user_list: ["apple", "cube"] });
// 此时user_list的属性值为["apple"，"ball","cube"]
DTAnalytics.userUniqAppend({ user_list: ["apple", "cube"] });

四、进阶功能

4.1 收入数据上报

4.1.1 广告变现

  • 说明
  1. 如果你的产品具备广告变现（IAA）功能，DT SDK 已经预置了常用的广告事件接口。在产品的广告变现相关场景中，你可以调用相应的接口。一旦调用了这些接口成功，您可以在我们的后台实时查看广告变现全链路的表现数据
  2. 并不是所有事件都要求上报，但是上报的越详细，越有助于分析整个广告变现链路。如果预置事件中没有满足你的需求，你仍可以自定义事件。DT 中针对一个广告变现流程（加载、展示、行为、转化、关闭等），使用了唯一的 seq 用来关联和区分。如果你想关联同一个广告变现流程中预置事件和自定义事件，请使用 seq 进行关联。seq 的生成，可以使用 UUID 来实现
  3. 如果需要查看设备层级广告收入预估，请务必调用以下接口上报相关事件：
  4. 广告相关的API均在DTAdReport类中
事件名称 显示名 事件描述
#ad_load_begin 广告加载开始 广告加载开始
#ad_load_end 广告加载结束 广告加载结束
#ad_to_show 广告预展示 将要展示广告
#ad_show 广告展示 参与广告收益计算的重要事件；在广告展示时上报
#ad_show_failed 广告展示失败 广告展示失败
#ad_close 广告关闭 广告已经关闭
#ad_click 广告点击 参与广告收益计算的重要事件；在广告点击时上报
#ad_rewarded 广告获得奖励 只针对激励广告获得奖励
#ad_conversion 广告收益 参与广告收益计算的重要事件；在用户获得广告奖励后上报
#ad_paid 广告展示价值 广告平台给每个广告的预估价值
  • 接口列表
kotlin 复制代码 
// 上报广告开始加载事件
fun reportLoadBegin(
    id: String,
    type: AdType,
    platform: AdPlatform,
    seq: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)

// 上报广告结束加载事件
fun reportLoadEnd(
    id: String,
    type: AdType,
    platform: AdPlatform,
    duration: Long,
    result: Boolean,
    seq: String,
    errorCode: Int = 0,
    errorMessage: String = "",
    properties: MutableMap<String, Any>? = mutableMapOf(),
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)

// 上报广告预展示事件，在想展示广告之前调用
fun reportToShow(
    id: String,
    type: AdType,
    platform: AdPlatform,
    location: String,
    seq: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
    entrance: String? = "",
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)

// 上报广告展示事件，在展示广告时调用
fun reportShow(
    id: String,
    type: AdType,
    platform: AdPlatform,
    location: String,
    seq: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
    entrance: String? = "",
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)

// 上报广告展示失败事件,在展示广告失败时调用
fun reportShowFailed(
    id: String,
    type: AdType,
    platform: AdPlatform,
    location: String,
    seq: String,
    errorCode: Int,
    errorMessage: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
    entrance: String? = "",
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)

// 上报广告关闭事件，在广告被关闭时调用
fun reportClose(
    id: String,
    type: AdType,
    platform: AdPlatform,
    location: String,
    seq: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
    entrance: String? = "",
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)

// 上报广告点击事件，在广告被点击时调用
fun reportClick(
    id: String,
    type: AdType,
    platform: AdPlatform,
    location: String,
    seq: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
    entrance: String? = "",
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)

// 上报广告获得奖励事件，在激励广告获取奖励后调用
fun reportRewarded(
    id: String,
    type: AdType,
    platform: AdPlatform,
    location: String,
    seq: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
    entrance: String? = "",
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)

// 上报广告收益转化事件，在点击广告时调用（#ad_conversion_source = by_click）
fun reportConversionByClick(
    id: String,
    type: AdType,
    platform: AdPlatform,
    location: String,
    seq: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
    entrance: String? = "",
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)

// 上报广告收益转化事件，在获得广告激励时调用（#ad_conversion_source = by_rewarded）
fun reportConversionByRewarded(
    id: String,
    type: AdType,
    platform: AdPlatform,
    location: String,
    seq: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
    entrance: String? = "",
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)

// 上报广告收益转化事件，在点击广告后跳出App时调用（#ad_conversion_source = by_left_app）
fun reportConversionByLeftApp(
    id: String,
    type: AdType,
    platform: AdPlatform,
    location: String,
    seq: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
    entrance: String? = "",
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)

// 上报广告展示价值事件，在广告SDK回调时调用
fun reportPaid(
    id: String,
    type: AdType,
    platform: AdPlatform,
    location: String,
    seq: String,
    value: Double,
    currency: String,
    precision: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
    entrance: String? = "",
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)

fun reportPaid(
    id: String,
    type: AdType,
    platform: AdPlatform,
    location: String,
    seq: String,
    mediation: AdMediation,
    mediationId: String,
    value: Double,
    precision: String,
    country: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
)

// 上报离开app事件，在点击广告链接，离开当前app(页面)时调用
fun reportLeftApp(
    id: String,
    type: AdType,
    platform: AdPlatform,
    location: String,
    seq: String,
    properties: MutableMap<String, Any>? = mutableMapOf(),
    entrance: String? = "",
    mediation: AdMediation = AdMediation.IDLE,
    mediationId: String = "",
)
  • 参数
参数名 类型 是否必传 说明
seq String 是 广告系列事件的标识，需要调用 DTAdReport.generateUUID（）生成
id String 是 Network 广告单元 ID
type AdType 是 详见 类型 Type
platform AdPlatform 是 详见 广告平台 Platform
entrance String 否 广告展示入口
result Boolean 是 广告加载结果，true 为广告加载成功
duration Long 是 广告加载时长
location String 是 广告位置，通常为在广告平台配置的位置值
errorCode Int 否 失败码，值为应用接入的对应的广告平台给出的错误码
errorMessage String 否 失败信息，应用接入的对应的广告平台给出的错误信息
value Double 是 广告价值，应用接入的对应的广告平台给出的广告价值信息
currency String 是 广告价值对应的货币单位，请传入 USD
precision String 是 精确度，广告价值所对应的精确度
country String 是 广告展示所在的国家/地区信息
mediation AdMediation 否 详见 聚合广告平台 Mediation
mediationId String 否 聚合平台广告单元 ID
properties Map<String, Any> 否 应用自定义的额外属性
  • 使用事例

场景一：独立广告平台

kotlin 复制代码 
/*
* 一次展示Admob插页广告的过程
*/

// 广告位，比如这页面是主页
val location = "main"

// Admob广告单元
val adUnit = "xxxxxxxx"

// 整个过程的行为系列标识
var seq = DTAdReport.generateUUID()

// 1.上报开始加载广告
DTAdReport.reportLoadBegin(adUnit, AdType.INTERSTITIAL, AdPlatform.ADMOB, seq)

// 加载开始时间
var loadStartTime = System.currentTimeMillis()

// 2.Admob开始加载广告
InterstitialAd.load(this,adUnit, adRequest,object : InterstitialAdLoadCallback() {

    override fun onAdLoaded(interstitialAd: InterstitialAd) {
        // 3.上报加载广告成功
        val loadDuration = System.currentTimeMillis() - loadStartTime
        DTAdReport.reportLoadEnd(adUnit, AdType.INTERSTITIAL, AdPlatform.ADMOB, loadDuration, ture, seq)
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
        // 3.上报加载广告失败
        val loadDuration = System.currentTimeMillis() - loadStartTime
        DTAdReport.reportLoadEnd(adUnit, AdType.INTERSTITIAL, AdPlatform.ADMOB, loadDuration, false, seq, adError.code, adError.msg)
    }
});

InterstitialAd?.fullScreenContentCallback = object: FullScreenContentCallback() {
    override fun onAdClicked() {
        // 7.广告被点击
        DTAdReport.reportClick(adUnit, AdType.INTERSTITIAL, AdPlatform.ADMOB, location, seq)
        DTAdReport.reportConversionByClick(adUnit, AdType.INTERSTITIAL, AdPlatform.ADMOB, location, seq)
    }

    override fun onAdDismissedFullScreenContent() {
        // 8.广告关闭
        DTAdReport.reportClose(adUnit, AdType.INTERSTITIAL, AdPlatform.ADMOB, location, seq)
    }

    override fun onAdFailedToShowFullScreenContent(adError: AdError?) {
        // 6.广告展示失败
        DTAdReport.reportShowFailed(adUnit, AdType.INTERSTITIAL, AdPlatform.ADMOB, location, seq, adError.code, adError.msg)
    }

    override fun onAdShowedFullScreenContent() {
        // 5.广告展示成功
        DTAdReport.reportShow(adUnit, AdType.INTERSTITIAL, AdPlatform.ADMOB, location, seq)
    }
}

// 4.展示广告
DTAdReport.reportToShow(adUnit, AdType.INTERSTITIAL, AdPlatform.ADMOB, location, seq)
InterstitialAd?.show(this)

对于激励广告，会有获得激励回调

kotlin 复制代码 
override fun onAdRewared(){
    DTAdReport.reportConversionByRewared(adUnit, AdType.REWARDED, AdPlatform.ADMOB, location, seq)
}

场景二：聚合广告平台（Mediation）

由于聚合广告平台展示广告的时候，通常没有返回具体是哪个广告平台（Network）的广告和对应信息，所以需要在回调中判断，如 onAdShowed 回调

kotlin 复制代码 
// 聚合广告平台一般会返回广告相关的信息 AdInfo
override fun onAdShowed(ad: AdInfo){
    // 需自行实现 getAdPlatform() 、getAdUnit()方法
    val adPlatform = getAdPlatform(ad)
    val adUnit = getAdUnit(ad)
    // 4. 广告展示成功
    DTAdReport.reportShow(adUnit, AdType.INTERSTITIAL, adPlatform, location, seq)
}

其他 API 类似

4.1.2 内购变现（beta）

  • 说明

如果你的产品具备内购变现（IAP）功能，DT SDK 已经预置了内购收入事件（#iap_purchase_success）接口

内购相关的API均在DTIPAReport类中

在产品的内购变现相关场景中，你可以调用相应的接口。一旦调用了这些接口成功，您可以在我们的后台实时查看内购变现全链路的表现数据

  • 方法
kotlin 复制代码 
// 上报购买成功事件，购买成功的时候上报
fun reportPurchaseSuccess(
    order: String,
    sku: String,
    price: Double,
    currency: String,
    properties: MutableMap<String, Any>? = mutableMapOf()
)
  • 参数
参数名 类型 是否必传 说明
order String 是 购买订单
sku String 是 购买商品 id
price Double 是 购买所需的价格
currency String 是 购买所用的货币单位，与 price 共同决定购买所需的价格
properties Map<String, Any> 否 应用自定义的额外属性

4.1.3 订阅变现（beta）

  • 说明

如果你的产品具备订阅变现（IAS）功能，DT SDK 已经预置了订阅收入事件（#ias_subscribe_success）接口
内购相关的API均在DTIASReport类中

在产品的订阅变现相关场景中，你可以调用相应的接口。一旦调用了这些接口成功，您可以在我们的后台实时查看订阅变现全链路的表现数据
需要注意的是，订阅会存在退订的情况，那么在用户退订的时候，同样也需要调用该接口，在price属性中，传入“-退订金额”（例如：-28），在计算最终收入的场景中，收入数据才会与实际一致。

  • 方法
kotlin 复制代码 
// 订阅成功事件上报，订阅成功时上报
fun reportSubscribeSuccess(
    originalOrderId: String,
    orderId: String,
    sku: String,
    price: Double,
    currency: String,
    properties: MutableMap<String, Any>? = mutableMapOf()
)
  • 参数
参数名 类型 是否必传 说明
originalOrderId String 是 订阅原始订单 id
orderId String 是 订阅订单
sku String 是 订阅商品 id
price Double 是 订阅所需的价格
currency String 是 订阅所用的货币单位，与 price 共同决定订阅所需的价格
properties Map<String, Any> 否 应用自定义的额外属性

4.2 集成三方数据

4.2.1 透传 dt_id

如果您需将三方数据同步至 DT 平台，请在三方 SDK 初始化之前调用获取 dt_id 的方法，然后按照 DT 集成各平台的操作文档传入三方平台的对应参数

kotlin 复制代码 
DTAnalytics.getDataTowerId(object: OnDataTowerIdListener {
    override fun onDataTowerIdCompleted(dataTowerId: String) {
        // ...
    }
})

4.2.2 关联三方 ID

  • 说明

如果您需将 DT 数据从服务端发送至三方平台，请初始化三方 SDK 之后获取三方设备 ID，然后使用 DT SDK 进行数据上报

  • 方法
kotlin 复制代码 
// 需先获取对应 id
// Firebase
DTAnalytics.setFirebaseAppInstanceId("");
// AppsFlyer
DTAnalytics.setAppsFlyerId("");
// Adjust
DTAnalytics.setAdjustId("");
// Kochava
DTAnalytics.setKochavaId("");
// Tenjin
DTAnalytics.setTenjinId("");
  • 调用接口会上报的属性
调用接口 对应三方平台 公共事件属性 用户属性
setFirebaseAppInstanceId() Firebase #firebase_iid #latest_firebase_iid
setAppsFlyerId() AppsFlyer #appsflyer_id #latest_appsflyer_id
setAdjustId() Adjust #adjust_id #latest_adjust_id
setKochavaId() Kochava #kochava_id #latest_kochava_id
setTenjinId() Tenjin #tenjin_id #latest_tenjin_id

4.3 事件时长计时

  • 说明

如果您需要记录某个事件的持续时长，可以调用 trackTimerStart 来开始计时

  1. 在事件开始时，调用 trackTimerStart 并不会真正发送事件
  2. 在事件结束时调用 trackTimerEnd，SDK 会上报 "event" 事件，并自动在 "event" 事件属性中加入 #event_duration 这一属性来表示记录的事件持续时长
  3. 多次调用 trackTimerStart 时，事件 "event" 的开始时间以最后一次调用时为准
  4. 多次调用 trackTimerPause \ trackTimerResume \ trackTimerEnd 时，事件 "event" 的暂停时间\恢复时间\结束时间以最先一次调用时为准
  • 方法
kotlin 复制代码 
// 开始事件计时
DTAnalyticsUtils.trackTimerStart("event");

// 如果需要暂停事件计时
DTAnalyticsUtils.trackTimerPause("event");

// 如果需要恢事件计时
DTAnalyticsUtils.trackTimerResume("event");

// 结束事件计时, properties 为自定义属性，Map<String, Any> 或者 JSONObject，可不传
DTAnalyticsUtils.trackTimerEnd("event", properties);

4.4 公共属性

如需为所有事件添加属性，可以使用公共属性接口进行设置。

4.4.1 静态公共属性

静态公共属性会使用持久化存储，应用退出再开启时，原先设置的值会保持不变。

kotlin 复制代码 
val props = JsonObject()
// or Map
// val props = mutableMapOf()

// 设置
DTAnalytics.setStaticCommonProperties(props)

// 清除
DTAnalytics.clearStaticCommonProperties()

4.4.2 动态公共属性

动态公共属性会在调用相关事件上报接口时动态地进行公共属性的获取，应用重启后需重新设置。

kotlin 复制代码 
val props = JsonObject()

// 设置
DTAnalytics.setDynamicCommonProperties {
  props
}

// Track 时会调用动态公共属性的函数来获取公共属性，并进行上报
DTAnalytics.track("simple_event")

// 清除
DTAnalytics.clearDynamicCommonProperties()

4.5 自动采集与关闭

SDK默认情况下会有一些自动采集的行为，包括预置事件和用户事件

4.5.1 预置事件的自动采集

自动采集事件 时机
#app_install（app安装） App 首次启动，调用 DT.initSDK() 时
#session_start（app打开 App 启动，调用 DT.initSDK() 时、App 从后台切换到前台时（对应 resume）
#session_end（app关闭） App 从前台切换到后台时（对应 pause）

4.5.2 关闭预置事件的自动采集

在某些场景下，您可能不希望有某个预置事件的上报，SDK 提供了接口来实现对预置事件的采集与上报的控制。

kotlin 复制代码 
// 禁用预置事件
DT.disableAutoTrack(PresetEvent)

// 取消禁用
DT.enableAutoTrack(PresetEvent)

需传入枚举类型 PresetEvent，支持的预置事件。默认为不禁用：

  • #app_install,
  • #session_start,
  • #session_end

4.5.3 用户事件的自动采集

用户事件类型 自动上报说明
user_set 在每次初始化时，自动上报，用于更新用户最新的属性（#latest_xxx），当最新值未发生变化时，不会上报
user_set_once 用于记录用户激活时的属性（#active_xxx），仅上报一次，相关属性上报过一次就不再上报

4.5.4 关闭预置属性的采集与上报

当您在使用过程中，不希望上报DT的预置属性时，可通过配置文件的方式实现

配置方式

  1. 在 res/values 下添加一个 xml 文件（任意名字），
  2. 其中定义 string-array，且 name 为 DTDisPresetProperties
  3. 字符串数组内填写需要禁用的预置属性

特殊说明
以下预置属性不可关闭：

属性 说明说明
#bundle_id 应用包名，属于DT内置字段
#app_id DT的app_id，上报数据的必备字段
#debug 判断该条数据是否是debug
#dt_id 上报数据的必备字段，用于用户识别
#acid 用于用户识别
#session_id 会话事件唯一id，标识回话
#sdk_type 判断SDK类型
#sdk_version_name 判断SDK版本

示例

xml 复制代码 
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array name="DTDisPresetProperties">
        <item>#os_lang_code</item>
        <item>#os_version_name</item>
    </string-array>
</resources>
上一个
客户端
下一个
iOS
最近修改: 2025-02-26