DEVELOPER DOCUMENTATION
每个业务事件，都有明确归属
统一事件字段、交付确认和重试规则，让客户端与后台数据可以核对。
事件类型
| 事件 | 触发时机 | 业务字段 |
|---|---|---|
login | 游戏登录且 SDK 验证成功 | event_id |
active | 已登录玩家进入游戏或回到前台 | event_id |
role_create | 游戏确认角色创建成功 | event_id、server_id、role_id、role_name、level |
role_update | 进入角色或角色等级变化 | 同角色创建事件 |
区服和角色标识需保持稳定，角色名不能替代角色 ID。每个新业务事件生成新 event_id，同一事件重试复用原 ID 与内容。
持久化上报
sdk.setEventDeliveryListener(deliveryCallback);
sdk.enqueueEvent(loginEventId, "login",
null, null, null, 0, queuedCallback);
sdk.enqueueEvent(roleEventId, "role_update",
serverId, roleId, roleName, level, queuedCallback);
sdk.flushEvents();
sdk.managePendingEvents(false, countCallback);queued: true 只表示事件已在本地保存。收到 deliveryCallback 成功回调才代表服务端确认；最终统计以后台查询为准。必须先成功验证玩家会话。首次启动且尚未验证玩家时不能离线入队；已验证玩家在网络中断或会话过期后可继续入队。
补传与错误处理
| 结果 | 处理方式 |
|---|---|
| 网络错误、408、429、5xx | 保留事件，自动退避重试，间隔从 2 秒起、最多 5 分钟。 |
http_401 | 保留事件，等待重新获取会话并登录。 |
| 其他永久 4xx | 停止重试，保留拒绝记录供排查，不反复生成新 ID。 |
queue_write_failed | 检查容量、存储或同 ID 不同内容冲突；此次入队未成功。 |
每条事件最多 8 KB，应用最多保留 500 条待发及拒绝记录。队列按 API、游戏、渠道、包和玩家隔离，令牌只保存在内存中。
应用被杀后不会继续后台发送。下次启动并验证同一玩家后恢复队列。当前队列由单进程、单 SDK 实例持有。
统计口径
报表按北京时间的服务端接收日期统计，跨天补传归入收到当天。新增玩家不是安装或注册量；跨包玩家分别计数，不可直接相加作为独立用户总量。客户端事件不作为结算依据。