埋点接入

ReportManager 负责 Unity 小游戏的业务埋点。

本文按“接入准备 → 最小闭环 → API 参考 → 验收”的顺序说明。首次接入建议先完成玩法、模式、关卡的最小闭环，再按埋点表增加道具、活动等扩展事件。

接入前提

埋点应在 SDK 初始化完成后调用。尚未完成 SDK 导入时，请先阅读 Unity SDK 快速接入。

1. 适用范围与统一约定

1.1 能力范围

能力	接入方式
业务入口	`ReportManager.I`
玩法、模式、关卡	使用 SDK 状态机接口
道具、活动、养成等业务事件	使用预定义强类型数据类
激励视频	`VideoButton` 自动埋点，或自定义入口手动接入
自定义事件	`OnNewEvent` 或底层 `Sdk.OnNewEvent`

1.2 核心概念

所有项目统一使用以下层级。名称一旦与数据/运营同学确认，版本内不要随意变更。

层级	事件字段	示例	Unity 接口
玩法	`game_name`	`KXPYP`	SDK 配置并由 `StartMineGame()` 启动
模式	`mode_name`	`normal`	`StartGameModel("normal")`
关卡	`mode_level`	`50`	`NewReportGameStart(game_start)`

没有模式或关卡怎么办

没有模式：与对接人确认后统一使用 wujin。
退出当前模式：必须传大小写完全一致的特殊值 None。
没有关卡：mode_level 统一传 0。
没有分数：保持对应可空字段为 null，不要为了凑字段伪造 0 或 1。

1.3 三个核心字段怎么传

三个字段的来源不同：game_name 来自项目配置，mode_name 来自模式接口，mode_level 来自每局的关卡数据。

字段	完整传递规则
`game_name`	怎么传：在项目全局配置中填写游戏名，启动流程会通过 `InitSDK(..., gameName, ...)` 注入。什么时候传：SDK 初始化前配置好，运行中不要反复修改。后续行为：`GetNewReportJsonData<T>()` 会自动写入每个事件对象。
`mode_name`	怎么传：调用 `ReportManager.I.StartGameModel(modeName)`。什么时候传：玩家进入或切换模式时，必须早于关卡开始。后续行为：SDK 保存到 `ZMYSDKManager.I.ModeName`，关卡、视频及预定义事件会自动继承。
`mode_level`	怎么传：给 `game_start.mode_level` 赋值，并上报该 `game_start` 对象。什么时候传：每一局、每一关开始时；重新开始也必须重新赋值并上报。后续行为：SDK 会保存当前关卡编号；其他手动关卡事件仍建议显式赋值。

小游戏工程的默认启动链路会把 IXYXGlobalConfig.Instance.Get_GameName() 传给 ZMYSDKManager.I.InitSDK(...)。因此业务埋点代码不应逐条设置 game_name。

csharp

// SDK 初始化完成后：这里只启动玩法事件，不是在这里传 game_name
ReportManager.I.StartMineGame();

// 玩家进入模式时设置 mode_name
ReportManager.I.StartGameModel("normal");

// 每一局开始时设置 mode_level
game_start start = ReportManager.I.GetNewReportJsonData<game_start>();
start.mode_level = 50;
ReportManager.I.NewReportGameStart(start);

// 后续关卡事件会继承当前 game_name / mode_name。
// mode_level 显式赋值，保证事件字段完整。
game_complete complete = ReportManager.I.GetNewReportJsonData<game_complete>();
complete.mode_level = 50;
complete.mode_level_score = 999;
ReportManager.I.NewReportGameComplete(complete);

不要手动覆盖 SDK 状态字段

不要给事件对象手动写 game_name、mode_name 或 _duration。
game_start.mode_level 必须显式赋值，否则 NewReportGameStart 读取 .Value 时会抛出异常。
进度、暂停、结果等手动关卡事件建议继续填写同一个 mode_level，避免事件脱离具体关卡。

场景切换时按以下规则更新：

同一模式进入下一关：创建新的 game_start，写入新关卡编号。
同一关重新开始：再次上报 game_start，写入同一关卡编号。
切换模式：调用 StartGameModel(newMode)，再开始新关卡。
退出模式：调用 StartGameModel("None")。

1.4 命名空间与调用原则

csharp

using ZMYSDK.Report;
using ZMYSDK.Report.JsonProperties;

事件名、玩法名、模式名和视频点名称必须与埋点表完全一致，区分大小写。
同一局的标准顺序是：启动玩法 → 进入模式 → 开始关卡 → 过程事件 → 结果事件。
事件数据类禁止直接 new。源码已将构造函数标记为编译期错误，必须使用 GetNewReportJsonData<T>()。
每次调用 GetNewReportJsonData<T>() 默认会清空该类型上一次的属性，避免数据串到下一条事件。
_duration、mode_name 和定时时长事件由封装层维护，业务代码不要覆盖；mode_level 建议在每条关卡事件上显式赋值，保证每条关卡事件字段完整。
优先使用强类型预定义事件；仅在埋点表没有对应数据类时使用原始自定义事件。

2. 最小可用接入

下面示例覆盖单玩法、单模式和多关卡项目。代码应在 SDK 初始化成功后执行。

csharp

using ZMYSDK.Report;
using ZMYSDK.Report.JsonProperties;

public class StatisticsExample
{
    private int currentLevel = 50;

    public void EnterGame()
    {
        // 每次 SDK 生命周期调用一次，启动玩法和玩法时长上报
        ReportManager.I.StartMineGame();

        // 进入模式
        ReportManager.I.StartGameModel("normal");
    }

    public void StartLevel()
    {
        game_start data = ReportManager.I.GetNewReportJsonData<game_start>();
        data.mode_level = currentLevel; // 必填；封装内部会读取 Value
        ReportManager.I.NewReportGameStart(data);
    }

    public void CompleteLevel(int score)
    {
        game_complete data = ReportManager.I.GetNewReportJsonData<game_complete>();
        data.mode_level = currentLevel;
        data.mode_level_score = score;
        ReportManager.I.NewReportGameComplete(data);
    }

    public void BackToHome()
    {
        // 停止当前模式时长上报
        ReportManager.I.StartGameModel("None");
    }
}

mode_level 是关卡开始的必填字段

NewReportGameStart 的实现会读取 game_start.mode_level.Value。未赋值会在运行时抛出异常，不能依赖默认值。

3. 玩法与模式

3.1 启动玩法

csharp

ReportManager.I.StartMineGame();

该接口会：

首次产生一次 start_first；
本次产生一次 start；
启动玩法计时器，后续自动产生 gaming。

每次 SDK 生命周期只调用一次。重复调用会重新创建玩法计时器并重复产生 start。

3.2 进入、切换和退出模式

csharp

// 进入普通模式
ReportManager.I.StartGameModel("normal");

// 切换到每日挑战；SDK 会先停止上一模式计时
ReportManager.I.StartGameModel("daily");

// 退出当前模式
ReportManager.I.StartGameModel("None");

StartGameModel 会产生 mode_start 并自动维护 mode_gaming 时长事件。传入空字符串会被拒绝；None 是退出标记，不是普通业务模式名。

4. 关卡状态机

4.1 标准顺序

text

game_start
   ├─ game_pause ── game_continue ──┐
   ├─ game_quit  ── game_continue ──┤
   ├─ game_fail  ── game_revive  ───┤
   ├─ game_progress / game_foul     │
   └─ game_complete / game_draw / game_skip

状态约束：

game_progress、game_foul、game_pause、game_fail 等过程事件必须在 game_start 之后。
game_continue 只能跟在 game_pause 或 game_quit 之后。
game_revive 只能跟在 game_fail 之后。
game_complete、game_draw 和 game_skip 会结束当前关卡。
中途离开使用 game_quit。它表示关卡挂起，不等同于最终失败；恢复时使用 game_continue。

4.2 开始关卡

csharp

game_start data = ReportManager.I.GetNewReportJsonData<game_start>();
data.mode_level = 50;
data.mode_difficulty = 2;       // 可选，以埋点表为准
data.mode_level_skin = "forest";
ReportManager.I.NewReportGameStart(data);

调用后 SDK 会保存当前关卡编号、开始关卡计时，并产生 game_start。进行中会自动产生 level_gaming。

4.3 进度与犯规

csharp

game_progress progress = ReportManager.I.GetNewReportJsonData<game_progress>();
progress.mode_level = 50;
progress.mode_level_progress = 80;
progress.mode_level_score = 900;
ReportManager.I.NewReportGameProgress(progress);

game_foul foul = ReportManager.I.GetNewReportJsonData<game_foul>();
foul.mode_level = 50;
foul.activity_name = "invalid_operation";
ReportManager.I.NewReportGameFoul(foul);

过程字段的业务含义必须在埋点表中明确，不要在不同场景复用同一个字段表达不同含义。

4.4 暂停与继续

csharp

game_pause pause = ReportManager.I.GetNewReportJsonData<game_pause>();
pause.mode_level = 50;
pause.mode_level_score = 600;
ReportManager.I.NewReportGamePause(pause);

game_continue resume = ReportManager.I.GetNewReportJsonData<game_continue>();
resume.mode_level = 50;
ReportManager.I.NewReportGameContinue(resume);

用户主动暂停时使用这组接口。SDK 也会监听 Unity 暂停和前后台事件；不要在同一生命周期回调里额外重复上报。

4.5 中途离开与恢复

csharp

game_quit quit = ReportManager.I.GetNewReportJsonData<game_quit>();
quit.mode_level = 50;
quit.mode_level_score = 600;
ReportManager.I.NewReportGameQuit(quit);

// 玩家稍后恢复挂起的关卡
game_continue resume = ReportManager.I.GetNewReportJsonData<game_continue>();
resume.mode_level = 50;
ReportManager.I.NewReportGameContinue(resume);

game_quit 不会把关卡标记为最终结束。玩家明确放弃且不会恢复时，最终事件口径应先与数据/运营同学确认，不要擅自用 game_fail 替代。

4.6 失败与复活

csharp

game_fail fail = ReportManager.I.GetNewReportJsonData<game_fail>();
fail.mode_level = 50;
fail.mode_level_score = 600;
ReportManager.I.NewReportGameFail(fail);

game_revive revive = ReportManager.I.GetNewReportJsonData<game_revive>();
revive.mode_level = 50;
ReportManager.I.NewReportGameRevive(revive);

如果失败后不复活，直接进入下一局时重新调用 NewReportGameStart。

4.7 成功、平局与跳关

csharp

game_complete complete = ReportManager.I.GetNewReportJsonData<game_complete>();
complete.mode_level = 50;
complete.mode_level_score = 999;
ReportManager.I.NewReportGameComplete(complete);

// 平局
game_draw draw = ReportManager.I.GetNewReportJsonData<game_draw>();
draw.mode_level = 50;
ReportManager.I.NewReportGameDraw(draw);

// 跳过关卡
game_skip skip = ReportManager.I.GetNewReportJsonData<game_skip>();
skip.mode_level = 50;
ReportManager.I.NewReportGameSkip(skip);

同一局只选择一个最终结果，不要同时上报成功、平局和跳关。

4.8 关卡接口速查

事件	数据类型	上报方法	状态变化
`game_start`	`game_start`	`NewReportGameStart`	开始/重开关卡
`game_progress`	`game_progress`	`NewReportGameProgress`	保持进行中
`game_foul`	`game_foul`	`NewReportGameFoul`	保持进行中
`game_pause`	`game_pause`	`NewReportGamePause`	进行中 → 暂停
`game_continue`	`game_continue`	`NewReportGameContinue`	暂停/挂起 → 进行中
`game_quit`	`game_quit`	`NewReportGameQuit`	进行中 → 挂起
`game_fail`	`game_fail`	`NewReportGameFail`	进行中 → 可复活
`game_revive`	`game_revive`	`NewReportGameRevive`	可复活 → 进行中
`game_complete`	`game_complete`	`NewReportGameComplete`	结束
`game_draw`	`game_draw`	`NewReportGameDraw`	结束
`game_skip`	`game_skip`	`NewReportGameSkip`	结束

5. 激励视频

5.1 使用 `VideoButton`

SDK 的 VideoButton 组件会自动上报以下事件：

事件	时机
`video_unable`	视频功能不可用
`video_noAds`	功能可用但没有广告
`video_show`	视频入口可展示
`video_click`	点击视频入口
`video_play`	开始播放
`video_success`	完整播放并成功发奖
`video_fail`	中途退出或播放失败

使用该组件时必须正确配置 video_name。原有 video_param1、video_param2 继续兼容；需要携带更多统计字段时，可以在业务代码中设置 VideoExtraProperties：

csharp

using System.Collections.Generic;

videoButton.VideoExtraProperties = new Dictionary<string, object>
{
    { "video_scene", "level_fail" },
    { "reward_count", 3 },
    { "is_first", true },
};

这些动态属性会自动附加到表格中的全部七个视频事件。VideoExtraProperties 保存的是传入字典的引用；一次播放期间不要继续修改或复用该字典承载其他视频点的数据。使用 VideoButton 时，不要在业务回调中重复调用 NewReportVideo*。

5.2 自定义广告入口

没有使用 VideoButton 时，按真实生命周期调用对应接口：

csharp

using System.Collections.Generic;

var extra = new Dictionary<string, object>
{
    { "video_scene", "level_fail" },
    { "reward_count", 3 },
    { "is_first", true },
};

ReportManager.I.NewReportVideoShow("double_reward", extra);
ReportManager.I.NewReportVideoClick("double_reward", extra);
ReportManager.I.NewReportVideoPlay("double_reward", extra);
ReportManager.I.NewReportVideoSuccess("double_reward", extra);

video_show、video_click、video_play、video_success 和 video_fail 支持以下三种形式：

csharp

// 只使用原有 video_param1 / video_param2
ReportManager.I.NewReportVideoClick("double_reward", "param1", "param2");

// 只使用动态属性
ReportManager.I.NewReportVideoClick("double_reward", extra);

// 同时使用原有参数和动态属性
ReportManager.I.NewReportVideoClick(
    "double_reward",
    "param1",
    "param2",
    extra
);

video_unable 和 video_noAds 原本没有 video_param1/2 参数，分别支持“只传 video_name”和“video_name + extra”两种形式：

csharp

ReportManager.I.NewReportVideoUnable("double_reward", extra);
ReportManager.I.NewReportVideoNoAds("double_reward", extra);

动态属性适用于 video_unable、video_noAds、video_show、video_click、video_play、video_success 和 video_fail。属性值支持字符串、数值、布尔值、集合以及 LitJson 可以序列化的对象。

动态属性规则

video_name 必须与埋点表中的视频点名称一致，动态属性名也必须先在统计后台配置。
空属性名会被忽略。
同名动态属性会覆盖 SDK 自动生成的基础属性，不要传 game_name、mode_name、mode_level 或 video_name。
动态属性序列化失败时，SDK 会打印错误日志，并回退为只上报基础视频属性。

6. 预定义业务事件

SDK 为道具、活动、养成、UI、资源、登录等事件生成了强类型数据类和对应方法，统一调用方式如下：

csharp

item_get data = ReportManager.I.GetNewReportJsonData<item_get>();
data.item_id = 1001;
data.item_type1 = 0;     // 类型值以埋点表为准
data.item_number = 100;  // 本次变化量
data.item_count = 200;   // 变化后余额
data.item_game = "KXPYP";

ReportManager.I.NewReport_item_get(data);

命名规则：

text

数据类型：<event_name>
上报方法：ReportManager.I.NewReport_<event_name>(data)
最终事件：<event_name>

字段很多不代表全部都要赋值。只填写埋点表要求的业务字段；game_name 由 GetNewReportJsonData 自动写入。

6.1 基础事件目录

当前 Unity 小游戏 SDK 提供以下基础业务事件。

展开公共事件列表

分类	事件名
游戏与关卡	`game_share`, `game_evaluate`, `game_ui_sort`, `game_stuck`, `game_unlock`, `game_loadstart`, `game_loadover`, `game_loadfail`, `game_click`, `game_round_start`, `game_round_complete`, `game_behavior`, `game_difficulty_adjust`, `dealing_card`
物品与道具	`item_get`, `item_cost`, `item_use`, `tools_unlock`, `tools_fail`, `tools_use`
活动	`activity_warmup`, `activity_unlock`, `activity_enter`, `activity_start`, `activity_fail`, `activity_success`, `activity_reward`, `activity_reset`, `activity_giveup`, `activity_complete`, `activity_register`
实时活动	`live_activity_start`, `live_activity_click`, `live_activity_update`, `live_activity_complete`
养成	`develop_trail`, `develop_unlock`, `develop_use`, `develop_levelup`
UI	`element_show`, `element_use`, `element_result`, `popup_show`, `popup_redirect`
资源	`res_downloadstart`, `res_downloadover`, `res_downloadfail`, `res_read_fail`
邮件	`mail_check`, `mail_delete`, `mail_receive`
插屏广告	`insert_all`, `insert_nonet`, `insert_select`, `insert_show`, `inters_click`, `insert_close`, `insert_show_level`
登录与网络	`tcp_delay`, `login_register`, `login_bind`, `login_request`, `login_success`, `login_fail`, `login_enterfsm`, `login_leavefsm`, `login_sdk`, `login_startserver`, `login_server`, `login_startsyndata`, `login_SynDatachangeuser`, `login_focusupdate`, `login_focusupload`, `login_synData_needUpdateData`, `login_syndata_needuploaddata`, `login_syndata_actionsuccess`, `login_syndata_fsmsuccess`, `login_nethttperror`, `login_download_request`, `login_download_success`, `login_download_fail`, `login_upload_request`, `login_upload_success`, `login_upload_fail`
用户与支付	`user_level_update`, `pay_success_custom`, `game_pay_event`, `resume_request`, `resume_success`
其他扩展	`unity_online_config_params`, `video_lock_park`, `use_prop_refresh`, `use_prop_sort`, `use_prop_remove`, `ttfeed_entry`, `ttfeed_subscribe`, `ttfeed_game_ready`, `ttfeed_reportev`

6.2 扩展事件

当前版本还提供以下小游戏业务扩展事件：

分类	事件名
游戏与挑战	`game_replay`, `challenge_competition`
物品	`item_buy`
养成	`develop_enter`, `develop_start`, `develop_action`, `develop_speedup`, `develop_complete`, `develop_destroy`
视频弹窗	`video_refuse`, `video_popup_success`, `video_popup_fail`
登录与启动	`login_userloginout`, `minigame_launch_progress`, `loading_event`
用户风控	`user_tag_update`, `user_cheat`

调用前应以当前工程中 ReportDefineByTools.cs 和 NewReportManagerByTools.cs 实际生成的类型为准。

SDK 维护侧：同步线上事件定义

ReportDefineByTools.cs 和 NewReportManagerByTools.cs 均由工具生成，不要直接编辑。维护 SDK 源码时，在 Unity 菜单中执行 Tool/导出上报脚本：

从统计后台获取事件、属性和关联关系。
更新 Assets/Editor/Report 下的事件、属性及关联配置。
重新生成 Assets/ZMYSDK/Runtime/Report/ReportDefineByTools.cs 和 NewReportManagerByTools.cs。

线上 number 类型生成可空 int 字段；array_map 类型生成 object 字段，并按 JSON 对象或数组序列化。同步完成后必须编译 SDK，并核对新增事件、字段类型及关联关系。普通业务接入项目不需要执行此流程。

7. 通用与自定义上报

7.1 直接上报预定义数据类

若存在数据类但没有便捷包装方法，可以直接使用 OnNewEvent：

csharp

item_get data = ReportManager.I.GetNewReportJsonData<item_get>();
data.item_id = 1001;
data.item_number = 50;

ReportManager.I.OnNewEvent(data);

有 NewReport_<event> 方法时优先调用包装方法，便于统一校验和后续扩展。

7.2 原始自定义事件

只有埋点表没有预定义数据类时才使用底层接口：

csharp

using System.Collections.Generic;
using LitJson;
using ZMYSDK;

var properties = new Dictionary<string, object>
{
    { "page_name", "shop" },
    { "button_name", "buy" },
    { "product_id", "coin_1" },
};

ZMYSDKManager.I.Sdk.OnNewEvent(
    "custom_button_click",
    JsonMapper.ToJson(properties)
);

大小写

管理器属性的源码名称是 Sdk，不是旧文档中的 SDK。事件名和 JSON 属性名同样区分大小写。

不要用字符串拼接构造 JSON；属性值必须可序列化，且不得包含手机号、身份证、Token 等敏感信息。

8. 联调与验收

8.1 控制台日志

每次强类型事件上报都会打印类似日志：

text

上报：OnNewEvent:key[game_start]--JsonProperties[{...}]

其中：

key 是最终事件名，通常等于数据类名；
JsonProperties 是最终属性 JSON。

日志出现只代表客户端已发起上报。提测前仍需在埋点后台确认事件已入库且字段类型正确。

8.2 推荐验收路径

至少完整跑通以下用例：

冷启动后调用一次 StartMineGame。
进入模式并开始一关。
暂停后继续。
失败后复活，或直接失败后开始下一局。
重新开始一关并成功结算。
中途退出一关，再恢复该关。
获取和消耗一次道具。
使用 VideoButton 完整播放一次激励视频。

重点核对 event key、game_name、mode_name、mode_level、分数、数量以及自定义属性是否与埋点表一致。

8.3 常见问题

现象	排查项
`game_start` 抛出空值异常	是否为 `game_start.mode_level` 赋值
提示“关卡未开始”	是否在过程/结果事件前调用了 `NewReportGameStart`
`game_continue` 被拒绝	前一状态是否为 `game_pause` 或 `game_quit`
`game_revive` 被拒绝	是否紧跟在 `game_fail` 后调用
模式一直是 `None`	是否在开始关卡前调用了 `StartGameModel("业务模式名")`
属性串到下一条事件	是否绕过 `GetNewReportJsonData<T>()` 或传入了 `ClearProperties=false`
视频事件重复	是否使用 `VideoButton` 的同时又手动调用 `NewReportVideo*`
找不到某个数据类	当前 SDK 版本是否生成了对应事件类型和包装方法
只有日志、后台无数据	SDK 是否初始化完成；事件/属性是否已在后台配置；网络是否可用

8.4 提测清单

[ ] 玩法、模式、关卡名称已与埋点表确认。
[ ] StartMineGame 在每次 SDK 生命周期只调用一次。
[ ] 每局 game_start.mode_level 已显式赋值。
[ ] 每局最终结果事件唯一，挂起退出没有误写成失败。
[ ] 没有手动重复上报 SDK 自动产生的时长和 VideoButton 事件。
[ ] 预定义数据对象均通过 GetNewReportJsonData<T>() 获取。
[ ] 自定义属性已在后台配置，且不含敏感信息。
[ ] 已在目标小游戏平台完成至少一次真机/真环境验证。

埋点接入 ​

1. 适用范围与统一约定 ​

1.1 能力范围 ​

1.2 核心概念 ​

1.3 三个核心字段怎么传 ​

1.4 命名空间与调用原则 ​

2. 最小可用接入 ​

3. 玩法与模式 ​

3.1 启动玩法 ​

3.2 进入、切换和退出模式 ​

4. 关卡状态机 ​

4.1 标准顺序 ​

4.2 开始关卡 ​

4.3 进度与犯规 ​

4.4 暂停与继续 ​

4.5 中途离开与恢复 ​

4.6 失败与复活 ​

4.7 成功、平局与跳关 ​

4.8 关卡接口速查 ​

5. 激励视频 ​

5.1 使用 VideoButton ​

5.2 自定义广告入口 ​

6. 预定义业务事件 ​

6.1 基础事件目录 ​

6.2 扩展事件 ​

7. 通用与自定义上报 ​

7.1 直接上报预定义数据类 ​

7.2 原始自定义事件 ​

8. 联调与验收 ​

8.1 控制台日志 ​

8.2 推荐验收路径 ​

8.3 常见问题 ​

8.4 提测清单 ​

埋点接入

1. 适用范围与统一约定

1.1 能力范围

1.2 核心概念

1.3 三个核心字段怎么传

1.4 命名空间与调用原则

2. 最小可用接入

3. 玩法与模式

3.1 启动玩法

3.2 进入、切换和退出模式

4. 关卡状态机

4.1 标准顺序

4.2 开始关卡

4.3 进度与犯规

4.4 暂停与继续

4.5 中途离开与恢复

4.6 失败与复活

4.7 成功、平局与跳关

4.8 关卡接口速查

5. 激励视频

5.1 使用 `VideoButton`

5.2 自定义广告入口

6. 预定义业务事件

6.1 基础事件目录

6.2 扩展事件

7. 通用与自定义上报

7.1 直接上报预定义数据类

7.2 原始自定义事件

8. 联调与验收

8.1 控制台日志

8.2 推荐验收路径

8.3 常见问题

8.4 提测清单