📖 概述

神策数据分析（Sensors Analytics）是一款专业的用户行为分析产品。本文档基于 SensorsConfig.java 配置类，详细说明如何在项目中集成神策数据分析功能。

✨ 功能特性

🏗️ 技术架构

应用层 → ISensorsAnalytics → Consumer → 神策服务器 (埋点接口) (数据消费者) (数据收集)

📦 依赖配置

Maven 依赖

在项目的 pom.xml 中添加神策 SDK 依赖：

<!-- 引入神策分析 SDK -->
<dependency>
    <groupId>com.sensorsdata.analytics.javasdk</groupId>
    <artifactId>SensorsAnalyticsSDK</artifactId>
    <version>3.6.8</version>
</dependency>

📋 版本兼容性

⚙️ 配置说明

配置属性类

项目中使用 SensorsDataProperties 类来管理神策相关配置：

@RefreshScope
@Data
@Component
@ConfigurationProperties(prefix = "sensorsdata")
public class SensorsDataProperties {

    /**
     * 神策服务地址
     */
    private String serverUrl;

    /**
     * 埋点模式
     */
    private String trackMode;

    /**
     * 神策事件名称
     */
    private String eventName;

    /**
     * 批量发送配置
     */
    private BatchMode batch;

    @Data
    public static class BatchMode {
        /**
         * 快速批量发送模式"每次发送"条数阈值
         */
        private Integer bulkSize;

        /**
         * 缓存队列最大条数
         */
        private Integer maxCacheSize;

        /**
         * 超时时间（秒）
         */
        private Integer timeoutSeconds;
    }
}

跟踪模式枚举

支持的跟踪模式定义在 SensorsTrackModeEnums 中：

public enum SensorsTrackModeEnums implements EnumLookUp<String> {
    DEBUG("debug", "测试上报"),
    BATCH("batch", "批量模式"),
    FAST_BATCH("fast_batch", "快速批量模式");
}

📝 配置参数详解

🔧 代码集成

配置类

将 SensorsConfig.java 添加到项目中：

/**
 * @author 开发者
 * @date 2025/11/11 15:55:00
 */
@Slf4j
@Configuration
public class SensorsConfig {

    @Resource
    private SensorsDataProperties sensorsDataProperties;

    @Bean(destroyMethod = "shutdown")
    public ISensorsAnalytics init() {

        SensorsTrackModeEnums trackModeEnums =
            EnumLookUp.getEnumInstance(SensorsTrackModeEnums.class, sensorsDataProperties.getTrackMode());

        switch (trackModeEnums) {
            case DEBUG:
                // 注意：debug 模式数据不会写入服务器
                // URL 会从 https://api.example.com/sa?project=stage
                // 变为 https://api.example.com/debug?project=default
                log.info("sensorsData debug mode");
                return new SensorsAnalytics(new DebugConsumer(sensorsDataProperties.getServerUrl(), true));

            case BATCH:
                log.info("sensorsData batch mode");
                return new SensorsAnalytics(new BatchConsumer(sensorsDataProperties.getServerUrl()));
        }

        log.info("sensorsData default mode [batch]");
        return new SensorsAnalytics(new BatchConsumer(sensorsDataProperties.getServerUrl()));
    }
}

💻 使用示例

基本埋点

@Service
public class UserBehaviorService {

    @Resource
    private ISensorsAnalytics sensorsAnalytics;

    @Resource
    private SensorsDataProperties sensorsDataProperties;

    /**
     * 用户点击事件埋点
     */
    public void trackUserClick(String userId, String creditApplyNo, String scene) {
        Map<String, Object> properties = new HashMap<>();
        properties.put("f_credit_apply_no", creditApplyNo);
        properties.put("f_quotient_scene", scene);
        properties.put("timestamp", System.currentTimeMillis());

        // 发送埋点数据
        sensorsAnalytics.track(userId, false, sensorsDataProperties.getEventName(), properties);

        // 立即刷新（可选）
        sensorsAnalytics.flush();
    }
}

业务场景示例

@Service
public class CreditApplyService {

    @Resource
    private ISensorsAnalytics sensorsAnalytics;

    @Resource
    private SensorsDataProperties sensorsDataProperties;

    /**
     * 授信申请成功埋点
     */
    public void trackCreditApplySuccess(CreditApply creditApply, Partner partner) {
        Map<String, Object> properties = new HashMap<>();
        properties.put("f_credit_apply_no", creditApply.getSeqNo());
        properties.put("f_quotient_scene", partner.getPartnerCode());
        properties.put("f_credit_amount", creditApply.getCreditAmount());
        properties.put("f_apply_time", creditApply.getCreateTime());

        // 使用随机 UUID 作为匿名用户标识
        String distinctId = UUID.randomUUID().toString();

        sensorsAnalytics.track(distinctId, false, sensorsDataProperties.getEventName(), properties);
        sensorsAnalytics.flush();
    }
}

测试代码

@Test
public void testSensorsAnalytics() {
    Map<String, Object> properties = new HashMap<>();
    properties.put("f_credit_apply_no", "CA20251111000001");
    properties.put("f_quotient_scene", "miniWallet");
    properties.put("f_event_type", "click");

    sensorsAnalytics.track(
        UUID.randomUUID().toString(),
        false,
        "d_h5_trilateral_credit_claim_click",
        properties
    );

    sensorsAnalytics.flush();
}

🔐 配置示例

开发环境配置

# application-dev.yml
sensorsdata:
  server-url: https://api.example.com/sa?project=dev
  track-mode: debug
  event-name: d_h5_trilateral_credit_claim_click
  batch:
    bulk-size: 50
    max-cache-size: 5000
    timeout-seconds: 10

测试环境配置

# application-test.yml
sensorsdata:
  server-url: https://api.example.com/sa?project=stage
  track-mode: batch
  event-name: d_h5_trilateral_credit_claim_click
  batch:
    bulk-size: 100
    max-cache-size: 10000
    timeout-seconds: 30

生产环境配置

# application-prod.yml
sensorsdata:
  server-url: https://api.example.com/sa?project=production
  track-mode: batch
  event-name: d_h5_trilateral_credit_claim_click
  batch:
    bulk-size: 200
    max-cache-size: 20000
    timeout-seconds: 60

Nacos 配置中心

如果使用 Nacos 配置中心，可以在对应的 dataId 中添加：

# example-backend.yml
sensorsdata:
  server-url: ${sensors.server.url:https://api.example.com/sa?project=stage}
  track-mode: ${sensors.track.mode:batch}
  event-name: ${sensors.event.name:d_h5_trilateral_credit_claim_click}
  batch:
    bulk-size: ${sensors.batch.bulk-size:100}
    max-cache-size: ${sensors.batch.max-cache-size:10000}
    timeout-seconds: ${sensors.batch.timeout-seconds:30}

⚠️ 注意事项

重要提醒

🚀 性能优化

异常处理示例：

try {
    sensorsAnalytics.track(distinctId, isLoginId, eventName, properties);
    sensorsAnalytics.flush();
} catch (Exception e) {
    log.error("神策埋点失败", e);
    // 不影响主业务流程
}

📊 数据规范

🔍 问题排查

常见问题

📝 日志调试

开启神策 SDK 日志：

logging:
  level:
    com.sensorsdata: DEBUG
    com.example.backend.config.SensorsConfig: DEBUG

🏥 健康检查

@Component
public class SensorsHealthCheck {

    @Resource
    private ISensorsAnalytics sensorsAnalytics;

    @PostConstruct
    public void checkSensorsStatus() {
        try {
            // 发送测试事件
            Map<String, Object> testProps = new HashMap<>();
            testProps.put("test", "health_check");

            sensorsAnalytics.track("health_check", false, "system_health_check", testProps);
            log.info("神策数据分析初始化成功");
        } catch (Exception e) {
            log.error("神策数据分析初始化失败", e);
        }
    }
}

🎯 最佳实践

代码组织

统一埋点服务：

@Service
public class SensorsTrackingService {

    @Resource
    private ISensorsAnalytics sensorsAnalytics;

    public void trackEvent(String userId, String eventName, Map<String, Object> properties) {
        // 统一的埋点逻辑
    }
}

事件常量管理：

public class SensorsEventConstants {
    public static final String CREDIT_APPLY_CLICK = "d_h5_trilateral_credit_claim_click";
    public static final String USER_REGISTER = "d_user_register";
    public static final String ORDER_CREATE = "d_order_create";
}

📊 监控告警

🗂️ 数据治理

📚 附录

相关文件清单

参考链接