SensorFlow 快速开始

完整数据链路

SensorFlow 将采集、接收、存储和分析部署在你自己的服务器中。

• 神策官方各端 SDK 负责采集 Android、iOS、Web、小程序和服务端事件。
• SensorFlow 接收服务校验并处理事件。
• ClickHouse 保存事件与用户明细，Apache Superset 提供 SQL、图表和运营看板。

神策官方 SDK -> SensorFlow 接收服务 -> ClickHouse -> Apache Superset

系统要求

本地验证只需要 Docker Engine 或 Docker Desktop 与 Docker Compose v2；无需单独安装 Go。

• 首次启动需要下载 Go、ClickHouse、Redis 与 Superset 镜像。
• 生产环境需按事件量、查询压力和数据保留期评估资源。

1. 获取开源服务

克隆 SensorFlow 开源仓库并进入项目根目录。

git clone https://github.com/data-analyze-bi/sensorFlow.git
cd sensorFlow

2. 一键安装并查看 Superset

安装 Docker 后，在仓库根目录运行安装器。它会生成缺失凭证、启动 Redis、ClickHouse 和 Apache Superset，并等待 Superset 健康检查通过。

• 安装器完成后会用红色显示 Superset 管理员账号和密码，请保存到密码管理器。
• 打开安装器输出的 http://服务器IP:8088 查看演示看板；服务器或云防火墙需允许 TCP 8088。
• 绑定域名分两类：SUPERSET_DOMAIN 只提供图表页面；SENSORFLOW_DOMAIN 只接收 /sensors/* 埋点请求。两个域名都使用时必须不同。

./install.sh

# Superset 域名示例：analytics.example.com
# SensorFlow 埋点域名示例：track.example.com
# 查看演示后，再获取许可证并运行：
./activate.sh

3. 验证演示看板

打开安装器输出的 Superset 地址，使用它生成的管理员账号查看 demo_* 合成事件看板。

• 演示数据用于核对部署和分析流程，不是客户业务数据或产品效果。
• 安装阶段不启动真实 SDK 接收服务；不要在此时发送生产埋点。

4. 检查演示数据，再激活真实接收

先直接查询演示事件。准备接入真实 SDK 时，从运营网站下载许可证，再运行 activate.sh；安装器生成的 token 用于接收端鉴权。

• 以下命令适用于安装器新建的 Compose ClickHouse；复用现有数据库时，请使用该数据库的连接方式。
• 许可证激活后再发送唯一 integration_test 事件，核对原始记录和属性类型。

docker compose -f deploy/docker/docker-compose.yml exec -T clickhouse sh -c 'exec clickhouse-client --user "$CLICKHOUSE_USER" --password "$CLICKHOUSE_PASSWORD" --query "SELECT event, count() FROM sensors.event GROUP BY event ORDER BY event"'

# 下载许可证后，最后启动真实 SDK 接收服务
./activate.sh

5. 接入神策官方 SDK

本项目不发布自研客户端 SDK，请选择业务端对应的神策官方 SDK，并将上报地址指向 SensorFlow。

• ⚠️ 关于第三方 SDK 兼容性的重要说明：兼容标准上报流程不代表神策官方认证；SDK 版本、加密插件、可视化埋点和全埋点功能需先在测试环境验证。
• 客户端支持 Android、iOS、Web、微信小程序与 React Native；服务端按业务语言选择 Java、Go、Python、Node.js 或 PHP 官方 SDK。
• 保留现有事件名、登录 ID 和属性类型，验证接收、用户关联、ClickHouse 入库与 Superset 指标后再切换生产。

https://your-domain.example/sensors/send/?token=YOUR_TOKEN

各端 SDK 官方下载入口

以下链接指向 sensorsdata GitHub 官方组织仓库。本项目不包含或再分发这些 SDK；下载前请查看所选版本仓库中的 LICENSE 与官方使用条款。

Web / JavaScript SDK

用于网站和 Web 应用采集页面浏览、点击、自定义事件及用户属性。请从神策官方仓库或官方文档选择适用版本。

• 可通过 npm、yarn 或官方支持的浏览器引入方式安装。
• 将 server_url 指向 SensorFlow 接收地址；单页应用按官方文档启用页面切换采集。
• 生产环境关闭调试日志，并确认 Beacon/CORS 与域名策略。

npm install sa-sdk-javascript

import sensors from 'sa-sdk-javascript';
sensors.init({
  server_url: 'https://your-domain.example/sensors/send/?token=YOUR_TOKEN',
  is_track_single_page: true,
  use_client_time: true,
  send_type: 'beacon'
});
sensors.quick('autoTrack');
sensors.track('ButtonClick', { button_name: 'Submit', page_name: 'Registration' });
sensors.login('USER_ID');

iOS SDK

按神策 iOS 官方文档通过 CocoaPods 或 Swift Package Manager 安装，将数据接收地址改为 SensorFlow。

• SensorFlow 接收端与神策云服务无关，无需配置神策云项目 Scheme。
• 先在测试环境验证自动采集、用户登录 ID、自定义属性及 App 生命周期事件。
• 正式发布前关闭 SDK 调试日志。

import SensorsAnalyticsSDK

let options = SAConfigOptions(
  serverURL: "https://your-domain.example/sensors/send/?token=YOUR_TOKEN",
  launchOptions: launchOptions
)
options.enableLog = true
options.enableAutoTrack = .default
SensorsAnalyticsSDK.start(configOptions: options)
SensorsAnalyticsSDK.sharedInstance()?.login("USER_ID")
SensorsAnalyticsSDK.sharedInstance()?.track("ButtonClick", withProperties: ["button_name": "Submit"])

Android SDK

按神策 Android 官方文档添加 Gradle 依赖，在 Application 中以 SensorFlow 地址初始化。

• SensorFlow 接收端与神策云服务无关，无需配置神策云项目 Scheme。
• 按隐私合规要求配置自动采集范围和用户授权时机。
• 发布前关闭 enableLog，并验证混淆、网络权限与 HTTPS。

SAConfigOptions options = new SAConfigOptions(
  "https://your-domain.example/sensors/send/?token=YOUR_TOKEN"
);
options.setAutoTrackEventType(
  SensorsDataAPI.AutoTrackEventType.APP_START |
  SensorsDataAPI.AutoTrackEventType.APP_END |
  SensorsDataAPI.AutoTrackEventType.APP_CLICK
);
options.enableLog(true);
SensorsDataAPI.startWithConfigOptions(this, options);
SensorsDataAPI.sharedInstance().login("USER_ID");
SensorsDataAPI.sharedInstance().track("ButtonClick", properties);

微信小程序 SDK

从神策官方渠道获取小程序 SDK，在 app.js 中初始化并配置 SensorFlow HTTPS 接收域名。

• 在微信公众平台将接收域名加入 request 合法域名。
• 按业务和隐私要求选择 appLaunch、appShow、pageShow、pageShare 等自动采集项。
• 在真机与正式域名环境验证网络请求。

import sensors from './utils/sensorsdata.min.js';

sensors.init({
  server_url: 'https://your-domain.example/sensors/send/?token=YOUR_TOKEN',
  autotrack: {
    appLaunch: true, appShow: true, appHide: true,
    pageShow: true, pageShare: true
  },
  show_name: true
});
sensors.login('USER_ID');
sensors.track('ButtonClick', { button_name: 'Submit' });

React Native SDK

按神策 React Native 官方文档安装 npm 依赖并完成 iOS、Android 原生侧初始化。

• 确认 npm 包与两端原生 SDK 版本兼容。
• 将 serverUrl 指向 SensorFlow，验证页面浏览与自定义事件。
• 升级 React Native 或原生 SDK 前先在测试环境回归。

import RNSensorsAnalyticsModule from 'react-native-sensors-analytics';

RNSensorsAnalyticsModule.init({
  serverUrl: 'https://your-domain.example/sensors/send/?token=YOUR_TOKEN',
  autoTrackAppViewScreen: true
});
RNSensorsAnalyticsModule.login('USER_ID');
RNSensorsAnalyticsModule.track('ButtonClick', { button_name: 'Submit' });

服务端 SDK

Java、Go、Python、Node.js、PHP 等服务端应用应使用神策对应官方 SDK，在业务成功后上报可信事件。

• 复用应用级 SDK 实例，不要在每个请求中重复初始化。
• 客户端与服务端使用一致的登录 ID，避免同一用户被拆分。
• 进程退出前 flush/close，金额等字段使用稳定的数据类型。

# Python 示例
pip install SensorsAnalyticsSDK

from sensorsanalytics import SensorsAnalytics
sa = SensorsAnalytics(server_url='https://your-domain.example/sensors/send/?token=YOUR_TOKEN')
sa.track(distinct_id='USER_ID', event_name='ProductView', properties={
    'product_name': 'Example', 'price': 5999
})
sa.flush()
sa.close()

验证 SDK 数据采集

完成任一端接入后，先发送 integration_test 事件，再逐层检查请求、接收服务、ClickHouse 与 Superset。

• 在客户端网络面板或日志中确认请求到达 /sensors/send/。
• 检查接收服务没有许可证、格式或属性类型错误。
• 在 ClickHouse 查询 integration_test，并在 Superset SQL Lab 使用同一数据源复核。
• 确认登录前后 distinct_id 关联、事件时间和属性类型符合预期。

SELECT event, distinct_id, time, properties
FROM sensors.event
WHERE event = 'integration_test'
ORDER BY time DESC
LIMIT 10;

6. 验证 ClickHouse 数据

发送测试事件后，在 ClickHouse 查询事件是否已经入库。

SELECT event, count() AS event_count
FROM sensors.event
GROUP BY event
ORDER BY event_count DESC
LIMIT 20;

7. 使用 Superset 分析

打开 Superset，选择已配置的 ClickHouse 数据库，即可通过 SQL Lab、数据集、图表和看板分析数据。

• 查看日活、注册、登录、事件趋势等常用运营指标。
• 组合漏斗、留存、路径与分群看板。
• 按团队、项目或数据集配置访问权限。

更新与运维

停止接收服务后再替换许可证，重新赋予执行权限并启动服务。

• 定期备份 MySQL、ClickHouse 和 Superset 元数据。
• 监控接收失败、ClickHouse 磁盘水位、写入延迟与查询耗时。
• 许可证到期前在控制台续费，累计有效期会在现有截止时间后顺延。