跳到主要内容

Launcher运营API

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件面向Launcher运营API的使用者与维护者，系统化梳理广告配置、广告投放、渠道管理、播放统计等核心能力的接口规范与实现要点。文档以三级配置架构为主线，结合规则引擎与传统限制模式，覆盖资源绑定、策略匹配、频控与缓存、播放上报与统计分析等关键流程，并给出投放示例、配置指南与效果分析方法，帮助快速落地与优化。

项目结构​

  • 文档侧：位于 docs/launcher 下，包含三级配置、渠道限制、广告位与资源、播放统计等专题文档。
  • API侧：位于 yudao-module-launcher/yudao-module-launcher-api，提供RPC接口定义与通用枚举、常量、错误码。
  • 业务侧：位于 yudao-module-launcher/yudao-module-launcher-biz，包含控制器、服务、数据访问、定时任务、Kafka消费与TDengine存储等。

Mermaid Diagram Code:

graph TB
subgraph "文档"
LInfo["launcher-info.md<br/>三级配置与审批流程"]
LAdvert["launcher-advert.md<br/>资源与策略限制"]
LChannel["launcher-channel.md<br/>渠道关联限制"]
LPlayCount["ad-play-count.md<br/>播放统计分析"]
end
subgraph "API模块"
LCfgApi["LauncherConfigApi.java<br/>RPC接口"]
EAdType["AdTypeEnum.java<br/>广告类型枚举"]
ELAET["LauncherAdPlayTypeEnum.java<br/>播放类型枚举"]
EApiConst["ApiConstants.java<br/>服务名/前缀/版本"]
EErr["ErrorCodeConstants.java<br/>错误码"]
end
LInfo --> LAdvert
LAdvert --> LChannel
LInfo --> LCfgApi
LCfgApi --> EAdType
LCfgApi --> ELAET
LCfgApi --> EApiConst
LCfgApi --> EErr

图表来源

章节来源

核心组件​

  • RPC接口：LauncherConfigApi 提供文件使用状态查询等能力，作为App侧与Launcher服务交互的入口。
  • 枚举体系：
    • 广告类型 AdTypeEnum：视频、图片、收藏、文本。
    • 播放类型 LauncherAdPlayTypeEnum：默认、三方（特定客户定制）。
    • 常量 ApiConstants：服务名、前缀、版本。
    • 错误码 ErrorCodeConstants：统一错误码定义。
  • 文档支撑：三级配置、资源与策略、渠道限制、播放统计等文档，明确业务流程与约束。

章节来源

架构总览​

Launcher运营API采用三层配置架构与规则引擎驱动的策略匹配，结合Redis频控与TDengine统计存储，形成从配置到执行再到分析的闭环。

Mermaid Diagram Code:

sequenceDiagram
participant Dev as "终端设备(Launcher)"
participant Biz as "Launcher模块"
participant Rule as "规则引擎"
participant Redis as "Redis缓存"
participant TD as "TDengine统计"
Dev->>Biz : "请求广告配置(包名, 版本号)"
Biz->>Biz : "识别LauncherID(一级配置)"
loop "遍历广告位(二级配置)"
Biz->>Biz : "获取广告位详情"
Note right of Biz : "匹配三级策略"
Biz->>Rule : "规则引擎匹配(matchBusinessIds)"
Rule-->>Biz : "返回命中资源策略ID"
alt "未命中"
Biz->>Biz : "尝试默认/无限制策略"
end
Biz->>Redis : "检查总量限制"
end
Biz->>Biz : "组装最终广告位列表(JSON)"
Biz-->>Dev : "返回配置(含素材URL/跳转动作)"
Dev->>TD : "异步上报播放/点击数据"

图表来源

章节来源

详细组件分析​

广告配置接口​

  • 接口定位：提供与App侧交互的RPC接口，用于查询文件在Launcher中的使用状态等。
  • 接口路径：/launcherConfig/checkFileUseOnLauncher
  • 请求参数
    • fileId：文件ID（Long，可空）
  • 返回值：CommonResult<Boolean>，表示文件是否在Launcher中使用
  • 使用建议
    • 在素材删除前调用该接口进行依赖检查，避免资源悬挂
    • 结合审批状态与变更状态，确保只对已生效配置进行操作

章节来源

广告投放接口​

  • 请求入口：设备启动时携带包名与版本号发起请求
  • 处理流程
    1. 识别Launcher版本（一级配置）
    2. 遍历广告位（二级配置）
    3. 匹配策略（三级配置）
      • 规则引擎优先：基于设备画像与规则中心的复杂规则
      • 传统限制：渠道、MAC、地区三类限制（Legacy）
      • 单资源互斥：同一广告位仅启用一个资源
    4. 频控检查：依据Redis计数器判断是否超出总量限制
    5. 组装返回：JSON结构包含素材地址、跳转动作等
  • 返回格式：结构化JSON（字段由业务配置决定）

章节来源

渠道管理接口​

  • 功能概述：在三级配置中设置当前广告位在哪些渠道生效，支持列表查询、筛选、新增关联、导出、批量删除、取消变更等。
  • 关键字段
    • 广告位索引ID：所属广告位ID（自动填充）
    • 渠道：已有关道名称（来自设备管理模块）
    • 变更状态：审批/生效状态
  • 操作说明
    • 导出：支持异步导出（大数据量）
    • 批量删除/删除：需审批
    • 取消数据变更：撤销未审批通过的修改

章节来源

播放统计接口​

  • 数据来源：设备端异步上报，TDengine存储
  • 分析维度：按天/月聚合，支持三方播放完成、错误、跳过、跳转、APP打开等事件
  • 使用建议
    • 结合广告位与策略标签，对比不同渠道/地区的播放效果
    • 关注异常波动（如播放错误率上升），配合规则引擎与频控策略进行优化

章节来源

广告类型枚举​

  • 枚举项
    • VIDEO：视频
    • IMAGE：图片
    • FAV：收藏（快捷方式）
    • TEXT：字幕/文本
  • 使用场景
    • 13号广告位：收藏（快捷方式）
    • 14号广告位：字幕（滚动文字）
    • 其他位：视频/图片/文本等

章节来源

播放类型配置​

  • 枚举项
    • DEFAULT：默认
    • THIRD_GERMANY_COM_MEDIA_SYSTEMADSOLUTION_CUSTOM：三方（特定客户定制）
  • 用途
    • 区分不同客户的播放统计口径与上报格式

章节来源

渠道参数设置​

  • 关联模块：设备管理 - 渠道信息管理
  • 新增渠道：先在设备管理模块创建，再在Launcher三级配置中进行关联
  • 多选支持：可在新增关联时选择多个渠道

章节来源

播放记录统计​

  • 存储：TDengine
  • 分析：按天/月维度，支持多维指标（播放完成、错误、跳过、跳转、APP打开等）
  • 报表：结合规则引擎与策略标签，进行效果对比与归因分析

章节来源

运营最佳实践​

  • 投放示例
    • 规则引擎模式：配置“CPU>4核 且 内存>2GB 且 地区=巴西”，精准触达目标设备
    • 传统限制模式：按渠道/地区/MAC进行简单过滤，适合快速验证
  • 渠道配置指南
    • 先在设备管理创建渠道，再在Launcher三级配置中关联
    • 使用筛选条件快速定位广告位与渠道关系
  • 播放效果分析
    • 对比不同策略的播放完成率、点击率、错误率
    • 结合频控与缓存策略，避免过度推送导致的异常

章节来源

依赖分析​

  • 组件耦合
    • LauncherConfigApi 依赖 ApiConstants（服务名/前缀/版本）、AdTypeEnum、LauncherAdPlayTypeEnum、ErrorCodeConstants
    • 业务侧通过规则引擎、Redis、TDengine实现策略匹配、频控与统计
  • 外部依赖
    • 规则引擎：用于复杂设备画像匹配
    • Redis：用于总量限制计数
    • TDengine：用于播放统计数据的高效存储与查询

Mermaid Diagram Code:

classDiagram
class LauncherConfigApi {
+checkFileUseOnLauncher(fileId) : CommonResult<Boolean>
}
class ApiConstants {
+NAME : String
+PREFIX : String
+VERSION : String
}
class AdTypeEnum {
+VIDEO
+IMAGE
+FAV
+TEXT
}
class LauncherAdPlayTypeEnum {
+DEFAULT
+THIRD_GERMANY_COM_MEDIA_SYSTEMADSOLUTION_CUSTOM
}
class ErrorCodeConstants {
+INDEX_CHANEL_NOT_EXISTS
+INDEX_MAC_NOT_EXISTS
+INDEX_REGION_NOT_EXISTS
+BASE_INFO_NOT_EXISTS
+INDEX_NOT_EXISTS
+INDEX_ADVERT_NOT_EXISTS
+LAUNCHER_IS_RUNNING
+AD_PLAY_COUNT_NOT_EXISTS
+AD_PLAY_DEVICE_COUNT_NOT_EXISTS
+EXEC_RECORD_NOT_EXISTS
}
LauncherConfigApi --> ApiConstants : "使用"
LauncherConfigApi --> AdTypeEnum : "使用"
LauncherConfigApi --> LauncherAdPlayTypeEnum : "使用"
LauncherConfigApi --> ErrorCodeConstants : "使用"

图表来源

章节来源

性能考虑​

  • 缓存策略：利用Redis缓存总量限制计数，降低数据库压力
  • 查询优化：规则引擎匹配与默认策略回退应尽量减少跨库扫描
  • 统计分析：TDengine按天/月聚合，避免大表全量扫描
  • 异步导出：大批量导出采用异步任务，提升用户体验

故障排查指南​

  • 常见错误码
    • 广告位与渠道/地区/MAC关联不存在
    • Launcher基本信息不存在
    • 广告位不存在
    • 广告位与广告关联不存在
    • 该Launcher配置正在审批中
    • 播放统计不存在或库缺失
    • 执行记录不存在
  • 排查步骤
    • 确认一级配置（包名/版本）是否存在
    • 检查二级配置（广告位）与三级配置（策略/资源）是否完整
    • 核对渠道/地区/MAC限制是否正确
    • 检查审批状态与变更状态
    • 关注Redis计数器与TDengine统计入库情况

章节来源

结论​

Launcher运营API围绕三级配置与规则引擎构建，实现了从策略匹配、资源绑定到播放统计的全链路能力。通过清晰的接口定义、完善的枚举与错误码体系，以及与Redis/TDengine的协同，能够支撑高并发的广告投放与精细化运营分析。建议在实践中优先采用规则引擎模式，结合渠道/地区/MAC等限制进行分层投放，并持续通过播放统计进行效果归因与策略迭代。

附录​

  • 术语
    • 一级配置：Launcher基础信息（包名、版本号）
    • 二级配置：广告位管理（开屏、首页Banner等）
    • 三级配置：资源绑定与投放策略（规则引擎/传统限制）
  • 参考文档
用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答