菜单

Restful API 使用指南

本指南将会为您介绍如何使用数据接入 API，通过使用数据接入 API，可以在不依赖传输工具与 SDK 的情况下，使用 HTTP 的 POST 方法直接向 Datatower.ai 后台传输数据

在开始对接前，您需要先阅读 数据规则 ，在熟悉 DT 的数据格式与数据规则后，再阅读本指南进行对接

POST 方法上传的数据必须遵循 DT 的 数据格式

一、数据格式转换

在上传数据之前，首先需要将数据的格式转换成 DT 的数据格式，DT 的每一条数据都是一个 JSON，数据样例如下（为了方便阅读，数据已经过排版）：

{
        "#app_id": "dt_xxxx",
        "#bundle_id": "com.xxxxxx",
        "#gaid": "0e3b4bxxxxxxxd5818e8a7",
        "#dt_id": "37e04xxxxxxx71a709f94",// 设备唯一 ID，必传，确保唯一即可
        "#acid": "abc",//  用户唯一 ID，
        "#event_time": 1678952745764,
        "#event_name": "#session_start",
        "#event_type": "track",
        "#event_syn": "1447172248184095741",
        "properties": {
                "#mcc": "410",
                "#mnc": "04",
                "#os_country_code": "PK",
                "#os_lang_code": "en",
                "#app_version_code": 10202,
                "#app_version_name": "1.02.02",
                "#os": "Android",
                "#sdk_type": "restful-api",  // 区分sdk类型，restfulAPi请固定为restful-api
                "#sdk_version_name": "1.0.0",  // sdk版本号当前固定为1.0.0
                "active_time": "2024-01-01 00:00:00" // 日期时间请传 UTC 时区，系统默认收到的所有日期时间都是 UTC 时区
        }
}

具体的数据格式规范，请参考 数据格式 一节。

二、数据上报

当您准备好 JSON 数据后，即可进行数据上报，DT 后台接受 HTTP 标准 POST 方式的调用请求，所有接口数据字符集编码均采用 UTF-8 方式。具体的调用方式如下：

2.1 数据接收接口

请将请求头的 Content-Type 设置为 text/plain

如果您使用的是云服务，请输入以下 URL:

https://report.roiquery.com/web?token={token}&app_id={app_id}

2.1.1 接收参数

请求参数一览表

字段名	说明	是否必填
#app_id	DT后台创建的项目app_id，如果数据中的app_id非法，则该条将会直接被过滤	是
#bundle_id	应用包名	是
#dt_id	DT_ID，与设备唯一关联，用于DT后台的用户识别	是
#event_name	事件名当`#event_type`为track时，必须以字母开头，只能包含：字母（区分大小写）、数字和下划线“_”，长度最大为 64 个字符当`#event_type`为user时，表示对用户属性进行设置，此时支持的事件名有： `#user_set`、`#user_set_once`、`#user_unset`、`#user_add`、`#user_append`、 `#user_uniq_append`、`#user_delete`	是
#event_time	事件发生时的客户端时间，获取时间戳，精确到毫秒	是
#event_type	数据类型，`track`和`user`仅两个值	是
#event_syn	本条数据ID，用于当事件时间与事件名完全一样时，进行去重判断	是
#acid	账号ID，如果项目有自己的登录id体系，可设置。与#dt_id一起共同用于用户识别	否
#gaid	Google 的广告设备 ID	否
#debug	本条事件是否debug数据，当为debug时，数据不入库	否

请求参数示例图

Query参数

app_id：您项目的 APPID
token：您的 API_TOKEN，请向 DT 工作人员申请

Body参数

data：经过编码、加密后的字符串

对需要上报的数据（jsonArray），先base64编码

⚠️：data必须保证是jsonArray，再进行base64，否则无法完成上报；
data未编码前的示例：

[
    {
        "#app_id": "dt_xxxxx",
        "#dt_id": "default_dt_id",
        "#acid": "default_acid",
        "#event_name": "test_event",
        "#event_type": "track",
        "#event_time": 1721802135331,
        "properties": {
            "test":"test"
        }
    }
]

然后与一个固定字符串（"@datatower"）进行md5
再urlEncode；

代码示例：

const dataToBase64 = encodeToBase64(data_ready_to_report);
const mdData = md5(dataToBase64 + "@datatower");

// 最终发送时的data字符串
const resultData = `data=${encodeURIComponent(dataToBase64)}&check=${mdData}`

注意 : 不同语言的库有可能自带 urlencode, 这时候不需要再次 urlencode了, 例如 Python3 的 requests 库，postman 的请求测试等

2.1.2 返回参数

如果收到返回参数，code: 0，则代表数据传输成功

2.1.3 常见错误码说明

错误码	错误信息	说明
1	Identify Error	app_id或者API_TOKEN填写有误
4	Verify Error	check不通过，检查一下数据加密与编码是否正确

上一个

下一个

数据导入

最近修改: 2025-02-19

大纲