跳到主要内容
版本:v3

数据规范

设备

设备 ID (device_id)

SDK 在初始化时,将为该终端生成唯一的 ID,我们称之为设备 ID。

生成规则

SDK 类型生成规则
Android依次尝试获取本地存储保存过的设备 ID、Android ID,如果都无法获取到正确结果则随机生成 UUID,最后获取或生成的设备 ID 会保存于本地存储
iOS尝试获取本地钥匙串保存过的设备 ID,获取失败则随机生成 UUID,最后获取或生成的设备 ID 会保存于本地

设备属性

设备属性表示设备的不变的属性以及最新状态。可以按照设备的某个属性或特征与事件进行关联,来分析这些用户的行为。

常见问题

设备 ID 会发生变化么?

Android:在能获取到 Android ID 的情况下,设备 ID 是比较稳定的(参考 Google 唯一标识符最佳做法)。如果无法获取到 Android ID,设备 ID 将有随着重装应用或重置 Google 广告 ID 而改变的可能。

iOS:获取或生成好的设备 ID 保存于设备的钥匙串中,可以保证在不重置系统的情况下,保持设备 ID 的稳定。

账号

账号 ID (user_id)

通常情况下是你的注册用户 ID,当用户在你的系统中发生注册或登录行为后,你可以将该用户在你的系统中的唯一 ID 直接或加密后设置到 SDK 中,这个 ID 会被作为今后用户在各个平台使用你的产品的身份识别 ID。

账号属性

账号属性表示账号的不变的属性以及最新状态。可以按照账号的某个属性或特征与事件进行关联,来分析这些用户的行为。

事件

什么是事件

预置事件

事件名名称说明
device_loginApp 启动调用 SDK 初始化接口时会上报此事件,首次上报一个设备 ID 时将在设备表产生一条记录
user_login账号登录调用 SDK SetUser 接口时会上报此事件,首次上报一个账号 ID 时将在账号表产生一条记录
play_game游玩时长SDK 会以应用进入前台作为计时起点,置于后台时,上报此时间段的时长
charge用户付费调用 SDK Charge 接口时会上报此事件,通常情况下建议使用服务端 REST API 进行上报

衍生事件

在上报预置事件时,TapDB 也会同时记录一些特殊事件,这类特殊的事件我们称之为衍生事件。衍生事件无法通过 API 直接上报,只会由预置事件上报后触发。

事件名名称说明
dau_deviceApp 当日首次次启动App 在每日首次上报 device_login 时触发,可用于快速查询设备 DAU
dvau_deviceApp 当日首次启动(按版本)App 的不同版本在每日首次上报 device_login 时触发,可用于快速查询分版本的设备 DAU
wau_deviceApp 当周首次启动App 在每周首次上报 device_login 时触发,可用于快速查询设备 WAU
mau_deviceApp 当月首次启动App 在每月首次上报 device_login 时触发,可用于快速查询设备 MAU
dau_user账号当日首次登录账号每日首次上报 user_login 时触发,可用于快速查询账号 DAU
wau_user账号当周首次登录账号每周首次上报 user_login 时触发,可用于快速查询账号 WAU
mau_user账号当月首次登录账号每月首次上报 user_login 时触发,可用于快速查询账号 MAU

自定义事件

除了预置事件和衍生事件外,也可以在事件管理中建立更多自定义事件。

数据规则

TapDB 的 REST API 支持传入数据格式为 URLEncode 后的 JSON 对象, 如果你直接使用 TapDB 的 REST API 则需要按照此格式进行上报。 如果你使用 SDK 接入,数据也会转化成该格式进行上报。

事件数据

记录一个事件及其属性

{
["index" | "client_id"]: ["APPID" | "ClientID"],
"device_id": "DeviceID",
"user_id": "UserID",
"type": "track",
"name": "EventName",
"properties": {
"os": "Android",
"device_id1": "000",
"device_id2": "000",
"device_id3": "000",
"device_id4": "000",
"width": 256,
"height": 768,
"device_model": "pixel",
"os_version": "Android 10.0",
"provider": "O2",
"network": "1",
"channel": "Google Play",
"app_version": "1.0",
"sdk_version": "2.8.0",
"#custem_event_property_name": "CustomEventPropertyValue"
}
}

系统字段

properties 同层级的字段为系统字段

名称数据类型说明
indexstring项目的 APPID,在 TapDB 后台可以查看该 ID
client_idstring项目的 TapTap Client ID,在 TapTap 开发者中心可以查看该 ID
typestring数据类型,上报事件时传入 track
device_idstring事件发生时的设备 ID
user_idstring事件发生时的账号 ID
namestring事件名,可传入预置事件或自定义事件

注意:

  • 预置事件 device_login 必须传入 device_id
  • 预置事件 user_loginplay_game 必须传入 device_iduser_id
  • 预置事件 charge 必须传入有效的 user_id(即上报过 user_loginuser_id

属性字段

properties 内的字段为属性字段,这些传入的字段会被当做事件的属性,你可以通过自定义属性进行扩展。

其中 SDK 预置事件属性:

名称类型说明
osstring操作系统(支持传入 Android、iOS、Windows、Mac)
device_id1string预留设备 ID 槽位(iOS SDK 传入 IDFA,Android SDK 传入 IMEI)
device_id2string预留设备 ID 槽位(Android SDK 传入 Google 广告 ID)
device_id3string预留设备 ID 槽位(Android SDK 传入 Android ID)
device_id4string预留设备 ID 槽位(Android SDK 传入 OAID)
widthnumber屏幕宽度
heightnumber屏幕高度
device_modelstring设备型号(设备厂商+设备型号)
os_versionstring操作系统版本
networkstring网络类型(WiFi 传入 2、未知传入 3、2G 传入 4、3G 传入 5、4G 传入 6)
channelstring分包渠道
app_versionstringApp 版本
sdk_versionstringSDK 版本

属性操作

账号属性操作

{
["index" | "client_id"]: ["APPID" | "ClientID"],
"user_id": "UserID",
"type": ["initialise" | "update" | "add"],
"properties": {
"level": 15,
"#custom": "custom"
}
}

设备属性操作

{
["index" | "client_id"]: ["APPID" | "ClientID"],
"device_id": "DeviceID",
"type": ["initialise" | "update" | "add"],
"properties": {
"level": 15,
"#custom": "custom"
}
}

系统字段

properties 同层级的字段为系统字段

名称数据类型说明
client_idstring项目的 TapTap Client ID,在 TapTap 开发者中心可以查看该 ID
typestring数据类型,属性操作支持 initialiseupdateadd
device_idstring进行属性操作的设备 ID
user_idstring进行属性操作的账号 ID

type 字段传入值的含义

名称说明
initialise对于需要保证只有首次设置时有效的属性,可以使用 initialise 进行赋值操作,仅当前值为空时赋值操作才会生效,如当前值不为空,则赋值操作会被忽略
update对于常规的设备属性,可使用该接口进行赋值操作,新的属性值将会直接覆盖旧的属性值
add对于数值类型的属性,可以使用该接口进行累加操作,调用后 TapDB 将对原属性值进行累加后保存结果值

注意:

  • 进行属性操作时,device_iduser_id 只能二选一传入。传入 device_id 则对该设备 ID 的属性进行操作,传入 user_id 则对该账号 ID 的属性进行操作

属性字段

properties 内的字段为属性字段,这些字段将被视为要操作的字段,按照 type 的值进行处理。