SDK 接入文档

Appearance

Android SDK 更新日志 ​

v1.5.1 · 2026-09-18 ​

在 Android 1.4.9 基础上同步 Flutter 1.5.1 业务增量。SDK 上报版本为 1.5.1，指纹规则版本继续为 fp_version 4.0.0。普通 AAR 与 AGP 4.2.2 命名 AAR 为同一二进制，二选一接入。

变更 ​

  • PostEvent 时间字段：输出与 fromJson(JSONObject/Map) 改用 post_create_time（仍为 10 位秒级 int）。Java 构造参数 createTime 不变；不读取旧字段 create_time 别名。
  • DramaPlayBehaviorEnum：新增 EP_COMPLETE（ep_complete / 播放完成）、EP_SHARE（ep_share / 分享）。
  • ClickItemTypeEnum：新增 POST（post / 帖子）、SHORT_DRAMA（short_drama / 短剧）。
  • 关键词搜索：searchContentType 支持 post / short_drama；search_id 为可视搜索结果 ID（多个英文逗号分隔），不是搜索会话 ID。

约定说明 ​

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

升级须知 ​

  1. 替换旧 AAR，libs 中只保留一份本 SDK。正式交付文件为 analytics-sdk-1.5.1.aar（与 analytics-sdk-1.5.1-agp4.2.2.aar 相同）。
  2. 后台与手写帖子 JSON 改用 post_create_time；滚动升级时由后台自行兼容旧客户端的 create_time。
  3. 后台接受剧集 ep_complete / ep_share 与搜索 post / short_drama；事件名与签名算法不变。
  4. 已保存的 v4 指纹继续复用，无需清除；无新增初始化参数。

集成要求：Android 7.0+（minSdk 24），Java 8。

v1.4.9 · 2026-09-16 ​

Android Native 与 Flutter 1.4.9 的 Android 指纹规则对齐。SDK 上报版本为 1.4.9，指纹规则版本为 fp_version 4.0.0。

变更 ​

  • 指纹 v4：canonical 前缀改为 fp_v4，移除 language、timezone 因子（仍可作为环境信息上报）。
  • 指纹持久化：首次按启动快照稳定字段生成 64 位小写 SHA-256，保存到 Context.getFilesDir()/analytics_device_fingerprint.txt；后续初始化与进程重启优先读取已有值。
  • 并发写入：同进程并发初始化串行处理；临时文件同步后替换并回读确认；写入失败不发布临时指纹，返回空字符串，下次初始化重试。
  • 兼容入口：旧 initializeV3 / computeFingerprintV3 方法名保留为弃用入口并转发至当前规则；旧六因子/UUID 入口与 analytics_fingerprint.txt 不参与新上报链路。

修复 ​

  • 重复初始化指纹丢失：sdk_init 已发出后重复初始化仍会恢复指纹 / 重试存储失败；不额外发送 sdk_init 或初始 cold_start。

升级须知 ​

  1. 替换旧 AAR，libs 中只保留一份本 SDK。正式交付文件为 analytics-sdk-1.4.9.aar（普通宿主与 AGP 4.2.2 旧工具链宿主使用同一 AAR）。
  2. 首次升级至 1.4.9 时，旧 v3 未持久化的指纹会变为新 v4 值；服务端按 fp_version 区分。
  3. 应用数据与指纹文件保留期间，语言、时区、国家、系统版本或设备标识变化都不覆盖指纹。
  4. 无新增接入参数；业务方不应自行计算、传入或清理 SDK 指纹文件。

集成要求：Android 7.0+（minSdk 24），Java 8。

v1.4.8 · 2026-09-08 ​

Android Native 正式 AAR，SDK 上报版本为 1.4.8。帖子、剧集和视频扩展同步自 Flutter analytics_sdk。

新增 ​

  • 帖子 / 剧集事件：新增客户端 PostEvent、DramaEvent、DramaStatusChangeEvent 及对应枚举，支持实体构造与 fromJson(JSONObject) / fromJson(Map)。
  • VideoEvent 扩展：新增 POST_VIDEO 内容类型、postId 与整数 playSpeed；旧构造器继续兼容，默认 play_speed=100（1 倍速）。
  • 服务端帖子/剧集事件登记：登记 8 类服务端帖子/剧集事件，并跳过这些事件的客户端自动签名；补齐客户端帖子/剧集 ID 校验及字段归一。
  • HTTP 排查日志：上报日志包含实际 POST URL、请求头、完整签名后 JSON 请求体、响应状态/头/体，使用 AnalyticsSdkHttp 标签及请求编号分段输出。
  • OAID 内嵌：Release AAR 内嵌 Android_CN_OAID:4.2.16、华为 ads-identifier:3.4.62.300、荣耀 ads-identifier:1.0.2.301（含类、资源、Manifest、混淆规则）。

修复 ​

  • 顶层 signKey 解析：修复正式环境加密配置顶层 signKey 未被读取导致客户端事件缺少 event_sig 的问题；兼容签名字段别名与原有嵌套配置，顶层非空优先。
  • 本地 AAR OAID 依赖：补齐本地 AAR 交付时的 OAID 依赖，避免 Demo 源码 Debug 依赖掩盖 Release 集成缺类问题。

行为变更 ​

  • 保留 FULL 模式自动 page_click：自动页面展示、页面点击及触摸/滚动/捏合会话统计均保留；PageClickEvent 手动接口保持兼容。
  • Demo 调整：仅 Demo 测试台移除手动 PageClickEvent 按钮与批量发送；屏幕控制台不回显 page_click，SDK 自动采集与网络上报正常保留。
  • 移除 IM 事件：移除全部 IM 事件实体、枚举与文档入口。
  • 统一日志开关：业务方通过 AnalyticsSdk.setLoggingEnabled(boolean) 控制 SDK Logcat（含请求/响应）；Release AAR 默认关闭，运行中可切换。

升级须知 ​

  1. 替换旧 AAR，libs 中只保留一份本 SDK。正式交付文件为 analytics-sdk-1.4.8.aar。
  2. 移除宿主对 OAID / 华为 / 荣耀标识库的直接依赖；如其他库间接引入，排除对应传递依赖，避免重复类。OkHttp、JSON、AndroidX 等仍需宿主配置。
  3. 使用新事件时，在服务端 eventList 白名单加入 post_event、drama_event、drama_status_change；帖子视频播放仍为 video_event。
  4. FULL 模式自动采集页面点击，无需再手动重复上报；删除旧 IM 事件调用。
  5. 排查上报时，初始化前开启日志并收集 AnalyticsSdkHttp；结束后调用 setLoggingEnabled(false)。

集成要求：Android 7.0+（minSdk 24），Java 8。

v1.0.6 · 2026-04-18 ​

修复 ​

  • 滑动误报修复：点击事件改为手指抬起时判定，滑动操作不再误触发点击埋点。

文档更新 ​

  • 接入指南补充了所有 14 个事件的完整 payload 字段说明，方便对接时核对字段。

升级方式 ​

替换 sdk-release.aar 文件，无接口变更，可直接替换。

v1.0.5 · 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.0.4 · 2026-04-16 ​

新增字段 ​

  • NovelEvent / ComicEvent 新增 chapter_id（章节 ID）和 chapter_name（章节名称）字段。无章节内容或未对接推荐引擎时传空字符串即可。
  • 旧构造器保持兼容重载（默认传 ""），现有接入方无需修改代码，直接替换 AAR 即可。

播放器自动埋点 ​

新增独立模块 com.datapluse.analyticssdk.player，不修改任何现有代码，不影响宿主 App 稳定性。

  • PlayerTracker：核心协调器，自动计算 playDuration / playProgress，调用 AnalyticsSdk.track() 上报 VideoEvent。
  • ExoPlayerAdapter：对接 ExoPlayer（media3），play / pause / seek / complete / buffer / error / 视频切换全自动。
  • MediaPlayerAdapter：对接原生 MediaPlayer，complete / seek / buffer / error 自动，play / pause 需手动调 tracker.notifyPlay() / tracker.notifyPause()。
  • IjkPlayerAdapter：对接 IjkPlayer，接口与 MediaPlayerAdapter 一致。
  • PlayerVideoMeta：视频元数据值对象（Builder 模式，含 VideoEvent 全部业务字段）。
  • PlayerEventConfig：事件开关配置，支持 defaults() / only(...) / all()（含 buffer/error）。

接入方无变更：现有代码无需任何改动，PlayerTracker 仅在接入方显式使用时生效。