版本：v3

服务端接入

你可以直接使用 REST API 进行接入，可以在不依赖 SDK 的情况下直接将数据上报到 TapDB。

上报事件和属性

数据传输的格式和含义请参考数据规则。

如果返回 Response Code 为 200，则代表数据上报成功，请在埋点管理中进一步查看事件的写入情况。

单条上报

POST https://e.tapdb.net/v2/event

Content-Type: application/json

请求内容示例：

{
    "client_id": "test_appid",
    "device_id": "test_device_id",
    "user_id": "test_user_id",
    "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": "7656c71f-6d73-488e-b740-3ab370c6f3db"
    }
}

批量上报

POST https://e.tapdb.net/v2/batch

Content-Type: application/json

请求内容示例：

{
  "data": [
    {
      "client_id": "test_appid",
      "device_id": "test_device_id",
      "user_id": "test_user_id",
      "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": "7656c71f-6d73-488e-b740-3ab370c6f3db"
      }
    },
    {
      "client_id": "test_appid",
      "device_id": "test_device_id",
      "user_id": "test_user_id",
      "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": "1c11f92e-6f18-417d-8aed-ffbe668a9feb"
      }
    }
  ]
}

常见问题

若当前事件的主体并非设备或账号，device_id 和 user_id 可以传入任意一个固定值
为了保证服务端上报的事件也能使用设备维度进行分析，建议在客户端调用 SDK 的 GetDeviceID 接口取得 SDK 为该设备生产的唯一 ID 并上报到 App 的服务端

特殊类型事件上报

在线人数

由于 SDK 无法推送准确的在线数据，这里提供服务端在线数据推送接口。游戏服务端可以以小于 1 分钟的间隔自行统计在线人数（间隔 0.5 分钟为最佳），通过接口推送到 TapDB。TapDB 按照 2 分钟的颗粒度汇总展现。

注意：在线人数使用 json 格式上报，这与其他通用事件上报的格式有差别，请注意区分。

POST https://se.tapdb.net/tapdb/online

Content-Type: application/json

请求内容：

参数	参数类型	参数说明
client_id	string	游戏的 ClientID
onlines	array	多条在线数据（最多 100 条）

其中 onlines 数组的结构为

参数	参数类型	参数说明
server	string	服务器。TapDB 对同一服务器每一个自然 1 分钟仅接受一次数据
online	number	在线人数
timestamp	number	当前统计数据的时间戳（秒）。TapDB 会按照自然 2 分钟进行数据对齐

示例：

{
    "client_id":"ClientID",
    "onlines":[{
      "server":"s1",
      "online":123,
      "timestamp":1489739590
    },{
      "server":"s2",
      "online":188,
      "timestamp":1489739560
    }]
}

常见问题

Q：统计数据如何按 2 分钟对齐

A：在线人数图表展示的横坐标每个点间隔 2 分钟，分别是每个小时的 0、2、4 至 58 分，实际数据统计周期为该时间点前 0.5 分钟到后 0.5 分钟、后 0.5 分钟到后 1.5 分钟。以图表 10 点 04 分的点为例，分别统计的是 10 点 03 分 30 秒至 10 点 04 分 30 秒、 10 点 04 分 30 秒至 10 点 05 分 30 秒这两个时间范围（指上报数据内容的 timestamp 字段，而非实际请求接口的时间）内，各 server 在线人数的总和。这个点大约在 10 点 04 分 30 秒至 10 点 05 分 30 秒时显示前一个时间段（10 点 03 分 30 秒至 10 点 04 分 30 秒）的统计数据，10 点 05 分 30 秒之后显示后一个时间段（ 10 点 04 分 30 秒至 10 点 05 分 30 秒）的统计数据。

Q：在线人数曲线有缺口是什么原因

A：请检查上报数据的频率是否低于 1 分钟一次。为了保证图表的展示的曲线平滑，可直接将上报频率调整为每分钟 2 次，并在上报失败时进行重试，直至上报成功。

充值记录

由于 SDK 推送可能会不准确，建议直接使用服务端充值推送接口。注意需要停止客户端 SDK 中充值信息的上报，防止重复统计。

POST https://e.tapdb.net/v2/event

Content-Type: application/json

{
  "name": "charge", // 事件名，固定为 charge
  "client_id": "ClientID", // 必需。注意 ClientID 需要被替换成游戏的 ClientID
  "user_id": "userId", // 必需。用户 ID。必须和 SDK 的 setUser 接口传递的 userId 一样，并且该用户已经通过 SDK 接口进行过推送
  "type": "track", // 必需。数据类型，请确保传入的值为 track
  "properties": {
    "ip": "8.8.8.8", // 可选。充值用户的 IP
    "order_id": "100000", // 必需。长度大于 0 并小于等于 256。订单 ID。
    "amount": 100, // 必需。大于 0 并小于等于 100000000000。充值金额。单位分，即无论什么币种，都需要乘以 100
    "virtual_currency_amount": 100, //获赠虚拟币数量，必传，可为 0
    "currency_type": "CNY", // 可选。货币类型。国际通行三字母表示法，为空时默认 CNY。参考：人民币 CNY，美元 USD；欧元 EUR
    "product": "item1", // 可选。长度大于 0 并小于等于 256。商品名称
    "payment": "alipay" // 可选。长度大于 0 并小于等于 256。充值渠道
  }
}

TapDB 并不会对上报的充值数据进行去重，当接口返回 200 时则代表 TapDB 已经接受到该条日志数据，请到埋点概览中查看该条数据后续的落盘情况。反复上报相同订单记录将会导致数据被重复统计

退款记录

对于需要进行退款分析的游戏，这里提供服务端退款数据推送接口。该接口的属性与付费事件的属性基本一致，但额外增加了一个 origin_order_id 字段，用于追踪原始订单的 ID。

POST https://e.tapdb.net/v2/event

Content-Type: application/json

{
  "name": "refund", // 事件名，固定为 refund
  "client_id": "ClientID", // 必需。注意 ClientID 需要被替换成游戏的 ClientID
  "user_id": "userId", // 必需。用户 ID。必须和 SDK 的 setUser 接口传递的 userId 一样，并且该用户已经通过 SDK 接口进行过推送
  "type": "track", // 必需。数据类型，请确保传入的值为 track
  "properties": {
    "ip": "8.8.8.8", // 可选。充值用户的 IP
    "timestamp": 1718101321234, // 可选。毫秒级时间戳。退款事件发生时间。
    "order_id": "100000", // 必需。长度大于 0 并小于等于 256。订单 ID。
    "origin_order_id": "200000", // 可选。长度大于 0 并小于 256。原始充值订单 ID。
    "amount": 100, // 必需。大于 0 并小于等于 100000000000。充值金额。单位分，即无论什么币种，都需要乘以 100
    "virtual_currency_amount": 100, //获赠虚拟币数量，必传，可为 0
    "currency_type": "CNY", // 可选。货币类型。国际通行三字母表示法，为空时默认 CNY。参考：人民币 CNY，美元 USD；欧元 EUR
    "product": "item1", // 可选。长度大于 0 并小于等于 256。商品名称
    "payment": "alipay" // 可选。长度大于 0 并小于等于 256。充值渠道
  }
}

上报事件和属性​

单条上报​

批量上报​

常见问题​

特殊类型事件上报​

在线人数​

常见问题​

充值记录​

退款记录​

上报事件和属性

单条上报

批量上报

常见问题

特殊类型事件上报

在线人数

常见问题

充值记录

退款记录