tanqiu/assets/scripts/Utils/埋点测试说明.md

埋点功能测试说明

概述

本文档说明如何测试已实现的埋点功能，确保事件追踪正常工作。

已实现的埋点功能

1. 埋点管理器 (AnalyticsManager)

• 基础事件追踪功能
• 小程序生命周期事件追踪
• 场景加载事件追踪
• 游戏进度事件追踪
• 新手引导事件追踪

2. 小程序生命周期管理器 (MPLifecycleManager)

• 自动监听小程序显示/隐藏事件
• 自动监听Web页面可见性变化
• 会话时长统计

3. LaunchScreen 集成

• 启动页面埋点集成
• 场景加载进度追踪
• 小程序生命周期事件追踪

测试方法

方法一：控制台测试（推荐）

1. 在游戏运行时，打开浏览器开发者工具

2. 在控制台中运行以下命令：

   // 初始化埋点系统
   testAnalytics.init();
   
   // 运行所有测试
   testAnalytics.runAll();
   
   // 测试特定功能
   testAnalytics.test('basic');      // 基础功能
   testAnalytics.test('lifecycle');  // 生命周期事件
   testAnalytics.test('scene');      // 场景加载事件
   testAnalytics.test('progress');   // 游戏进度事件
   testAnalytics.test('manager');    // 生命周期管理器
   
   // 手动发送测试事件
   testAnalytics.sendTestEvent('custom_event', {
   property1: 'value1',
   property2: 123
   });
   
   // 获取当前会话时长
   testAnalytics.getSessionDuration();
   

方法二：代码集成测试

在需要测试的场景中导入并使用测试类：

import { AnalyticsTestSimple } from './Utils/AnalyticsTestSimple';

// 创建测试实例
const tester = new AnalyticsTestSimple();

// 运行所有测试
tester.runAllTests();

// 测试特定功能
tester.testSpecificFeature('basic');

预期的测试结果

成功的测试输出示例：

[AnalyticsTest] 开始运行埋点测试...
[AnalyticsTest] ✅ 基础埋点功能测试通过
[AnalyticsTest] ✅ 小程序生命周期事件测试通过
[AnalyticsTest] ✅ 场景加载事件测试通过
[AnalyticsTest] ✅ 游戏进度事件测试通过
[AnalyticsTest] ✅ 小程序生命周期管理器测试通过
[AnalyticsTest] 测试完成
[AnalyticsTest] 通过: 5 项
[AnalyticsTest] 失败: 0 项

埋点事件输出示例：

[Analytics] 发送事件: test_custom_event
[Analytics] 发送事件: $MPLaunch
[Analytics] 发送事件: $MPShow
[Analytics] 发送事件: $MPHide
[Analytics] 发送事件: $SceneLoadStart
[Analytics] 发送事件: $SceneLoaded
[Analytics] 发送事件: $SceneUnloaded
[Analytics] 发送事件: $CompleteSection
[Analytics] 发送事件: $UpdateLevel
[Analytics] 发送事件: $TutorialStart
[Analytics] 发送事件: $TutorialFinish

实际游戏中的埋点验证

1. 启动页面埋点

• 启动游戏时应该看到 $MPLaunch 和 $MPShow 事件
• 场景加载时应该看到 $SceneLoadStart 和 $SceneLoaded 事件

2. 小程序生命周期埋点

• 切换到后台时应该看到 $MPHide 事件
• 回到前台时应该看到 $MPShow 事件和 $MPBackgroundTime 事件

3. 场景切换埋点

• 场景切换时应该看到 $SceneUnloaded 和新场景的 $SceneLoadStart、$SceneLoaded 事件

事件数据表对照

根据 弹弹守卫战_事件数据表.xlsx 中的定义，以下事件已实现：

事件名	实现状态	说明
$MPLaunch	✅	小程序启动事件
$MPShow	✅	小程序显示事件
$MPHide	✅	小程序隐藏事件
$SceneLoadStart	✅	场景开始加载事件
$SceneLoaded	✅	场景加载完成事件
$SceneUnloaded	✅	场景卸载事件
$CompleteSection	✅	完成关卡事件
$UpdateLevel	✅	等级提升事件
$TutorialStart	✅	新手引导开始事件
$TutorialFinish	✅	新手引导完成事件

注意事项

1. 开发环境测试：当前实现使用控制台输出，实际部署时需要替换为真实的数据上报接口
2. 数据格式：所有事件数据都包含设备信息、会话ID、用户ID等基础属性
3. 错误处理：埋点系统包含错误处理机制，不会影响游戏正常运行
4. 性能影响：埋点操作是异步的，不会阻塞游戏主线程

故障排除

常见问题：

1. 控制台没有埋点输出

   • 检查 Analytics.setEnabled(true) 是否被调用
   • 确认埋点管理器已正确初始化

2. 测试函数不存在

   • 确认 AnalyticsTestSimple.ts 已被正确加载
   • 检查 testAnalytics 全局对象是否存在

3. 事件属性不正确

   • 对照事件数据表检查属性名称和类型
   • 查看控制台输出的完整事件数据

如有其他问题，请检查浏览器控制台的错误信息。