Launcher信息与广告位配置

核心概念：桌面管理 | Launcher信息与广告位配置 | 概览

本模块是广告推送配置的核心入口，采用清晰的 三级配置架构，帮助您从整体到局部精确控制广告投放。

• 一级配置 (基础信息)：管理 Launcher 应用的包名、版本号等基础属性。
• 二级配置 (广告位管理)：在特定 Launcher 版本下定义广告位（如开屏、首页），支持分组管理。
• 三级配置 (策略与资源)：针对具体广告位，绑定素材资源并设置投放策略（MAC/渠道/地区限制）。

---

核心概念：桌面管理 | Launcher信息与广告位配置 | 一级配置：Launcher基础信息

一级配置：Launcher基础信息

在Launcher信息管理的一级配置页面中，主要用于管理 Launcher 应用本身的身份信息。系统允许存在多条相同的包名或版本号记录，以便支持不同的业务场景或测试需求。

页面概览

页面上方列表展示了所有已登记的 Launcher 基础信息。

核心功能

• 新增/编辑：配置 Launcher 的 名称、包名 和 版本号。
• 多版本支持：允许创建多条记录，即使包名和版本号相同（系统通过唯一 ID 区分），方便进行灰度测试或多版本并行管理。
• 审批管理：关键信息的变更需通过审批流程（详情见下文 审批与状态说明）。

---

核心概念：桌面管理 | Launcher信息与广告位配置 | 二级配置：广告位管理

二级配置：广告位管理

在Launcher信息管理的二级配置页面中，点击一级列表中的任意一行，页面下方将展开该 Launcher 对应的 广告位配置列表。 此处定义了该 Launcher 版本下包含哪些具体的广告展示位置（Ad Slot）。

核心概念

• 归属关系：广告位严格属于某一个一级 Launcher 信息。
• 分组管理：
  • 为了便于管理大量广告位，系统引入了 分组 概念。
  • 在创建广告位时，您可以选择放入 已存在的分组 或 手动输入新分组。
  • 唯一性约束：同一分组下的广告位名称不能重复，确保引用的唯一性。这一抽象层设计极大简化了分类管理的复杂度。

广告位定义与扩展

随着业务发展，“广告位”的概念在系统中经历了泛化。它不仅指代物理存在的展示位，还涵盖了各类统计埋点状态。

• 配置类广告位：指实际存在的、可配置资源的广告位。

  • 例如：1-14号广告位、Banner 广告位、开屏广告。
  • 操作：您可以在此页面进行新增、编辑和资源配置。

• 统计类广告位 (虚拟)：指代三方广告的执行状态，仅用于数据上报与统计分析，无需也无法在此处配置。

  • 涵盖类型：三方请求素材失败、三方播放完成、三方播放错误、三方播放跳过、三方播放跳转、三方 APP 打开、三方获取素材成功、三方 APP 打开(艾科统计)。
  • 注意：这些“广告位”由设备端直接上报，您在后台只能在 广告播放数据分析 中看到相关数据，而不需要在配置页面创建它们。

操作指南

1. 新增广告位：点击 新增，填写广告位名称、选择/新建分组。
2. 配置入口：点击广告位列表右侧的 编辑 按钮，即可进入 三级配置页面（包含资源绑定与投放限制）。

---

核心概念：桌面管理 | Launcher信息与广告位配置 | 三级配置入口

三级配置入口

在Launcher信息管理的三级配置入口中，在二级广告位列表中点击 编辑，将弹出一个综合配置窗口。这就是 三级配置页面。

在此页面中，您可以：

1. 绑定资源：上传图片、视频、字幕等素材（详情请跳转 三级配置：资源与策略）。
2. 设置限制：配置广告投放的 MAC、渠道、地区限制（详情请跳转 三级配置：资源与策略）。

注意：三级配置遵循 “单资源互斥” 原则。同一个广告位下可以配置多个资源备选，但同一时间只能 启用 一个。启用 B 资源会自动禁用 A 和 C 资源。

---

核心概念：桌面管理 | Launcher信息与广告位配置 | 审批与状态说明

审批与状态说明

关于Launcher信息管理的审批与状态说明：

由于本模块涉及系统核心配置，非管理员的修改需要经过审批流程。您可以在 审批中心 查看您的申请进度。

业务审批状态

• 未开始(草稿)：数据已保存但未提交审批。
• 审批中：数据已提交，正在等待管理员审核。
• 审批通过：审核通过，数据已生效。
• 审批不通过：审核被拒绝，需重新修改或取消。
• 已取消：申请被主动取消。

业务模块信息变更状态

• 未生效：新建数据，尚未生效。
• 已生效：数据已审核通过并生效。
• 已生效且做修改标记：在已生效数据基础上进行了修改，正在审批中。
• 已生效且做移除标记：申请删除已生效数据，正在审批中。
• 已生效且修改状态为启用：申请启用该配置，正在审批中。
• 已生效且修改状态为禁用：申请禁用该配置，正在审批中。

---

核心概念：桌面管理 | Launcher信息与广告位配置 | 4. 请求处理流程 (Launcher广告)

4. 请求处理流程 (Launcher广告)

4.1 简易流程图 (用户视角)

Mermaid Diagram Code:

sequenceDiagram
    participant Device as "终端设备 (Launcher)"
    participant Server as "云端服务器"

    Device->>Server: "1. 启动/请求广告配置"
    Server->>Server: "2. 识别Launcher版本"
    Server->>Server: "3. 匹配广告位策略 (地区/渠道)"
    Server-->>Device: "4. 返回广告位及素材内容"
    Device->>Device: "5. 展示广告"
    Device->>Server: "6. 上报播放/点击数据 (异步)"

4.2 详细处理流程 (技术视角)

Mermaid Diagram Code:

sequenceDiagram
    participant STB as "设备 (Launcher)"
    participant Biz as "Launcher模块"
    participant Rule as "规则引擎 (RuleRunUtil)"
    participant Redis as "Redis缓存"

    STB->>Biz: "1. 请求广告配置 (包名, 版本号)"
    Biz->>Biz: "2. 查找对应的 LauncherID (一级配置)"
    
    loop "3. 遍历该版本下的所有广告位"
        Biz->>Biz: "获取广告位详情 (二级配置)"
        
        Note right of Biz: "匹配三级策略"
        Biz->>Rule: "3a. 规则引擎匹配 (matchBusinessIds)"
        Rule-->>Biz: "返回命中的 资源策略ID"
        
        alt "规则未命中"
             Biz->>Biz: "3b. 尝试匹配 默认/无限制 策略"
        end
        
        Biz->>Redis: "3c. 检查总量限制"
    end
    
    Biz->>Biz: "4. 组装最终广告位列表"
    Biz-->>STB: "5. 返回 JSON 配置 (含图片URL/跳转动作)"

4.3 逻辑详解

1. 入口识别: Launcher 启动时，携带自身的包名和版本号请求服务器。服务器首先确认该版本是否存在（一级配置）。
2. 广告位遍历: 系统找出该 Launcher 版本下定义的所有广告位（如“开屏”、“首页Banner”）（二级配置）。
3. 策略匹配: 针对每个广告位，系统会检查其下挂载的所有策略（三级配置）：
   • 规则优先: 优先使用规则引擎匹配特定人群（如“仅巴西地区展示足球广告”）。
   • 互斥原则: 同一广告位下，如果命中多个策略，通常按优先级或更新时间取其一（单资源互斥）。
4. 频控检查: 如果广告设置了“限制推送设备数据”，系统会查询 Redis 中的计数器，超限则不返回该广告。
5. 数据下发: 最终返回给设备的是一个结构化的 JSON，包含每个广告位的 ID、素材地址、点击跳转动作等。