Analytics SDK Android 接入指南

具体的事件上报参数说明，参考文档：Lark 链接　密码：@8228T56

文档版本：1.9 | SDK 版本：1.5.1 | minSdk 24 | Java 8+

下载 SDK

1. 环境要求

项目	要求
minSdk	24 (Android 7.0+)
compileSdk	35
Java	8
网络权限	已内置，AAR 自动合并，无需手动声明

2. 集成 AAR

将交付包中的 analytics-sdk-1.5.1.aar 放入 app/libs/（替换旧包，只保留一份本 SDK），然后在 app/build.gradle 中添加依赖：

groovy

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar'])
    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
    implementation 'org.json:json:20240303'
    implementation 'androidx.core:core:1.13.1'
}

OAID 已内嵌：Release AAR 已包含 Android_CN_OAID、华为 / 荣耀 ads-identifier（含资源、Manifest、混淆规则）。宿主无需再声明这三个 Maven 依赖，也无需额外配置 JitPack / 华为 / 荣耀仓库。若宿主或其他库已直接或间接引入，请移除直接依赖或排除传递依赖，避免重复类。

设备指纹与升级

业务方无需新增初始化参数。SDK 自动生成 device_fingerprint，可通过 getParams() 或实际事件 JSON 读取；不要把它当作 deviceId 参数传回。

项目	约定
`sdk_version`	`1.5.1`
`fp_version`	`4.0.0`
持久化文件	`Context.getFilesDir()/analytics_device_fingerprint.txt`
生成时机	本地没有非空值时，按 Android 启动快照稳定字段计算 SHA-256
后续初始化	读取已有文件；不随语言、时区或系统升级重算
失败降级	初始化尚未完成或存储失败时为空；下次初始化继续恢复 / 重试

language 和 timezone 仍可出现在 sdk_init 环境信息中，但不参与指纹。首次从 v3（1.4.8）升级时会生成新的 v4 指纹；原先的 analytics_fingerprint.txt 是旧 UUID 兼容入口文件，不会当作 v4 指纹迁移。从 1.4.9 升级至 1.5.1 直接复用已保存的 v4 指纹，无需清理。

不卸载且保留应用数据和指纹文件时，指纹稳定。清除应用数据、删除文件等操作会触发重新生成。服务端应按 fp_version 区分新旧指纹。

验收： 初始化完成后记录指纹与 fp_version；强制结束进程后重启、重复 init()、修改语言 / 时区后检查值不变。不要在正式用户数据上执行清除数据测试。

混淆配置（ProGuard/R8）

无需手动添加任何规则。 AAR 内已内嵌 consumer ProGuard rules，Gradle 在构建时会自动合并到 app 的混淆配置中。

若 app 的 build.gradle 开启了混淆：

groovy

buildTypes {
    release {
        minifyEnabled true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}

SDK 的公开 API（入口类、事件实体、枚举、生命周期观察者）会被自动保护，无需在 proguard-rules.pro 中额外声明。

3. 初始化

在 Application.onCreate() 中调用，且必须在所有事件上报之前完成。

java

import com.datapluse.analyticssdk.core.AnalyticsSdk;
import com.datapluse.analyticssdk.utils.AnalyticsUtils;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // 由业务方控制日志：调试开、正式关；也可在运行中切换（Release AAR 默认关闭）
        AnalyticsSdk.setLoggingEnabled(BuildConfig.DEBUG);

        // 设置客户端版本（所有事件会自动携带此字段，无需每次传参）
        AnalyticsUtils.setClientVersion(BuildConfig.VERSION_NAME);

        // 初始化 SDK
        AnalyticsSdk.getInstance().init(
            this,                  // Context（推荐传 Application，Activity context 也可）
            "your_app_id",         // appId，由平台分配
            null,                  // encryptedConfig，见第 4 节；启动时可传 null
            "official",            // channel 渠道标识
            getUserId(),           // uid，未登录传 null
            getDeviceId(),         // 设备唯一标识
            true                   // enableAutoPageTrack：自动页面展示与点击追踪
        );
    }
}

参数说明

参数	类型	说明
`context`	`Context`	推荐在 `Application.onCreate()` 中传 `this`；SDK 内部会自动调用 `getApplicationContext()`，传 Activity context 也安全
`appId`	`String`	平台分配的应用 ID
`encryptedConfig`	`String`	AES-GCM 加密配置，包含域名列表和事件白名单；可先传 `null`，配置到达后调用 `refreshConfig()`
`channel`	`String`	渠道标识，如 `"official"` `"google_play"`
`uid`	`String`	用户 ID；未登录传 `null`；非空时长度须 ≥ 4（由宿主保证，SDK 不额外校验）
`deviceId`	`String`	设备唯一标识
`enableAutoPageTrack`	`boolean`	`true`（`FULL`）时自动上报页面展示与 `page_click`；未启用自动点击时也可手动 `track(PageClickEvent)`

注意：encryptedConfig 包含域名列表，SDK 初始化后才能上报事件。若启动时尚未拿到配置，需要尽快调用 refreshConfig()。正式环境若在配置顶层下发 signKey，v1.4.8 起可正确读取并生成 event_sig。

4. 配置刷新

服务端下发加密配置后调用，包含域名列表（测速后自动选最快节点）和事件白名单。

java

// 从服务端拉取后调用，可在任意时机调用（线程安全）
AnalyticsSdk.getInstance().refreshConfig(encryptedConfigString);

配置内容（解密后结构）：

json

{
  "domainList": ["https://api1.example.com", "https://api2.example.com"],
  "eventList": ["app_page_view", "page_click", "video_play"]
}

domainList：SDK 会并发 HEAD 测速，自动选择响应最快的节点作为上报地址。
eventList：事件类型白名单，不在列表中的事件类型会被静默丢弃。

5. 用户管理

java

import com.datapluse.analyticssdk.utils.AnalyticsUtils;
import com.datapluse.analyticssdk.manager.UserManager;
import com.datapluse.analyticssdk.enums.UserTypeEnum;

// 登录成功后：同时设置 uid 和用户类型（推荐用法）
UserManager.setUserIdAndType("real_user_id_123", UserTypeEnum.VIP);

// 或分别更新
AnalyticsUtils.setUid("real_user_id_123");
UserManager.updateUserType(UserTypeEnum.VIP);

// 登出：自动清空 uid 并将用户类型重置为 NORMAL
UserManager.logoutUser();

// 更新渠道（动态切换渠道时使用）
UserManager.setChannel("new_channel");

说明： UserManager 是用户状态的统一管理入口，负责 uid、userType、channel 的协同更新，保证事件字段一致。AnalyticsUtils.setUid() 仍然可用，但涉及 userType 变更时推荐统一通过 UserManager 操作。非空 uid 长度须 ≥ 4（由宿主保证）。

6. 事件上报

所有事件通过同一入口上报，SDK 内部自动批量处理：

java

AnalyticsSdk.getInstance().track(event);

如需立即上报（如 App 退出前）：

java

AnalyticsSdk.getInstance().flush();

事件 JSON 结构

每条事件上报的 JSON 分为两层：

json

{
  // ── 公共字段（SDK 自动注入，无需手动传）──
  "event":            "page_click",
  "event_id":         "a3f1...",
  "app_id":           "your_app_id",
  "uid":              "user_123",
  "sid":              "abc...",
  "channel":          "official",
  "client_ts":        1713400000,
  "device":           "Android",
  "device_id":        "xxx",
  "device_brand":     "Xiaomi",
  "device_model":     "Mi 14",
  "system_name":      "Android",
  "system_version":   "14",
  "device_fingerprint": "xxx",
  "fp_version":       "4.0.0",
  "client_version":   "2.3.0",
  "sdk_version":      "1.5.1",
  "app_version":      "1.0.0",
  "user_agent":       "",

  // ── 业务字段（按事件类型不同，见各节说明）──
  "payload": { ... }
}

page_key 格式说明

所有事件的 pageKey、referrerPageKey、currentPageKey、navigationKey 字段，SDK 在上报时会自动去掉前导 /：

传入值	实际上报值
`/home`	`home`
`/video_detail`	`video_detail`
`/`	`/`（仅有斜杠时保留）
`home`	`home`（无斜杠不变）

接入方按习惯传带 / 或不带 / 均可，SDK 统一处理。

6.1 页面展示 — `AppPageViewEvent`

java

import com.datapluse.analyticssdk.entity.AppPageViewEvent;

// 标准（含推荐场景 trace_id）
AppPageViewEvent event = new AppPageViewEvent(
    "vip",           // userType，可传空字符串
    "/home",         // pageKey
    "首页",           // pageName
    "/splash",       // referrerPageKey（来源页）
    "启动页",         // referrerPageName
    "/home",         // currentPageKey
    "首页",           // currentPageName
    320,             // pageLoadTime（毫秒）
    "trace_abc123"   // recommendTraceId，非推荐场景传 ""
);
AnalyticsSdk.getInstance().track(event);

java

// 简化（非推荐场景，省略 recommendTraceId）
AppPageViewEvent event = new AppPageViewEvent(
    "vip", "/home", "首页", "/splash", "启动页", "/home", "首页", 320
);
AnalyticsSdk.getInstance().track(event);

payload 字段

字段	类型	说明
`page_key`	String	去前导 `/` 后的页面标识
`page_name`	String	页面名称
`referrer_page_key`	String	来源页面标识
`referrer_page_name`	String	来源页面名称
`current_page_key`	String	当前页面标识
`current_page_name`	String	当前页面名称
`page_load_time`	int	页面加载耗时（毫秒）
`recommend_trace_id`	String	推荐引擎 trace_id，非推荐场景为 `""`
`user_type`	String	用户类型，如 `"vip"`

6.2 页面点击 — `PageClickEvent`

FULL 模式自动上报（默认 300ms 节流，滑动 / 取消手势不触发）。也可手动调用下方接口；未启用自动追踪时需自行上报。

java

import com.datapluse.analyticssdk.entity.PageClickEvent;

PageClickEvent event = new PageClickEvent(
    "/home", "首页",
    540, 960,      // 点击坐标 x, y（像素）
    50, 50,        // 点击位置百分比 x%, y%（0-100）
    1080, 1920,    // 屏幕宽高
    "trace_abc123" // recommendTraceId，非推荐场景传 ""
);
AnalyticsSdk.getInstance().track(event);

payload 字段

字段	类型	说明
`page_key`	String	去前导 `/` 后的页面标识
`page_name`	String	页面名称
`click_page_x`	int	点击坐标 X（像素）
`click_page_y`	int	点击坐标 Y（像素）
`click_x_percent`	int	点击位置横向百分比（0-100）
`click_y_percent`	int	点击位置纵向百分比（0-100）
`screen_width`	int	屏幕宽度（像素）
`screen_height`	int	屏幕高度（像素）
`recommend_trace_id`	String	推荐引擎 trace_id，非推荐场景为 `""`

6.3 导航 — `NavigationEvent`

java

import com.datapluse.analyticssdk.entity.NavigationEvent;

AnalyticsSdk.getInstance().track(
    new NavigationEvent("/video_detail", "视频详情页")
);

payload 字段

字段	类型	说明
`navigation_key`	String	去前导 `/` 后的导航目标标识
`navigation_name`	String	导航目标名称

6.4 视频行为 — `VideoEvent`

推荐使用 VideoMetadata 封装视频内容信息，将构造函数从 13 个参数简化为 8 个：

java

import com.datapluse.analyticssdk.entity.VideoEvent;
import com.datapluse.analyticssdk.entity.VideoMetadata;
import com.datapluse.analyticssdk.enums.VideoEventEnum;
import com.datapluse.analyticssdk.enums.VideoContentTypeEnum;

VideoMetadata meta = new VideoMetadata(
    "video_001",    // videoId
    "搞笑合集第一期", // videoTitle
    "type_comedy",  // videoTypeId
    "娱乐",          // videoTypeName
    "tag_funny",    // videoTagKey
    "搞笑"           // videoTagName
);

VideoEvent event = new VideoEvent(
    meta,
    300,                           // videoDuration（总时长，秒）
    120,                           // playDuration（本次播放时长，秒）
    40,                            // playProgress（进度，0-100）
    VideoEventEnum.VIDEO_PLAY,     // videoBehavior
    VideoContentTypeEnum.SHORT_VIDEO, // videoContentType
    "media_001",                   // mediaId
    "trace_abc123"                 // recommendTraceId，非推荐传 ""
);
AnalyticsSdk.getInstance().track(event);

旧构造器继续兼容，play_speed 默认 100（1 倍速）。帖子视频使用完整重载，在末尾追加 postId、playSpeed：

java

AnalyticsSdk.getInstance().track(new VideoEvent(
    meta, 300, 120, 40, VideoEventEnum.VIDEO_PLAY,
    VideoContentTypeEnum.POST_VIDEO, "media_001", "", "post_001", 125
)); // play_speed = 125 表示 1.25 倍速

仅 post_video 上报 post_id，且帖子 ID 必须非空；普通长视频 / 短视频等其他内容类型均省略该字段。

payload 字段

字段	类型	说明
`video_id`	String	视频 ID
`video_title`	String	视频标题
`video_type_id`	String	视频分类 ID
`video_type_name`	String	视频分类名称
`video_tag_key`	String	视频标签标识
`video_tag_name`	String	视频标签名称
`video_duration`	int	视频总时长（秒）
`play_duration`	int	本次播放时长（秒）
`play_progress`	int	播放进度（0-100）
`play_speed`	int	播放倍速，`100`=1 倍速，`125`=1.25 倍速；默认 `100`
`video_behavior_key`	String	行为标识，如 `"video_play"`
`video_behavior_name`	String	行为展示名，如 `"播放"`
`video_content_type`	String	内容类型，如 `"short_video"` / `"post_video"`
`post_id`	String	帖子 ID；仅 `post_video` 必填且非空，其他类型省略
`media_id`	String	媒体 ID
`recommend_trace_id`	String	推荐引擎 trace_id，非推荐场景为 `""`

注意： videoBehavior 枚举在 payload 中拆分为 video_behavior_key（字符串值）和 video_behavior_name（中文展示名）两个字段。

6.15 帖子展示 — `PostEvent`

java

import com.datapluse.analyticssdk.entity.PostEvent;
import com.datapluse.analyticssdk.enums.PostContentTypeEnum;

AnalyticsSdk.getInstance().track(new PostEvent(
    "media_001", "post_001", "视频帖子", System.currentTimeMillis() / 1000L,
    "author_001", "作者", PostContentTypeEnum.VIDEO_POST
));

帖子展示默认行为为 view / “展示”；分类默认 default / “默认分类”，标签默认 default / “默认标签”，推荐 trace 默认为空。post_id 必须非空，否则事件丢弃。构造参数仍为 createTime；payload 输出字段为 post_create_time（10 位秒级），fromJson 只读新字段。支持 fromJson(JSONObject) / fromJson(Map)。

启用 eventList 白名单时加入 post_event。post_like / post_comment / post_collect / post_unlock 由服务端上报，SDK 登记名称并跳过客户端自动加签。

6.16 剧集播放 — `DramaEvent`

java

import com.datapluse.analyticssdk.entity.DramaEvent;
import com.datapluse.analyticssdk.enums.DramaPlayBehaviorEnum;

AnalyticsSdk.getInstance().track(new DramaEvent(
    "drama_001", "短剧标题", 5, 20, "media_005", "video_005",
    300, 60, 20, DramaPlayBehaviorEnum.EP_PLAY
));

drama_id、video_id 必须非空。内容类型默认 short_drama，倍速默认 100。播放行为含 EP_VIEW / EP_PLAY / EP_PAUSE / EP_FORWARD / EP_REWIND，以及 EP_COMPLETE（播放完成）、EP_SHARE（分享）。启用白名单时加入 drama_event。

6.17 剧集状态变更 — `DramaStatusChangeEvent`

java

import com.datapluse.analyticssdk.entity.DramaStatusChangeEvent;
import com.datapluse.analyticssdk.enums.DramaBehaviorEnum;

AnalyticsSdk.getInstance().track(new DramaStatusChangeEvent(
    "drama_001", "短剧标题", 5, "media_005", "video_005", 2,
    DramaBehaviorEnum.EP_SWITCH
)); // 从第 2 集切到第 5 集

启用白名单时加入 drama_status_change。drama_like / drama_comment / drama_collect / drama_purchase 由服务端上报并跳过客户端自动加签。

6.5 小说阅读 — `NovelEvent`

java

import com.datapluse.analyticssdk.entity.NovelEvent;
import com.datapluse.analyticssdk.enums.ReadBehaviorEnum;

NovelEvent event = new NovelEvent(
    "novel_001", "斗破苍穹",     // novelId, novelTitle
    "type_fantasy", "玄幻",      // novelTypeId, novelTypeName
    "tag_xh", "仙侠",            // novelTagKey, novelTagName
    35,                          // readProgress（0-100）
    128,                         // pageNo（当前页码）
    ReadBehaviorEnum.PAGE_NEXT,  // novelBehavior
    "media_novel_001",           // mediaId
    "trace_abc123",              // recommendTraceId，非推荐传 ""
    "chapter_003",               // chapterId，没有章节传 ""
    "第三章 风起云涌"              // chapterName，没有章节传 ""
);
AnalyticsSdk.getInstance().track(event);

payload 字段

字段	类型	说明
`novel_id`	String	小说 ID
`novel_title`	String	小说标题
`novel_type_id`	String	分类 ID
`novel_type_name`	String	分类名称
`novel_tag_key`	String	标签标识
`novel_tag_name`	String	标签名称
`read_progress`	int	阅读进度（0-100）
`page_no`	int	当前页码。普通小说从 `1` 开始；仅有声小说业务约定允许 `0`。注意：当前校验器仍会移除 `page_no = 0`
`novel_behavior_key`	String	行为标识，如 `"view"`
`novel_behavior_name`	String	行为展示名，如 `"下一页"`
`media_id`	String	媒体 ID
`recommend_trace_id`	String	推荐引擎 trace_id，非推荐场景为 `""`
`chapter_id`	String	章节 ID，无章节传 `""`
`chapter_name`	String	章节名称，无章节传 `""`

注意： novelBehavior 枚举在 payload 中拆分为 novel_behavior_key 和 novel_behavior_name 两个字段。

6.6 漫画阅读 — `ComicEvent`

java

import com.datapluse.analyticssdk.entity.ComicEvent;
import com.datapluse.analyticssdk.enums.ReadBehaviorEnum;

ComicEvent event = new ComicEvent(
    "comic_001", "火影忍者",
    "type_action", "热血",
    "tag_ninja", "忍者",
    60,                         // readProgress（0-100）
    700,                        // pageNo
    ReadBehaviorEnum.PAGE_NEXT,
    "media_comic_001",
    "trace_abc123",             // recommendTraceId，非推荐传 ""
    "chapter_010",              // chapterId，没有章节传 ""
    "第十话 忍道"                 // chapterName，没有章节传 ""
);
AnalyticsSdk.getInstance().track(event);

payload 字段

字段	类型	说明
`comic_id`	String	漫画 ID
`comic_title`	String	漫画标题
`comic_type_id`	String	分类 ID
`comic_type_name`	String	分类名称
`comic_tag_key`	String	标签标识
`comic_tag_name`	String	标签名称
`read_progress`	int	阅读进度（0-100）
`page_no`	int	当前页码
`comic_behavior_key`	String	行为标识，如 `"view"`
`comic_behavior_name`	String	行为展示名，如 `"下一页"`
`media_id`	String	媒体 ID
`recommend_trace_id`	String	推荐引擎 trace_id，非推荐场景为 `""`
`chapter_id`	String	章节 ID，无章节传 `""`
`chapter_name`	String	章节名称，无章节传 `""`

注意： comicBehavior 枚举在 payload 中拆分为 comic_behavior_key 和 comic_behavior_name 两个字段。

6.7 广告展示 — `AdImpressionEvent`

SDK 自动对广告 ID 按页面维度去重：同一页面内已上报的广告 ID 不会重复上报；用户返回该页面后，去重记录自动重置，广告可重新上报。Session 结束时全部清空。

java

import com.datapluse.analyticssdk.entity.AdImpressionEvent;
import com.datapluse.analyticssdk.enums.AdTypeEnum;

// 多个广告 ID 用逗号分隔
AdImpressionEvent event = new AdImpressionEvent(
    "/home", "首页",
    "slot_banner_top", "顶部Banner",
    "ad_001,ad_002",       // adId（多个用英文逗号分隔）
    AdTypeEnum.BANNER,
    "cr_001,cr_002"        // creativeId（可选，与 adId 一一对应）
);
AnalyticsSdk.getInstance().track(event);

payload 字段

字段	类型	说明
`page_key`	String	去前导 `/` 后的页面标识
`page_name`	String	页面名称
`ad_slot_key`	String	广告位标识
`ad_slot_name`	String	广告位名称
`ad_id`	String	广告 ID，多个用英文逗号分隔
`ad_type`	String	广告类型，来自 `AdTypeEnum.getLabel()`
`creative_id`	String	素材 ID，可选，默认 `""`

6.8 广告点击 — `AdClickEvent`

java

import com.datapluse.analyticssdk.entity.AdClickEvent;
import com.datapluse.analyticssdk.enums.AdTypeEnum;

AdClickEvent event = new AdClickEvent(
    "/home", "首页",
    "slot_banner_top", "顶部Banner",
    "ad_001",                    // adId
    AdTypeEnum.BANNER.getLabel(), // adType（字符串，推荐用枚举 .getLabel() 保持统一）
    "cr_001"                     // creativeId（可选）
);
AnalyticsSdk.getInstance().track(event);

注意： AdClickEvent 的 adType 参数为字符串（与 AdImpressionEvent 使用枚举不同）。建议统一通过 AdTypeEnum.XXX.getLabel() 传值，避免拼写错误。

payload 字段

字段	类型	说明
`page_key`	String	去前导 `/` 后的页面标识
`page_name`	String	页面名称
`ad_slot_key`	String	广告位标识
`ad_slot_name`	String	广告位名称
`ad_id`	String	广告 ID
`ad_type`	String	广告类型字符串
`creative_id`	String	素材 ID，可选，默认 `""`

6.9 广告通用事件 — `AdvertisingEvent`

java

import com.datapluse.analyticssdk.entity.AdvertisingEvent;

AdvertisingEvent event = new AdvertisingEvent(
    "show",                 // eventType（自由字符串，建议团队内统一约定，如 show/click/close）
    "adv_key_summer",       // advertisingKey
    "夏季促销活动",           // advertisingName
    "adv_campaign_001"      // advertisingId
);
AnalyticsSdk.getInstance().track(event);

payload 字段

字段	类型	说明
`event_type`	String	广告行为类型，无枚举约束，由业务方自定义（如 `"show"` `"click"` `"close"`）
`advertising_key`	String	广告活动标识
`advertising_name`	String	广告活动名称
`advertising_id`	String	广告活动 ID

6.10 推荐列表展示 — `RecommendListViewEvent`

java

import com.datapluse.analyticssdk.entity.RecommendListViewEvent;
import com.datapluse.analyticssdk.enums.RecommendContentTypeEnum;

RecommendListViewEvent event = new RecommendListViewEvent(
    "/home", "首页",
    RecommendContentTypeEnum.VIDEO,          // 内容类型
    "trace_abc123",                          // recommendTraceId（推荐引擎下发）
    "vid_001,vid_002,vid_003",               // 可视窗口内内容 ID（逗号分隔）
    "{\"algo\":\"cf\",\"exp_id\":\"A1\"}"    // recommendTraceInfo（溯源 JSON）
);
AnalyticsSdk.getInstance().track(event);

payload 字段

字段	类型	说明
`page_key`	String	去前导 `/` 后的页面标识
`page_name`	String	页面名称
`recommend_content_type`	String	内容类型，如 `"video"`
`recommend_trace_id`	String	推荐引擎 trace_id
`recommend_id`	String	可视内容 ID，多个用英文逗号分隔
`recommend_trace_info`	String	推荐溯源详情（JSON 字符串）
`client_version`	String	客户端版本，SDK 从公共字段注入 payload

6.11 推荐列表点击 — `RecommendListClickEvent`

java

import com.datapluse.analyticssdk.entity.RecommendListClickEvent;
import com.datapluse.analyticssdk.enums.RecommendContentTypeEnum;

RecommendListClickEvent event = new RecommendListClickEvent(
    "/home", "首页",
    "trace_abc123",                          // recommendTraceId
    "vid_002",                               // 被点击内容 ID
    RecommendContentTypeEnum.VIDEO,
    "{\"algo\":\"cf\",\"exp_id\":\"A1\"}"    // recommendTraceInfo
);
AnalyticsSdk.getInstance().track(event);

payload 字段

字段	类型	说明
`page_key`	String	去前导 `/` 后的页面标识
`page_name`	String	页面名称
`recommend_trace_id`	String	推荐引擎 trace_id
`recommend_id`	String	被点击内容 ID
`recommend_content_type`	String	内容类型，如 `"video"`
`recommend_trace_info`	String	推荐溯源详情（JSON 字符串）
`client_version`	String	客户端版本，SDK 从公共字段注入 payload

6.12 应用安装 — `AppInstallEvent`

java

import com.datapluse.analyticssdk.entity.AppInstallEvent;

// traceId 从剪贴板或落地页链接中获取
AppInstallEvent event = new AppInstallEvent("trace_install_abc001");
AnalyticsSdk.getInstance().track(event);

payload 字段

字段	类型	说明
`trace_id`	String	落地页点击生成的唯一 ID，从剪贴板读取

6.13 关键词搜索 — `KeywordSearchEvent`

java

import com.datapluse.analyticssdk.entity.KeywordSearchEvent;

// 仅关键词 + 结果数；search_content_type / search_trace_id / search_id 默认为空字符串
AnalyticsSdk.getInstance().track(
    new KeywordSearchEvent("搞笑视频合集", 256)
);

// 帖子 / 短剧搜索示例
AnalyticsSdk.getInstance().track(new KeywordSearchEvent(
    "短剧关键词", 2, "short_drama", "trace_001", "drama_001,drama_002"
));

payload 字段

字段	类型	说明
`keyword`	String	搜索关键词
`search_result_count`	int	搜索结果数量
`search_content_type`	String	搜索列表类型：`video` / `novel` / `comic` / `post` / `short_drama`；未接搜索推荐引擎传 `""`
`search_trace_id`	String	搜索引擎 trace ID；未接搜索推荐引擎传 `""`
`search_id`	String	可视范围内的搜索结果 ID，多个英文逗号分隔（不是搜索会话 ID）；未接搜索推荐引擎传 `""`

6.14 关键词点击 — `KeywordClickEvent`

java

import com.datapluse.analyticssdk.entity.KeywordClickEvent;
import com.datapluse.analyticssdk.enums.ClickItemTypeEnum;

AnalyticsSdk.getInstance().track(new KeywordClickEvent(
    "搞笑视频合集",        // 关键词
    "vid_001",            // 点击内容 ID
    ClickItemTypeEnum.VIDEO, // VIDEO / NOVEL / COMIC / POST / SHORT_DRAMA
    3                     // 点击位置（从 0 开始）
));

payload 字段

字段	类型	说明
`keyword`	String	搜索关键词
`click_item_id`	String	点击内容 ID
`click_item_type_key`	String	内容类型标识：`video` / `novel` / `comic` / `post` / `short_drama`
`click_item_type_name`	String	内容类型展示名，如 `"视频"` / `"帖子"` / `"短剧"`
`click_position`	int	点击位置（从 0 开始）
`search_trace_id`	String	搜索引擎 trace ID，默认 `""`

注意： clickItemType 枚举在 payload 中拆分为 click_item_type_key 和 click_item_type_name 两个字段。

7. Session 管理

SDK 默认自动管理 Session（30 分钟超时），通常无需手动干预。

7.1 生命周期通知

enableAutoPageTrack = true 时（默认），SDK 通过 ActivityLifecycleObserver 自动处理前后台切换，无需手动调用。

只有在 enableAutoPageTrack = false 的情况下，才需要手动通知 SDK：

java

import com.datapluse.analyticssdk.manager.SessionManager;

// App 进入后台时调用
SessionManager.getInstance().onAppBackground();

// App 回到前台时调用（后台超过 30 分钟则自动生成新 Session）
SessionManager.getInstance().onAppForeground();

7.2 Session 新建时机

场景	说明
冷启动	每次 `init()` 必定生成新 sid
后台超时回前台	后台停留 > 30 分钟，回前台时生成新 sid
行为超时	上次用户行为距今 > 30 分钟，下次上报时生成新 sid

7.3 服务端上报场景获取 sid

sid（会话 ID）由客户端 SDK 在初始化时自动生成，格式为 32 位十六进制字符串（UUID v4 去掉 -）。
服务端自行上报事件时，sid 必须从客户端获取后回传，不能由服务端自行生成，否则与客户端事件流断链，无法关联同一会话。

java

import com.datapluse.analyticssdk.manager.SessionManager;

// 在需要上报到服务端的场景，将当前 sid 随业务请求一起传给后端
String currentSid = SessionManager.getInstance().getSessionId();
// 将 currentSid 附加到你的 API 请求参数中，由服务端上报时使用

getSessionId() 会自动检查行为超时，调用即视为一次用户行为记录，返回值始终是当前有效的 sid。

8. 页面名称映射

SDK 自动追踪时通过 Activity 类名生成 pageKey（如 MainActivity → /main）。可通过 PageNameMapper 自定义：

java

import com.datapluse.analyticssdk.manager.PageNameMapper;
import java.util.HashMap;

// 批量配置
HashMap<String, String> pages = new HashMap<>();
pages.put("/main",    "首页");
pages.put("/detail",  "详情页");
pages.put("/user",    "个人中心");
pages.put("/search",  "搜索页");
PageNameMapper.addMappings(pages);

// 动态新增单条
PageNameMapper.addMapping("/live", "直播间");

// 完全自定义 pageKey 生成逻辑
PageNameMapper.setPageKeyProvider(activity -> {
    // 返回 null 时回退到默认规则
    if (activity instanceof LiveActivity) return "/live";
    return null;
});

默认 pageKey 规则（无自定义时）：

Activity 类名	pageKey（内部）	实际上报值
`MainActivity`	`/main`	`main`
`HomeActivity`	`/home`	`home`
`DetailActivity`	`/detail`	`detail`
`UserActivity`	`/user`	`user`
`DiscoverActivity`	`/discover`	`discover`
其他（去掉 Activity 后缀转小写）	`/{name}`	`{name}`

9. 自动追踪说明

enableAutoPageTrack = true（AutoTrackMode.FULL）时，SDK 自动监听 Activity/Fragment 页面生命周期，上报页面展示与点击，并维护页面停留：

触发时机	行为
页面进入	上报 `AppPageViewEvent`，并初始化该页面的广告去重缓存
页面离开	结束页面停留，清除该页面的广告去重缓存
页面点击	自动上报 `PageClickEvent`（默认 300ms 节流；滑动 / 取消手势不触发）
触摸 / 滚动 / 捏合	累计会话行为统计

页面点击由 FULL 模式自动采集，无需再手动重复上报；未启用自动追踪时也可手动 track(new PageClickEvent(...))。导航菜单行为调用 trackNavigation()。SDK 初始化、生命周期、网络及会话汇总事件继续自动处理。

如业务页面有特殊需求，可在 Fragment 的 onViewCreated() 或 onResume() 中手动上报页面展示：

java

// Fragment 手动页面追踪示例
AnalyticsSdk.getInstance().track(new AppPageViewEvent(
    "vip",          // userType
    "/home_tab",    // pageKey（建议用有语义的 key，而非 Activity 类名）
    "首页Tab",
    referrerPageKey, referrerPageName,
    "/home_tab", "首页Tab",
    0,              // pageLoadTime
    ""              // recommendTraceId
));

10. 播放器自动埋点（PlayerTracker）

PlayerTracker 是独立的播放器代理模块，支持 ExoPlayer、MediaPlayer、IjkPlayer 无侵入接入，自动上报 VideoEvent，不修改任何现有代码。

依赖声明

播放器库依赖均为 compileOnly，AAR 不内置任何播放器库。使用哪个播放器就引入对应 Adapter：

groovy

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar'])

    // ExoPlayer（按需引入）
    implementation 'androidx.media3:media3-exoplayer:1.3.1'

    // IjkPlayer（按需引入；JCenter 已关闭，需添加 Aliyun Maven 镜像）
    implementation 'tv.danmaku.ijk.media:ijkplayer-java:0.8.8'
}

未引入的播放器库对应的 Adapter 类不会被加载，无需为未使用的播放器添加依赖。

ExoPlayer 接入（全自动）

play / pause / seek / complete / buffer / error / 视频切换均自动触发，无需手动通知：

java

import com.datapluse.analyticssdk.player.*;
import com.datapluse.analyticssdk.player.adapters.ExoPlayerAdapter;
import com.datapluse.analyticssdk.enums.VideoContentTypeEnum;

PlayerVideoMeta meta = new PlayerVideoMeta.Builder()
    .videoId("v001").videoTitle("测试视频")
    .videoTypeId("1").videoTypeName("剧情")
    .videoTagKey("tag_romance").videoTagName("爱情")
    .mediaId("m001")
    .videoContentType(VideoContentTypeEnum.VIDEO)
    .recommendTraceId("")   // 非推荐场景传 ""
    .build();

PlayerTracker tracker = PlayerTracker.attach(new ExoPlayerAdapter(exoPlayer), meta);

// Activity/Fragment onDestroy 时释放
@Override
protected void onDestroy() {
    tracker.detach();
    super.onDestroy();
}

播放列表场景（视频切换自动处理）：

java

// MetadataProvider 始终返回当前正在播的视频 meta
// ExoPlayer 切换视频时 SDK 自动：上报旧视频末尾事件 → 重置 playDuration → 拉取新 meta
PlayerTracker tracker = PlayerTracker.attach(
    new ExoPlayerAdapter(exoPlayer),
    () -> getCurrentVideoMeta()
);

MediaPlayer / IjkPlayer 接入

MediaPlayer/IjkPlayer 无原生 play/pause 回调，需在 start()/pause() 后手动通知：

java

import com.datapluse.analyticssdk.player.adapters.MediaPlayerAdapter;

PlayerTracker tracker = PlayerTracker.attach(new MediaPlayerAdapter(mediaPlayer), meta);

mediaPlayer.start();
tracker.notifyPlay();   // 必须手动调

mediaPlayer.pause();
tracker.notifyPause();

// 切换视频时：SDK 自动上报旧视频末尾事件 + 重置 playDuration 计时 + 切换 meta
tracker.updateMeta(new PlayerVideoMeta.Builder()
    .videoId("v002").videoTitle("第二集")
    // ... 其余字段
    .build());

完整配置（Builder）

java

PlayerTracker tracker = new PlayerTracker.Builder()
    .adapter(new ExoPlayerAdapter(exoPlayer))
    .metadataProvider(() -> getCurrentVideoMeta())
    .config(PlayerEventConfig.only(
        VideoEventEnum.VIDEO_PLAY,
        VideoEventEnum.VIDEO_PAUSE,
        VideoEventEnum.VIDEO_COMPLETE))
    .playDurationProvider(() -> myPlayer.getPlayedSeconds())   // 可选：自定义计时
    .playProgressProvider(() -> myPlayer.getProgressPercent()) // 可选：自定义进度
    .build();

PlayerEventConfig 说明

工厂方法	开启的事件
`PlayerEventConfig.defaults()`	VIDEO_PLAY / VIDEO_PAUSE / VIDEO_COMPLETE / VIDEO_FORWARD / VIDEO_REWIND
`PlayerEventConfig.only(...)`	仅指定事件
`PlayerEventConfig.all()`	defaults + BUFFER_START + BUFFER_END + VIDEO_ERROR

稳定性保障

全链路 try-catch，适配器内任何异常仅打 Log，不影响播放器正常运行
tracker.detach() 幂等，可安全多次调用，任意时机调用不抛异常
MetadataProvider.getMetadata() 返回 null 时使用空 meta 兜底，不崩溃
播放器库依赖为 compileOnly，不打入 AAR，不干扰宿主 App 的播放器版本

11. 枚举值参考

EventType — 事件类型

SDK 提供预置事件类型常量（标准 Java enum），不支持自定义字符串。

java

import com.datapluse.analyticssdk.enums.EventType;

EventType.AD_IMPRESSION.getEvent();   // "ad_impression"
EventType.APP_PAGE_VIEW.getKey();     // "app_page_view"

// 查找预置类型
EventType t = EventType.fromEvent("ad_impression");  // 返回 EventType.AD_IMPRESSION
EventType.fromEvent("unknown");                       // 返回 null

VideoEventEnum — 视频行为

支持预置常量，也可通过 of(String key) 传入自定义字符串（key 只允许字母、数字、_、-，不合法时抛 IllegalArgumentException）。

java

VideoEventEnum.VIDEO_PLAY;                  // 预置常量
VideoEventEnum.of("video_repost");          // 自定义
VideoEventEnum.fromKey("video_play");       // 查找预置常量，找不到返回 null

枚举值	字符串值	说明
`VIDEO_PLAY`	`video_play`	播放
`VIDEO_PAUSE`	`video_pause`	暂停
`VIDEO_COMPLETE`	`video_complete`	播放完成
`VIDEO_FORWARD`	`video_forward`	快进
`VIDEO_REWIND`	`video_rewind`	快退
`VIDEO_SHARE`	`video_share`	分享

VideoContentTypeEnum — 视频内容类型

支持预置常量，也可通过 VideoContentTypeEnum.of("live_stream") 传入自定义字符串。

枚举值	字符串值
`VIDEO`	`video`
`SHORT_VIDEO`	`short_video`
`POST_VIDEO`	`post_video`

ReadBehaviorEnum — 阅读行为

支持预置常量，也可通过 ReadBehaviorEnum.of("bookmark") 传入自定义字符串。

枚举值	字符串值	说明
`VIEW`	`view`	展示
`PAGE_NEXT`	`page_next`	下一页
`PAGE_PREV`	`page_prev`	上一页
`COMPLETE`	`complete`	读完

AdTypeEnum — 广告类型

支持预置常量，也可通过 AdTypeEnum.of("interstitial") 传入自定义字符串（字段名为 label，对应 getLabel()）。

枚举值	字符串值
`ICON`	`icon`
`BANNER`	`banner`
`FEED`	`feed`
`PLAYER`	`player`
`SPLASH`	`splash`
`TEXT`	`text`

RecommendContentTypeEnum — 推荐内容类型

支持预置常量，也可通过 RecommendContentTypeEnum.of("live") 传入自定义字符串。

枚举值	字符串值
`VIDEO`	`video`
`NOVEL`	`novel`
`COMIC`	`comic`

ClickItemTypeEnum — 搜索点击内容类型

支持预置常量，也可通过 ClickItemTypeEnum.of("audio") 传入自定义字符串。

枚举值	字符串值
`VIDEO`	`video`
`NOVEL`	`novel`
`COMIC`	`comic`
`POST`	`post`
`SHORT_DRAMA`	`short_drama`

DramaPlayBehaviorEnum — 剧集播放行为

枚举值	字符串值	说明
`EP_VIEW`	`ep_view`	展示
`EP_PLAY`	`ep_play`	播放
`EP_PAUSE`	`ep_pause`	暂停
`EP_FORWARD`	`ep_forward`	快进
`EP_REWIND`	`ep_rewind`	快退
`EP_COMPLETE`	`ep_complete`	播放完成
`EP_SHARE`	`ep_share`	分享

UserTypeEnum — 用户类型

支持预置常量，也可通过 UserTypeEnum.of("svip") 传入自定义字符串。

枚举值	字符串值
`NORMAL`	`normal`
`VIP`	`vip`

AuthTypeEnum — 登录方式

支持预置常量，也可通过 AuthTypeEnum.of("apple") 传入自定义字符串。

枚举值	字符串值
`PHONE`	`phone`
`EMAIL`	`email`
`WECHAT`	`wechat`

OrderTypeEnum — 订单类型

支持预置常量，也可通过 OrderTypeEnum.of("subscription") 传入自定义字符串。

枚举值	字符串值
`NORMAL`	`normal`
`GIFT`	`gift`
`RECHARGE`	`recharge`

PayTypeEnum — 支付方式

支持预置常量，也可通过 PayTypeEnum.of("union_pay") 传入自定义字符串。

枚举值	字符串值
`ALIPAY`	`alipay`
`WECHAT`	`wechat`
`APPLE_PAY`	`apple_pay`

CurrencyEnum — 货币类型

支持预置常量，也可通过 CurrencyEnum.of("JPY") 传入自定义字符串。

枚举值	字符串值
`CNY`	`CNY`
`USD`	`USD`
`EUR`	`EUR`

ConsumeReasonEnum — 金币消耗原因

支持预置常量，也可通过 ConsumeReasonEnum.of("unlock") 传入自定义字符串。

枚举值	字符串值
`PURCHASE`	`purchase`
`GIFT`	`gift`
`REWARD`	`reward`

支持预置常量，也可通过 BannerEventEnum.of("swipe") 传入自定义字符串。

枚举值	字符串值
`SHOW`	`show`
`CLICK`	`click`
`DISMISS`	`dismiss`

12. 调试

业务方通过统一开关控制全部 SDK 日志（含完整请求/响应及警告、错误）；初始化前设置，运行中也可修改。Release AAR 默认关闭。

java

AnalyticsSdk.setLoggingEnabled(true);   // 开启
AnalyticsSdk.setLoggingEnabled(false);  // 关闭

固定 tag AnalyticsSdkHttp 打印实际 POST URL、请求头、完整签名后 JSON 请求体以及响应状态/响应体（分段输出，不含签名密钥）。复现上报时导出日志交给后台：

bash

adb logcat -v raw 'AnalyticsSdkHttp:D' '*:S' > sdk-http.log

查看其他 SDK 状态日志：

bash

adb logcat | grep -E "AnalyticsSdk|SessionManager|ActivityLifecycleObserver|DomainManager"

关键 log tag：

tag	内容
`AnalyticsSdkHttp`	实际上报 HTTP 请求/响应（含 `event_sig` 的完整批次 JSON）
`AnalyticsSdk`	上报成功/失败、配置解析、域名选择
`SessionManager`	Session 新建、超时
`DomainManager`	测速结果、最快域名

配置参数汇总

参数	值
自动上报间隔	5 秒
触发立即上报阈值	队列满 10 条
阈值触发防抖	1100ms（突发事件合并为单次请求）
单批最大上报条数	500 条
队列最大容量	5000 条
Session 超时	30 分钟
域名测速超时	5 秒
失败重试：基础延迟 / 最大延迟	2s / 60s
单条事件最大体积	300 KB
单批最大体积	5 MB

13. 销毁与资源释放

SDK 不会自动销毁。 如需主动释放资源（关闭线程池、注销监听），可在合适时机调用 dispose()。

java

AnalyticsSdk.getInstance().dispose();

dispose() 内部操作：

将队列中的剩余事件立即上报（flush()）
取消定时上报和退避重试任务
关闭上报线程池和调度线程池
关闭域名测速线程池
注销 Activity 生命周期观察者等监听

注意： Application.onTerminate() 在真实 Android 设备上永远不会被调用（仅限模拟器进程环境），不要在此处调用 dispose()。大多数场景下无需手动调用，进程退出时 OS 会回收所有资源；如业务有明确的 SDK 关闭节点（如账号切换、动态卸载模块），再调用即可。

主线程调用安全： dispose() 在主线程调用时会直接 shutdownNow() 不阻塞，不会触发 ANR。

14. 版本更新说明

v1.5.1（2026-09-18）

同步 Flutter 1.5.1 业务增量；sdk_version = 1.5.1，fp_version = 4.0.0。
帖子创建时间 payload 改为 post_create_time；Java 参数 createTime 保持兼容。
DramaPlayBehaviorEnum 新增 EP_COMPLETE / EP_SHARE；ClickItemTypeEnum 新增 POST / SHORT_DRAMA；关键词搜索支持 post / short_drama。
约定：非空 uid ≥ 4；小说 page_no=0 仅有声小说（当前校验器仍会移除 0）。
正式交付文件为 analytics-sdk-1.5.1.aar（与 AGP 4.2.2 命名 AAR 相同）。

完整变更与升级步骤见更新日志。

v1.4.9（2026-09-16）

指纹规则升级为 fp_version 4.0.0：去掉 language / timezone，首次生成并持久化后持续复用。
修复重复初始化时指纹丢失 / 存储失败未重试的问题。
事件 API 与初始化参数保持兼容；服务端需按 fp_version 区分 v3→v4。
正式交付文件为 analytics-sdk-1.4.9.aar（AGP 4.2.2 旧工具链宿主可使用同一 AAR）。

完整变更与升级步骤见更新日志。

v1.4.8（2026-09-08）

新增帖子 / 剧集事件与 VideoEvent 的 post_video / play_speed 扩展。
修复正式配置顶层 signKey 解析，补齐客户端事件签名。
保留 FULL 模式自动页面点击及手动点击 API；移除全部 IM 事件。
Demo 测试台移除手动点击测试与 page_click 控制台回显，SDK 自动上报照常保留。
支持完整上报请求/响应日志，由 AnalyticsSdk.setLoggingEnabled 统一控制。
Release AAR 内嵌 OAID / 华为 / 荣耀标识库，宿主无需重复引入。

完整变更与升级步骤见更新日志。

Analytics SDK Android 接入指南 ​

下载 SDK ​

目录 ​

1. 环境要求 ​

2. 集成 AAR ​

设备指纹与升级 ​

混淆配置（ProGuard/R8） ​

3. 初始化 ​

参数说明 ​

4. 配置刷新 ​

5. 用户管理 ​

6. 事件上报 ​

事件 JSON 结构 ​

page_key 格式说明 ​

6.1 页面展示 — AppPageViewEvent ​

6.2 页面点击 — PageClickEvent ​

6.3 导航 — NavigationEvent ​

6.4 视频行为 — VideoEvent ​

6.15 帖子展示 — PostEvent ​

6.16 剧集播放 — DramaEvent ​

6.17 剧集状态变更 — DramaStatusChangeEvent ​

6.5 小说阅读 — NovelEvent ​

6.6 漫画阅读 — ComicEvent ​

6.7 广告展示 — AdImpressionEvent ​

6.8 广告点击 — AdClickEvent ​

6.9 广告通用事件 — AdvertisingEvent ​

6.10 推荐列表展示 — RecommendListViewEvent ​

6.11 推荐列表点击 — RecommendListClickEvent ​

6.12 应用安装 — AppInstallEvent ​

6.13 关键词搜索 — KeywordSearchEvent ​

6.14 关键词点击 — KeywordClickEvent ​

7. Session 管理 ​

7.1 生命周期通知 ​

7.2 Session 新建时机 ​

7.3 服务端上报场景获取 sid ​

8. 页面名称映射 ​

9. 自动追踪说明 ​

10. 播放器自动埋点（PlayerTracker） ​

依赖声明 ​

ExoPlayer 接入（全自动） ​

MediaPlayer / IjkPlayer 接入 ​

完整配置（Builder） ​

PlayerEventConfig 说明 ​

稳定性保障 ​

11. 枚举值参考 ​

EventType — 事件类型 ​

VideoEventEnum — 视频行为 ​

VideoContentTypeEnum — 视频内容类型 ​

ReadBehaviorEnum — 阅读行为 ​

AdTypeEnum — 广告类型 ​

RecommendContentTypeEnum — 推荐内容类型 ​

ClickItemTypeEnum — 搜索点击内容类型 ​

DramaPlayBehaviorEnum — 剧集播放行为 ​

UserTypeEnum — 用户类型 ​

AuthTypeEnum — 登录方式 ​

OrderTypeEnum — 订单类型 ​

PayTypeEnum — 支付方式 ​

CurrencyEnum — 货币类型 ​

ConsumeReasonEnum — 金币消耗原因 ​

BannerEventEnum — Banner 行为 ​

12. 调试 ​

配置参数汇总 ​

13. 销毁与资源释放 ​

14. 版本更新说明 ​

v1.5.1（2026-09-18） ​

v1.4.9（2026-09-16） ​

v1.4.8（2026-09-08） ​

Analytics SDK Android 接入指南

下载 SDK

目录

1. 环境要求

2. 集成 AAR

设备指纹与升级

混淆配置（ProGuard/R8）

3. 初始化

参数说明

4. 配置刷新

5. 用户管理

6. 事件上报

事件 JSON 结构

page_key 格式说明

6.1 页面展示 — `AppPageViewEvent`

6.2 页面点击 — `PageClickEvent`

6.3 导航 — `NavigationEvent`

6.4 视频行为 — `VideoEvent`

6.15 帖子展示 — `PostEvent`

6.16 剧集播放 — `DramaEvent`

6.17 剧集状态变更 — `DramaStatusChangeEvent`

6.5 小说阅读 — `NovelEvent`

6.6 漫画阅读 — `ComicEvent`

6.7 广告展示 — `AdImpressionEvent`

6.8 广告点击 — `AdClickEvent`

6.9 广告通用事件 — `AdvertisingEvent`

6.10 推荐列表展示 — `RecommendListViewEvent`

6.11 推荐列表点击 — `RecommendListClickEvent`

6.12 应用安装 — `AppInstallEvent`

6.13 关键词搜索 — `KeywordSearchEvent`

6.14 关键词点击 — `KeywordClickEvent`

7. Session 管理

7.1 生命周期通知

7.2 Session 新建时机

7.3 服务端上报场景获取 sid

8. 页面名称映射

9. 自动追踪说明

10. 播放器自动埋点（PlayerTracker）

依赖声明

ExoPlayer 接入（全自动）

MediaPlayer / IjkPlayer 接入

完整配置（Builder）

PlayerEventConfig 说明

稳定性保障

11. 枚举值参考

EventType — 事件类型

VideoEventEnum — 视频行为

VideoContentTypeEnum — 视频内容类型

ReadBehaviorEnum — 阅读行为

AdTypeEnum — 广告类型

RecommendContentTypeEnum — 推荐内容类型

ClickItemTypeEnum — 搜索点击内容类型

DramaPlayBehaviorEnum — 剧集播放行为

UserTypeEnum — 用户类型

AuthTypeEnum — 登录方式

OrderTypeEnum — 订单类型

PayTypeEnum — 支付方式

CurrencyEnum — 货币类型

ConsumeReasonEnum — 金币消耗原因

BannerEventEnum — Banner 行为

12. 调试

配置参数汇总

13. 销毁与资源释放

14. 版本更新说明

v1.5.1（2026-09-18）

v1.4.9（2026-09-16）

v1.4.8（2026-09-08）