程序对接文档

把你的程序(网站 / 小程序 / APP / 桌面端)接到统计后台。全部接口无需登录、无需密钥,填上你的应用 ID 就能上报。
实际的上报地址请到后台「上报地址」弹窗复制(本机 / 内网 / 公网三选一,和你程序的部署位置对应)。

上报地址

文档里写的 https://你的后台地址/api/v1 按你的部署位置替换:

本机同服务器:http://127.0.0.1:3006/api/v1
内网另一台机器:http://后台内网IP:3006/api/v1
公网远程接入:https://你的后台域名/api/v1

点「复制实际地址」会取当前页面域名拼出的公网地址;拿不准就用它。

1访问统计上报

回答「多少人访问、用什么终端、停留多久」。接了这个,大屏和基础看板的访客、终端、城市分布才有数据。建议所有程序都接。

① 网页 / 桌面端网页壳(最简单,一行代码)

<script src="https://你的后台地址/assets/analytics-tracker.js"
        data-api-base="https://你的后台地址/api/v1"
        data-app-id="你的应用ID"
        data-terminal-type="web"></script>

放到每个页面 </body> 前即可,访问开始、停留时长自动处理。桌面端程序如果是网页壳,同样用这一行(data-terminal-type 换成 desktop)。

② 小程序 / APP / 原生程序(手动调两个接口)

页面/界面打开时调一次 /analytics/visit,离开时调 /analytics/visit-end 上报停留时长:

// 打开页面时(小程序示例,APP / 桌面端换成自己的 HTTP 请求即可)
wx.request({
  url: 'https://你的后台地址/api/v1/analytics/visit',
  method: 'POST',
  data: {
    appId: '你的应用ID',          // 后台「应用管理」里的应用标识
    terminalType: 'miniprogram', // web / miniprogram / app / desktop
    visitorId: '本地存的访客ID',  // 自己生成一个随机ID,存本地缓存,同一个用户永远用同一个
    sessionId: '本次会话ID',      // 每次打开程序生成一个新的随机ID
    pagePath: 'pages/index/index',
    userId: '登录用户的ID',       // 未登录可以不传
  }
});

// 离开页面时(onUnload / onHide)
wx.request({
  url: 'https://你的后台地址/api/v1/analytics/visit-end',
  method: 'POST',
  data: { appId: '你的应用ID', sessionId: '同一个会话ID', durationSeconds: 停留秒数 }
});
参数必填说明
appId是应用标识,后台按应用区分数据
visitorId / sessionId是访客去重标识(长期不变)/ 会话标识(每次打开新开一个),随机字符串即可,最长 64 位
terminalType建议web / miniprogram / app / desktop,决定大屏终端分布
pagePath否页面路径
userId否登录用户标识

2用户注册上报可选

用户在你的程序里注册成功后上报一条,大屏的用户地区分布、新增注册走势才有数据。传了手机号,后台自动解析归属地(省/市),不用传地区。

wx.request({
  url: 'https://你的后台地址/api/v1/connection/events',
  method: 'POST',
  data: {
    type: 'new_user',
    appId: '你的应用ID',
    userId: 'u10001',            // 必填,你程序里的用户ID
    username: '昵称',
    phone: '13800138000',        // 建议传:自动解析省市归属地
    email: '', nickname: '', avatar: ''
  }
});

3订单上报可选

用户支付成功后上报一条,大屏的收入分类(营收走势、地区营收、商品营收、支付方式)才有数据。

wx.request({
  url: 'https://你的后台地址/api/v1/connection/events',
  method: 'POST',
  data: {
    type: 'new_order',
    appId: '你的应用ID',
    orderNo: '202611100001',     // 必填,订单号(重复上报会覆盖更新,不会重复计数)
    userId: 'u10001',
    amount: 99.9,                // 支付金额(元)
    productName: '商品名称',
    orderStatus: 'paid'
  }
});

4业务数据查看与管理自动入库

你的程序接了上面 1–3 的上报接口后,数据会自动落进后台数据库对应的数据表,程序侧不需要做任何额外对接,也不需要自己建数据库。

程序产生的数据对接方式数据去向(后台「数据库管理」可见)
访问 / 停留时长第 1 节上报接口统计相关数据表
注册用户第 2 节上报接口用户数据表(users)
订单第 3 节上报接口订单数据表(payment_orders)
登录 / 支付等业务各功能模块的对接接口各自对应的业务数据表

查看与管理入口:后台「数据库管理」→「应用数据表」页签,选中你的应用即可看到本应用全部业务数据表(行数、占用空间、数据浏览与导出)。「系统公共表」是平台底层数据,程序和业务一般不直接使用。

需要存放自己的业务数据(如商品、道具、题库、配置项)时,用后台「数据表」功能可视化建表、管理记录,建好的表同样会自动出现在「应用数据表」里。

程序对接查看 / 管理:每个应用都有一套对接凭证(应用 ID + 应用密钥,新建应用时自动生成,应用编辑里可查看、可一键重置)。程序带上这两个请求头,就能调用后台各模块接口查看、管理本应用的数据:

GET https://你的后台地址/api/v1/users
请求头:
  x-app-id: 你的应用ID
  x-app-secret: 你的应用密钥
对接能力(后台按应用勾选对接权限)程序能做的事
用户查看 / 管理本应用用户(/users)
订单 / 支付订单查询管理(/payment-orders)、支付配置、支付回调与对账
会员会员套餐 / 附加权益(/packages、/addons)
消息消息中心通知查看与发送(/message-center/notifications)
合伙人合伙人 / 银行卡信息(/partners、/bank-cards)
激活码发码、激活记录(/activation-codes/issue 等)
游戏角色上报、CDK 核销、发货(/game/*)
业务数据上报第 2、3 节的注册 / 订单上报(/apps/business-data/push)

数据库管理页里的每张业务表,都对应上面某一类接口的数据;程序通过模块接口读写,不需要也不应该直接操作数据库。「数据库管理」页是管理员排查数据用的底层入口。

应用密钥等同账户密码,务必保密、不要写进前端页面代码;怀疑泄露就到应用编辑里重置密钥。哪些接口能调,由后台「应用管理」里给该应用勾选的对接权限决定。

注意事项

① 全部接口无需登录、无需密钥,appId 就是区分应用的依据,务必每个程序填自己的应用 ID;
② 上报失败不要影响程序本身运行,建议静默处理错误(示例里的回调都别写业务逻辑进去);
③ visitorId 长期固定、sessionId 每次打开程序换新的——这是访客数和停留时长统计准确的关键;
④ 用户地区数据:注册用户优先按手机号归属地统计(传了手机号自动解析),没手机号的按 IP 估算,无需程序额外处理。