版本：v4

数据规范

设备

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

衍生事件

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

事件名	名称	说明
dau_device	App 当日首次次启动	App 在每日首次上报 `device_login` 时触发，可用于快速查询设备 DAU
dvau_device	App 当日首次启动（按版本）	App 的不同版本在每日首次上报 `device_login` 时触发，可用于快速查询分版本的设备 DAU
wau_device	App 当周首次启动	App 在每周首次上报 `device_login` 时触发，可用于快速查询设备 WAU
mau_device	App 当月首次启动	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",
        "event_uuid": "550e8400-e29b-41d4-a716-446655440000"
    }
}

系统字段

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

名称	数据类型	说明
index	string	项目的 APPID，在 TapDB 后台可以查看该 ID
client_id	string	项目的 TapTap Client ID，在 TapTap 开发者中心可以查看该 ID
type	string	数据类型，上报事件时传入 track
device_id	string	事件发生时的设备 ID
user_id	string	事件发生时的账号 ID
name	string	事件名，可传入预置事件或自定义事件

注意：

预置事件 device_login 必须传入 device_id
预置事件 user_login、play_game 必须传入 device_id和 user_id
预置事件 charge 必须传入有效的 user_id（即上报过 user_login 的 user_id）

属性字段

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

其中 SDK 预置事件属性：

名称	类型	说明
os	string	操作系统（支持传入 Android、iOS、Windows、Mac）
device_id1	string	预留设备 ID 槽位（iOS SDK 传入 IDFA，Android SDK 传入 IMEI）
device_id2	string	预留设备 ID 槽位（Android SDK 传入 Google 广告 ID）
device_id3	string	预留设备 ID 槽位（Android SDK 传入 Android ID）
device_id4	string	预留设备 ID 槽位（Android SDK 传入 OAID）
width	number	屏幕宽度
height	number	屏幕高度
device_model	string	设备型号（设备厂商+设备型号）
os_version	string	操作系统版本
network	string	网络类型（WiFi 传入 2、未知传入 3、2G 传入 4、3G 传入 5、4G 传入 6）
channel	string	分包渠道
app_version	string	App 版本
sdk_version	string	SDK 版本
event_uuid	string	每条日志的唯一 ID，通常传入 UUID

属性操作

账号属性操作

{
    ["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_id	string	项目的 TapTap Client ID，在 TapTap 开发者中心可以查看该 ID
type	string	数据类型，属性操作支持 `initialise`、`update`、`add`
device_id	string	进行属性操作的设备 ID
user_id	string	进行属性操作的账号 ID

type 字段传入值的含义

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

注意：

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

属性字段

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

设备​

设备 ID （device_id）​

生成规则​

设备属性​

常见问题​

账号​

账号 ID （user_id）​

账号属性​

事件​

预置事件​

衍生事件​

自定义事件​

数据规则​

事件数据​

系统字段​

属性字段​

属性操作​

系统字段​

属性字段​

设备

设备 ID （device_id）

生成规则

设备属性

常见问题

账号

账号 ID （user_id）

账号属性

事件

预置事件

衍生事件

自定义事件

数据规则

事件数据

系统字段

属性字段

属性操作

系统字段

属性字段