数据上报指引

数据中心提供了 HTTPS+JSON 协议的数据上报接口，开发者可通过开发对接程序将数据以实时或离线方式上报至数据中心

数据定义

一条数据可用一个 Object，多条数据可以用一个 Array 来表示：

[
    {
        "type": "<model type>",
        "from": "<data source>",
        "props": {
            "foo": "bar"
        }
    },
    {
        "type": "<model type>",
        "from": "<data source>",
        "props": {
           "foo": "bar"
        }
    }
]

属性	类型	说明
type	string	这条数据代表的模型类型
props	object	实例属性，不属于模型的字段仍然会保存，但在处理时会忽略
from	string	表示这条数据的来源，例如来自小程序A还是小程序B，关键要在自己的业务体系便于区分且是唯一标识
tracking_id	string	当前会话的uuid追踪码，这个字段可为数据恢复、行为追溯等场景提供很大的便利，建议上报

属性

类型

必填

说明

type

string

这条数据代表的模型类型

props

object

实例属性，不属于模型的字段仍然会保存，但在处理时会忽略

from

string

表示这条数据的来源，例如来自小程序A还是小程序B，关键要在自己的业务体系便于区分且是唯一标识

tracking_id

string

当前会话的uuid追踪码，这个字段可为数据恢复、行为追溯等场景提供很大的便利，建议上报

tracking_id

tracking_id在前端生成，建议使用uuid/v4的方案

tracking_id应在会话初始阶段生成，并在会话期间上报的所有数据都附带上该标识

常规接口上报

请求

HTTP规范说明

HTTP规范	说明
URL	`https://zhls.qq.com/api/report?app_id=APPID&timestamp=TIMESTAMP&nonce=NONCE`
Query	app_id 数据中心分配的接入凭证字符串，用于识别客户身份，不同的小程序或公众号需要不同的app_id（app_id暂时通过中心侧分配）（注意此app_id不同于小程序或公众号的app_id） timestamp 当前的时间戳，单位为秒 nonce 随机字串标识，不超过32个字符
Body	可定义2种格式： `JSON Object`，代表一条数据 `JSON Array`，代表多条数据

URL

https://zhls.qq.com/api/report?app_id=APPID&timestamp=TIMESTAMP&nonce=NONCE

Query

app_id 数据中心分配的接入凭证字符串，用于识别客户身份，不同的小程序或公众号需要不同的app_id（app_id暂时通过中心侧分配）（注意此app_id不同于小程序或公众号的app_id）
timestamp 当前的时间戳，单位为秒
nonce 随机字串标识，不超过32个字符

Body

可定义2种格式：

JSON Object，代表一条数据
JSON Array，代表多条数据

属性	说明
Response Status Code	200表示联调成功
Body	code 非0表示客户端错误 msg 具体错误内容

属性

说明

Response Status Code

200表示联调成功

Body

code 非0表示客户端错误
msg 具体错误内容

可靠接口上报

为了提高数据接入的稳定性（同步返回结果）和安全性（数据加密），特提供后台数据上报接口。

与常规接口上报的url不同，此处为v1/safe-report

请求

POST https://zhls.qq.com/api/v1/safe-report?app_id=<app_id>&nonce=<nonce>&timestamp=<timestamp>&sign=<sign>&signature=<signature>
body <数据内容: JSON Object or JSON Array>

签名

下面是签名过程会涉及的参数

参数说明

参数	说明
app_id	数据中心分配的应用ID
app_secret	数据中心分配的签名密钥，需要绝对保密
timestamp	当前时间戳，单位为秒
nonce	随机字符串标识，不超过32个字符
sign	签名算法，目前只支持 `sha256`
signature	最终的签名参数

app_id

数据中心分配的应用ID

app_secret

数据中心分配的签名密钥，需要绝对保密

timestamp

当前时间戳，单位为秒

nonce

随机字符串标识，不超过32个字符

sign

签名算法，目前只支持 sha256

signature

最终的签名参数

计算签名

随机生成 timestamp、nonce
拼接字符串：app_id=<app_id>&nonce=<nonce>&sign=<sign>&timestamp=<timestamp>（key已经按字符串顺序顺次排列，不需要对value进行url encode）
使用`sign`算法和`app_secret`对拼接的字符串进行加密，然后使用hex进行编码，获得签名`signature`

示例

随机生成：timestamp = "1542951251", nonce = "407313d23c3f7"
拼接字符串：conStr = "app_id=abc&nonce=407313d23c3f7&sign=sha256&timestamp=1542951251"
signature = hex(sha256(conStr)) = "6e54c38c7e9c382a5295c3885503fa4a9ee37cabc884350d84973fc1b843126d"

代码示例

const crypto = require('crypto')
const request = require('request')
const app_id = 'abc'
const app_secret = 'xyz'

const timestamp = parseInt(Date.now() / 1000)

const nonce = Math.random().toString(16).substring(2) // 生成随机字符串

const str = `app_id=${app_id}&nonce=${nonce}&sign=sha256&timestamp=${timestamp}`
console.log(str)

const signature = crypto.createHmac('sha256', app_secret).update(Buffer.from(str, 'utf-8')).digest('hex');
console.log(signature)

let url = `https://zhls.qq.com/api/v1/safe-report?${str}&signature=${signature}`

request({
    method: "POST",
    url: url,
    json: true,
    timeout: 1000,
    body: {
        data: 'hello world'
    }
}, function (err, rsp, body) {
    if (!err && rsp.statusCode == 200) {
        console.log('report success', JSON.stringify(body))
    } else {
        console.log(`report err`, err, (rsp || {}).statusCode)
    }
})

本地用户识别码（UUID）

为了提高采集成功率，加入了针对open_id的修复环节，依赖SDK生成的本地UUID，没有使用SDK上报的业务需要自己实现。

下载生成算法

以下是代码示例：

// 下载算法文件，如 getUUID.js
import getUUID from './getUUID'

let local_id

onLaunch() {
  // 请在APP加载后第一时间完成
  this.setUserLocalId();
}
setUserLocalId() {
  try {
    // localStorage - 业务自己实现对本地存储的管理类
    local_id =localStorage.get('local_id')
  } catch() {}

  // 判断本地存储，防止重复生成
  if (!local_id) {
    local_id = getUUID()
    localStorage.set('local_id', local_id)
  }

  // 将本地ID回填到上报上下文的用户信息中
  sr.setUser({ local_id })
}