SDK 接入文档

Appearance

Flutter SDK 更新日志 ​

v1.5.3 · 2026-09-29 ​

主包与兼容包功能版本一致，均为 1.5.3；指纹规则版本 fp_version 仍为 4.0.0。公共 API、事件协议与签名规则相对 1.5.2 无变更。

修复 ​

  • Safari 电量 API：navigator.getBattery() 不可用时，电量监听异常不再中断初始化，避免设备指纹为空。
  • 监听与采集隔离：网络、电量、运行态监听的同步 / 异步错误独立隔离；浏览器属性访问失败不会丢弃其他已成功采集字段。
  • 可选异步超时降级：单项可选异步信息默认 2 秒超时，环境采集总保护 3 秒；设备 ID、启动快照、指纹与激活时间读取不再无限等待。此限制不是整个 init() 的总时限。

升级须知 ​

  1. 替换为 1.5.3 源码包后更新 path 依赖，执行 flutter pub get；iOS/macOS 按需 pod install。
  2. 从 1.5.2 升级无需修改调用代码。从 1.5.1 或更早升级仍须遵循 1.5.2 的 PostEvent.postCreateTime 改名要求。
  3. Web / PWA 宿主需重新构建发布，确认页面实际加载新 JS，初始化后 sdk_version 为 1.5.3。已持久化指纹无需清理。
  4. 建议在 iOS Safari 上 await init(...) 完成后检查 device_fingerprint / sdk_version / fp_version。

文档补充（2026-10-17） ​

协议取值扩展，不升级 SDK、不新增预定义常量。白名单仍用原事件名。

  • 视频播放失败：video_event 的 videoBehavior 传 VideoEventEnum('video_failed', '播放失败')，输出 video_behavior_key / video_behavior_name。
  • 剧集播放失败：drama_event 的 playBehavior 传 DramaPlayBehaviorEnum('ep_failed', '播放失败')，输出 play_behavior_key / play_behavior_name。
  • 页面 Observer：pageObserver（自动上报 app_page_view）与 sessionObserver（业务手动上报，只采集停留）必须二选一，供 app_session_summary.page_stay_list 使用。

分发说明 ​

  • 主包（flutter-sdk-v1.5.3.zip）：常规 Flutter 宿主（推荐）
  • 兼容包（flutter-sdk-v1.5.3-flutter305-gradle6-agp4-compat.zip）：Flutter 3.0.5 + Gradle 6.x + AGP 4.x 老旧 Android 工程

两包 SDK 版本与事件 API 相同，请按宿主构建环境选型，不要混用。

v1.5.2 · 2026-09-19 ​

主包与兼容包功能版本一致，均为 1.5.2；指纹规则版本 fp_version 仍为 4.0.0。

变更 ​

  • PostEvent Dart 参数改名：createTime 改为 postCreateTime，与协议字段 post_create_time 对齐。这是源码不兼容改名：从 1.5.1 升级的宿主必须把 PostEvent(createTime: ...) 改成 PostEvent(postCreateTime: ...)，旧调用会编译失败。
  • JSON 协议不变：toJson() 仍只输出 post_create_time，fromJson() 仍只读 post_create_time，类型仍为 10 位秒级 int。后台接收 / 存储 / 统计无需迁移。
  • 运行时版本同步：包版本与 SdkContext.kSdkVersion 更新为 1.5.2；普通包与兼容包同步交付。

升级须知 ​

  1. 替换为 1.5.2 源码包后更新 path 依赖，执行 flutter pub get；iOS/macOS 按需 pod install。
  2. 全局查找 PostEvent 构造，将 createTime: 替换为 postCreateTime:。
  3. 手写 payload 与后台映射继续用 post_create_time，不要改成 Dart 风格的 postCreateTime。
  4. 其余事件 API、签名与指纹规则不变；已持久化 v4 指纹无需清理。

分发说明 ​

  • 主包（flutter-sdk-v1.5.2.zip）：常规 Flutter 宿主（推荐）
  • 兼容包（flutter-sdk-v1.5.2-flutter305-gradle6-agp4-compat.zip）：Flutter 3.0.5 + Gradle 6.x + AGP 4.x 老旧 Android 工程

两包 SDK 版本与事件 API 相同，请按宿主构建环境选型，不要混用。

v1.5.1 · 2026-09-18 ​

主包与兼容包功能版本一致，均为 1.5.1；指纹规则版本 fp_version 仍为 4.0.0。

变更 ​

  • 帖子创建时间协议字段：payload 由 create_time 改为 post_create_time（仍为 10 位秒级 int）。Dart 构造参数 createTime 保持兼容；toJson() 只输出新字段，fromJson() 按 post_create_time 读取。后台与手写 JSON 需同步改名。
  • 运行时版本同步：包版本与 SdkContext.kSdkVersion 更新为 1.5.1；普通包与兼容包同步交付。

约定说明 ​

  • 非空 uid：长度须 ≥ 4（字符），由宿主保证；未登录可传空。本版不新增 SDK 最小长度校验。
  • 小说 page_no：仅有声小说允许为 0，普通小说必须 ≥ 1。本版仅补充文档与注释；当前校验器仍会移除 page_no = 0，未实现零页码端到端上报。

升级须知 ​

  1. 替换为 1.5.1 源码包后更新 path 依赖，执行 flutter pub get；iOS/macOS 按需 pod install。
  2. 后台接收 / 存储 / 统计改用 post_create_time；混合版本滚动升级时由后台自行兼容旧 create_time。
  3. 已有 Dart PostEvent(createTime: ...) 调用无需改参数名；指纹与签名规则不变，无需清理已有指纹。

分发说明 ​

  • 主包（flutter-sdk-v1.5.1.zip）：常规 Flutter 宿主（推荐）
  • 兼容包（flutter-sdk-v1.5.1-flutter305-gradle6-agp4-compat.zip）：Flutter 3.0.5 + Gradle 6.x + AGP 4.x 老旧 Android 工程

两包 SDK 版本与事件 API 相同，请按宿主构建环境选型，不要混用。

v1.5.0 · 2026-09-17 ​

主包与兼容包功能版本一致，均为 1.5.0；指纹规则版本 fp_version 仍为 4.0.0。本轮基于已交付的 1.4.9 工作版本同步 SDK 版本与交付归档，无进一步功能改动；事件名、字段名与参数类型保持兼容。

变更 ​

  • 运行时版本同步：包版本与 SdkContext.kSdkVersion 更新为 1.5.0；普通包与兼容包同步交付。
  • 指纹沿用：已在 1.4.9 持久化的 v4 指纹继续复用，无新增指纹迁移；初始化、事件及签名协议不变。

沿用能力（前轮 1.4.9） ​

  • DramaPlayBehaviorEnum：EP_COMPLETE（ep_complete / 播放完成）、EP_SHARE（ep_share / 分享）。
  • ClickItemTypeEnum：POST（post / 帖子）、SHORT_DRAMA（short_drama / 短剧）。
  • KeywordSearchEvent.searchContentType：支持 post、short_drama；search_id 为可视结果 ID 列表（英文逗号分隔）。
  • 设备指纹持久化：fp_version 4.0.0；首次计算去掉 language / timezone；重复 init() 从持久化恢复指纹。

升级须知 ​

  1. 替换为 1.5.0 源码包后更新 path 依赖，执行 flutter pub get；iOS/macOS 按需 pod install。
  2. 从 1.4.9 升级仅变更 sdk_version；已持久化指纹无需清理。从更早版本升级时，首次初始化仍会生成并保存 v4 指纹。
  3. 服务端继续接受 fp_version = 4.0.0，以及 drama_event / keyword_search / keyword_click 的既有扩展取值。

分发说明 ​

  • 主包（flutter-sdk-v1.5.0.zip）：常规 Flutter 宿主（推荐）
  • 兼容包（flutter-sdk-v1.5.0-flutter305-gradle6-agp4-compat.zip）：Flutter 3.0.5 + Gradle 6.x + AGP 4.x 老旧 Android 工程

两包 SDK 版本与事件 API 相同，请按宿主构建环境选型，不要混用。

v1.4.9 · 2026-09-17 ​

主包与兼容包功能版本一致，均为 1.4.9；指纹规则版本 fp_version 为 4.0.0。事件名、字段名与参数类型保持兼容；release_revision = 20260917 替代 2026-09-16 同版本包，请按交付日期与 SHA-256 更换 ZIP。

新增（2026-09-17） ​

  • DramaPlayBehaviorEnum：新增 EP_COMPLETE（ep_complete / 播放完成）、EP_SHARE（ep_share / 分享），写入既有 play_behavior_key / play_behavior_name。
  • ClickItemTypeEnum：新增 POST（post / 帖子）、SHORT_DRAMA（short_drama / 短剧），KeywordClickEvent 同时序列化 key / name。
  • KeywordSearchEvent.searchContentType：String 取值补齐 post、short_drama；search_content_type / search_trace_id / search_id 默认均为 ''。search_id 为可视范围内的搜索结果 ID（多个英文逗号分隔），不是搜索会话 ID。

变更（2026-09-16） ​

  • 设备指纹持久化：fp_version 升级为 4.0.0。Android / iOS / Web 首次指纹计算去掉 language、timezone（这两个字段仍正常采集上报）。首次生成 SHA-256 指纹并确认持久化成功后用于事件；之后每次 init() 读取已保存值，设备参数变化不会重新计算。清除应用数据或浏览器站点存储后才重新生成。
  • 旧版迁移：旧 v3 指纹没有独立持久化记录，升级后首次初始化生成并保存 v4 指纹后持续复用。旧兼容入口的 UUID 缓存不作为 v4 指纹使用。
  • 运行时版本同步：包版本与 SdkContext.kSdkVersion 均为 1.4.9。

修复 ​

  • 重复初始化指纹丢失：再次调用 init() 时从持久化恢复指纹，避免因跳过重复 sdk_init 而使后续事件指纹为空。

升级须知 ​

  1. 请替换为 2026-09-17 交付包；更新 path 依赖后执行 flutter pub get；iOS/macOS 按需 pod install。
  2. 服务端应接受 fp_version = 4.0.0；指纹不再要求与每次启动快照重算结果相同。事件签名规则不变。
  3. 后台需接受 drama_event 的 ep_complete / ep_share，以及 keyword_search / keyword_click 的 post / short_drama；未新增事件名。播放完成、分享、搜索与点击均由宿主在业务回调中调用 track()。

分发说明 ​

  • 主包（flutter-sdk-v1.4.9.zip）：常规 Flutter 宿主（推荐）
  • 兼容包（flutter-sdk-v1.4.9-flutter305-gradle6-agp4-compat.zip）：Flutter 3.0.5 + Gradle 6.x + AGP 4.x 老旧 Android 工程

两包 SDK 版本与事件 API 相同，请按宿主构建环境选型，不要混用。

v1.4.8 · 2026-09-07 ​

主包上报版本为 1.4.8（pubspec.yaml / SdkContext.kSdkVersion 已对齐）。本批交付更新主包；兼容包仍为既有构建，不含本次帖子 / 剧集能力。

新增 ​

  • 帖子分析日志（P1）：新增客户端 PostEvent、PostContentTypeEnum、PostEventEnum，支持图文帖 post 与视频帖 video_post 的展示事件。
  • 剧集分析日志：新增客户端 DramaEvent、DramaStatusChangeEvent 及 DramaContentTypeEnum / DramaPlayBehaviorEnum / DramaBehaviorEnum，覆盖单集展示播放与自动播放、上一集、下一集、切换剧集、解锁。
  • 服务端事件登记：登记 post_like、post_comment、post_collect、post_unlock、drama_like、drama_comment、drama_collect、drama_purchase（服务端来源，排除客户端签名）；drama_status_change 按客户端事件处理。

变更 ​

  • VideoEvent 字段扩展：新增 postId（post_id）、整数 playSpeed（play_speed，默认 100）、VideoContentTypeEnum.postVideo（post_video）。仅帖子视频携带非空 post_id，否则丢弃。
  • 字段默认值与校验：帖子 / 剧集分类默认 default /「默认分类」，标签默认 default /「默认标签」；补齐 ID、标题、行为、集数与时长校验。
  • 依赖兼容范围放宽：package_info_plus <9.0.0，connectivity_plus <7.0.0，screen_brightness >=0.2.2+1 <2.0.0。
  • iOS 屏幕状态保守降级：无法可靠取得初始状态时 is_screen_on 从 -1 起，仅在收到系统事件后更新。

升级须知 ​

  1. 启用客户端 eventList 白名单时加入 post_event、drama_event、drama_status_change。
  2. 视频帖展示用 PostEvent（video_post）；播放等操作用 VideoEvent（post_video）并传入非空 postId。
  3. 更新依赖后执行 flutter pub get；iOS/macOS 同步 pod install。

分发说明 ​

  • 主包（flutter-sdk-v1.4.8.zip）：Flutter 3.0.5 ~ 3.38.3，含本次全部能力（推荐）
  • 兼容包（flutter-sdk-v1.4.8-flutter305-gradle6-agp4-compat.zip）：仍为既有兼容构建；需要帖子 / 剧集请用主包

v1.4.7 · 2026-08-10 ​

修复 ​

  • 网络类型枚举统一：sdk_init 与 network_state_change 仅上报 wifi、ethernet、cellular_2g、cellular_3g、cellular_4g、cellular_5g、unknown；不再上报不符合规范的 cellular 或 offline。断网时网络类型为 unknown，同时 is_online 保持为 0。
  • 移动网络代际识别：Android 与 iOS 原生端依据系统蜂窝网络信息识别 2G/3G/4G/5G；其他平台继续使用 connectivity_plus，其中 mobile 兼容映射为 cellular_2g。

变更 ​

  • 运行时版本字段同步：SdkContext.kSdkVersion 更新为 1.4.7，确保事件公共字段及 getParams() 返回的 sdk_version 与包版本一致。
  • Flutter 多版本适配分发包：
    • 主包（flutter-sdk-v1.4.7.zip）：适配 Flutter 3.0.5 ~ 3.38.3，推荐新工程与常规升级使用。
    • 兼容包（flutter-sdk-v1.4.7-flutter305-gradle6-agp4-compat.zip）：专为仍使用 Flutter 3.0.5 + Gradle 6.x + AGP 4.x 的老旧 Android 工程锁定依赖线。

说明 ​

主包与兼容包功能版本一致，均为 1.4.7；请按宿主构建环境选型，不要混用。

v1.4.6 · 2026-08-07 ​

新增 ​

  • 广告 SDK 曝光按 trace_id 去重：ad_impression_sdk 在同一 Session 内对相同 trace_id 仅接受一次；事件通过校验并成功入队后才写入去重记录，避免上报失败或被拦截时误丢后续曝光。新 Session 会自动清空该记录。

修复 ​

  • 应用终止窗口的事件可靠性：批次请求前先将缓冲事件落盘；app_session_summary 在入队时同步写入本地缓存。只有收到 HTTP 200 才写入 tombstone 确认事件，超时、请求中断或进程终止后的未确认事件会在下次初始化时恢复重试。服务端应按 event_id 去重。
  • 崩溃恢复不再过滤未确认请求：in-flight 文件仅用于诊断，不能证明服务端已接收；其事件会随缓存恢复重试，避免会话汇总等事件丢失。

变更 ​

  • 批次成功日志可追溯：HTTP 200 后日志会列出本批次已确认的事件类型及 event_id。
  • 运行时版本字段同步：SdkContext.kSdkVersion 更新为 1.4.6，确保事件公共字段及 getParams() 返回的 sdk_version 与包版本一致。
  • Flutter 多版本适配分发包：
    • 主包（flutter-sdk-v1.4.6.zip）：适配 Flutter 3.0.5 ~ 3.38.3，推荐新工程与常规升级使用。
    • 兼容包（flutter-sdk-v1.4.6-flutter305-gradle6-agp4-compat.zip）：专为仍使用 Flutter 3.0.5 + Gradle 6.x + AGP 4.x 的老旧 Android 工程锁定依赖线，避免插件传递依赖拉高 AGP。

说明 ​

  • app_session_summary.page_stay_list：该字段是 JSON 对象数组，不是字符串；若服务端将 payload 作为字符串存储，展示或入库时需解析第二层 JSON，避免对象数组被隐式展示为 [object Object]。
  • 主包与兼容包功能版本一致，均为 1.4.6；请按宿主构建环境选型，不要混用。

v1.4.5 · 2026-07-24 ​

新增 ​

  • getDeviceCommonFields() 返回 sid：服务端复用公共字段时可一次取得当前会话 ID 与设备字段，无需再额外调用 getParams(['sid'])。未初始化或读取失败时 sid 安全返回空字符串。

变更 ​

  • 运行时版本字段同步：SdkContext.kSdkVersion 更新为 1.4.5，确保事件公共字段及 getParams() 返回的 sdk_version 与包版本一致。

升级须知 ​

服务端事件可直接使用 AnalyticsSdk.getDeviceCommonFields() 返回的 sid；原有通过 getParams(['sid']) 获取的方式继续兼容。

v1.4.4 · 2026-07-23 ​

新增 ​

  • 统一 trackEvent 上报入口：新增 AnalyticsSdk.instance.trackEvent(eventName: ..., payload: ...)，调用方只需传入事件名和业务 payload；SDK 自动补齐公共字段、生成 event_id，并复用原有 track() 校验、签名和入队链路。广告 SDK 的 onEvent(eventName, payload) 可直接转交，无需再逐事件构造埋点实体。
  • Web 网络类型细分：新增 network_type_resolver，Web 端按 connection_type / effective_type 解析为 wifi / ethernet / cellular / cellular_2g~cellular_5g / offline / unknown；is_online 统一由网络类型推导。

变更 ​

  • AdSkipEvent 字段补齐：payload 新增 trace_id、shown_duration，并纳入 event_id 计算，与广告关闭、曝光、点击等生命周期事件归因字段对齐。
  • NetworkStateChangeEvent 规范化：网络类型白名单扩展并统一归一化；is_online 改为按规范化后的网络类型计算。
  • 运行时版本字段对齐：SdkContext.kSdkVersion 更新为 1.4.4，与 pubspec 包版本一致，确保事件公共字段及 getParams() 返回的 sdk_version 正确。

升级须知 ​

广告 SDK 接入方可将多个生命周期回调精简为统一转发：

dart
onEvent: (eventName, payload) {
  AnalyticsSdk.instance.trackEvent(
    eventName: eventName,
    payload: payload,
  );
},

原有 track() 和广告事件实体继续保留，现有接入无需强制迁移。

v1.4.2 · 2026-07-16 ​

本次为 bug 修复版本，零破坏性变更，现有代码无需修改。

修复 ​

  • Android ClientId 无效值兜底：不再直接采用 Android_CN_OAID 返回的非空 ClientId；按 IMEI/MEID → OAID/AAID → AndroidID → GUID 的顺序逐级校验并选取首个有效标识。空值、null、unknown、unkown、纯连字符以及仅由 0 和连字符组成的值（如 000000-000-0000-00000000）均视为无效并继续回退，避免匿名识别标识关闭时上报全零 OAID。
  • 设备标识字段来源统一：Android 的 device_id、oaid 和 oaid_o 统一使用同一次有效 ClientId 选择逻辑；device_id、oaid 上报 MD5 值，oaid_o 上报对应原始值，避免三个字段因兜底路径不同而产生数据不一致。

v1.4.1 · 2026-07-13 ​

新增 ​

  • AnalyticsSdk.instance.sessionObserver：只采集页面生命周期和 Session 停留明细，不自动上报 app_page_view，用于业务自行上报页面曝光的场景。
  • 页面 Observer 接入警告：初始化后首帧检查 pageObserver / sessionObserver 注册状态；两个都未注册或同时注册时打印明确警告。

变更 ​

  • 页面 Observer 二选一：自动页面曝光注册 pageObserver，手动页面曝光注册 sessionObserver，两者都会补齐 app_session_summary.page_stay_list。误同时注册时 SDK 对页面停留和自动 app_page_view 做幂等保护。

修复 ​

  • Session 切换后当前页面停留缺失：新 Session 建立但当前路由未变化时，从新 Session 开始时间重新写入当前页面停留，不再出现有 page_count / page_click_count 却 page_stay_list=[] 的汇总数据。

升级须知 ​

  • SDK 自动上报 app_page_view：继续注册 AnalyticsSdk.instance.pageObserver，无需修改。
  • 业务手动上报 app_page_view：将 navigatorObservers 中的 pageObserver 替换为 sessionObserver，避免页面曝光重复上报。
  • pageObserver 与 sessionObserver 必须且只能注册一个：都不注册会导致 page_stay_list 缺失，同时注册会打印重复接入警告。

v1.4.0 · 2026-07-10 ​

破坏性变更 ​

  • navigation 事件改为手动上报：路由 push/pop 不再自动发送 NavigationEvent，仅保留 app_page_view 自动上报。导航事件专用于用户主动点击导航菜单（底部 Tab、顶部 Tab、侧边抽屉），需在点击回调中调用 trackNavigation()。使用 .withAnalytics() 的接入方无需改动。
  • PageLifecycleObserver.currentPageKey 改为只读 getter：外部不再直接赋值，改为调用 recordNavigation(pageKey) 或 AnalyticsSdk.instance.updateCurrentPage(...)。
  • 广告字段收敛：广告展示/点击及广告 SDK 生命周期事件不再上报 ad_slot_name，只保留 ad_slot_key；adType 改为普通 String，无需再传 AdTypeEnum。
  • AdLoadFailEvent / ad_load_fail 废弃：素材加载失败统一通过 AdErrorEvent（ad_error）上报，用 MATERIAL_LOAD_FAIL 等错误码区分阶段。
  • device_id 改为 SDK 内部生成：外部传入的 deviceId 会被忽略，可清理旧的设备 ID 传入逻辑。

新增 ​

  • 启动与运行态自动埋点：初始化后自动上报 sdk_init，并补齐 app_lifecycle、network_state_change、app_session_summary 等自动事件；会话结束时汇总事件量、页面量、点击量、网络变化、滚动/触控行为等摘要。
  • 设备指纹升级：设备品牌、型号、系统名称/版本、User-Agent 由 SDK 自动采集；device_fingerprint 升级为 fp_version = 3.0.0，基于 sdk_init 启动快照中的稳定字段生成。
  • 事件签名能力：encryptedConfig.eventSignature.signKey 可下发 HMAC-SHA256 密钥，客户端事件自动补充顶层 event_sig / event_sig_version，签名输入为 event|event_id|app_id|client_ts|device_fingerprint。
  • 页面内元素曝光/点击事件：新增 AppPageItemExposureEvent（app_pageitem_exposure）和 AppPageItemClickEvent（app_pageitem_click），支持元素 ID/类型/名称、父元素、页面、来路页面、位置与推荐追踪字段。
  • 广告 SDK 生命周期事件：新增广告 SDK 初始化、请求、填充、无填充、素材加载、曝光、点击、关闭、跳过、错误链路事件，覆盖广告请求到展示闭环；ad_fill / ad_load_success / ad_close / ad_error 等补齐 trace_id。
  • trackNavigation({pageKey, pageName})：手动上报导航事件，应在点击导航菜单时、且早于 app_page_view 触发。
  • updateCurrentPage({pageKey, pageName})：手动同步当前页面状态，适用于 PageView + AutomaticKeepAliveClientMixin 场景下 Tab 切换时更新 page_click 归属页面。
  • TabBar.withAnalytics() 补齐 AppPageViewEvent：Tab 切换时同时上报 AppPageViewEvent（含来路页面）和 NavigationEvent，行为对齐 BottomNavigationBar.withAnalytics()。
  • PageNameMapper 支持 :param 动态路由：addMappings 值支持 {'key': ..., 'name': ...} 结构化 Map，将含参路由归一到稳定 pageKey，向后兼容老字符串格式。
  • AnalyticsSdk.setRealRouteResolver(resolver)：注入自定义路由名解析回调，将实际路径（如 /video/123）映射为模板路径（/video/:id），适配 GetX / GoRouter 等框架。
  • PageLifecycleObserver.currentPageKeyListenable：暴露只读 ValueListenable<String>，可响应式监听当前路由变化。
  • KeywordSearchEvent 新增 searchContentType 字段：搜索列表内容类型（video / novel / comic），可选默认 ''，纳入 event_id 哈希。
  • 点击坐标增强：PageClickEvent 新增 viewport/document 维度坐标、页面尺寸与滚动偏移字段，提升点击热力图定位精度。

修复 ​

  • 崩溃重启后事件重复上报：本批次 event_id 上报前写入 in-flight 文件，完成后清除；崩溃重启时合并 in-flight 集合跳过重发，实现 at-most-once 语义。
  • 事件签名请求前兜底：uploadBatch() 真正请求前对缺失 event_sig 的客户端事件再次补签，避免启动早期签名配置晚到导致裸签上报（已有非空签名不覆盖）。
  • GlobalClickWrapper 点击坐标百分比不准：改用 renderBox.globalToLocal() 转本地坐标后计算，修复热力图位置偏移。
  • PageLifecycleObserver.dispose() 多 Navigator 污染：仅清理本 observer 注册的 navigator 路由，不再误移除其他 navigator 上的 observer。
  • ApiConfig.buildUrl 路径前缀丢失：baseDomain 含路径前缀（如 /v2）时补上 uri.path 拼接，修复上报 URL 错误。

变更 ​

  • 事件白名单降级策略：encryptedConfig.eventList 为空或省略时优先沿用本地缓存的事件类型配置，无缓存时才允许所有事件上报。
  • 广告展示去重改为页面级：同一页面访问内按 pageKey + adId 去重，页面退出清理该页面记录，新 session 开始清理全部记录。

升级须知 ​

  • 如服务端启用了 encryptedConfig.eventList，请按接入范围加入新增事件：sdk_init、app_lifecycle、network_state_change、app_session_summary、app_pageitem_exposure、app_pageitem_click，以及广告 SDK 生命周期事件（ad_sdk_init、ad_request、ad_fill、ad_no_fill、ad_load_success、ad_impression_sdk、ad_click_sdk、ad_close、ad_skip、ad_error）。
  • 所有导航菜单点击回调需补加 trackNavigation()（使用 .withAnalytics() 者除外）。
  • TabBar.withAnalytics() 会新增来自 Tab 切换的 app_page_view，请提前通知数据侧。
  • 如服务端校验 event_sig，按 event|event_id|app_id|client_ts|device_fingerprint 拼接明文并用 HMAC-SHA256 校验。

v1.3.0 · 2026-04-18 ​

本次为 bug 修复版本，零破坏性变更，现有代码无需修改。

修复 ​

  • GlobalClickWrapper 滑动误报：滚动时不再误触发点击上报；来电、边缘手势等系统中断后触摸状态正确清理，不影响下次点击。

v1.2.0 · 2026-04-17 ​

修复 ​

  • event_id 防抖去重：新增时间窗口防抖机制，同一事件在一定时间内重复调用 track()，第二条起直接丢弃，不入队、不上报。

    背景：event_id 基于秒级时间戳做 MD5，同一秒内相同参数的事件会产生相同 event_id，旧逻辑会重复上报。接入方无需任何改动，SDK 自动处理。

新增 ​

  • init() 新增可选参数 appVersion：支持接入方传入应用版本号，随每条事件上报至服务端。
    • 格式合法（如 '2.3.1'，符合 x.y.z）：正常写入并上报。
    • 格式非法（如 'beta'、'1.0'）：Debug 模式打印错误日志并忽略本次传值；Release 模式静默降级为 '1.0.0'。
    • 未传 appVersion：默认填 '1.0.0'（原为空字符串）。

v1.1.0 · 2026-04-15 ​

新增 ​

  • Tab 切换自动埋点：新增 BottomNavigationBar.withAnalytics() 和 TabBar.withAnalytics() 扩展方法，Tab 切换时自动上报导航/页面事件，无需手动调用 track()。

    • BottomNavigationBar.withAnalytics(tabs: [...]) — 切换时同时上报 AppPageViewEvent（含来路页面）和 NavigationEvent，并更新 PageLifecycleObserver.currentPageKey，与路由页面体系完全兼容。
    • TabBar.withAnalytics(tabs: [...]) — 切换时同时上报 AppPageViewEvent（含来路页面）和 NavigationEvent，并更新 PageLifecycleObserver.currentPageKey，适合顶部主导航或页面内分区 Tab。返回值实现 PreferredSizeWidget，可直接用于 AppBar.bottom。
    • 新增 AnalyticsTab(String key, [String? name]) 数据类，name 省略时由 PageNameMapper 自动解析。

  • NovelEvent / ComicEvent 新增章节字段：chapterId（章节 ID）和 chapterName（章节名称），均为可选字段，默认 ''。无章节内容或未对接搜索推荐引擎时传空字符串即可。两个字段同时纳入 event_id 的哈希计算。同步适配 compat/flutter-1.22 分支。