# 盛阳等三方支付EPG传参App开发需求.md ## 一、项目概述 开发一款基于橘视厅 SDK 的视频点播 App，部署于酒店 IPTV 机顶盒（Android 4.2+）。支持两种入口：EPG 调起直接播放 和 App 内浏览点播。媒资列表、详情、分集、播放地址全部由橘视厅 SDK 提供，不依赖后端。 ## 二、页面结构与流转（核心） ### 2.1 流转图 ``` EPG Intent 调起 App 独立启动 (含设备标识 + 节目编码) (无节目编码) │ │ ▼ ▼ ┌───────────────────────────────────────────────────┐ │ 启动页 │ │ 1. 解析 Intent 传参 │ │ 2. 调 init 接口 -> 获取 sign │ │ 3. 调 checkBenefits -> 获取 thirdCardNo │ │ 4. 初始化橘视厅 SDK │ └───────────────────────┬───────────────────────────┘ │ ┌────────────┴────────────┐ │ │ 有 programCode 无 programCode │ │ ▼ ▼ ┌───────────────┐ ┌───────────────┐ │ 播放页 │ │ 媒资列表页 │ │ (直接获取地址 │ │ (SDK 提供数据) │ │ 全屏播放) │ └───────┬───────┘ └───────┬───────┘ │ │ ▼ │ 返回 ┌───────────────┐ └──────────────► │ 详情页 │ │ (SDK 提供数据) │ │ 选集/介绍/播放 │ └───────┬───────┘ │ 点击播放 ▼ ┌───────────────┐ │ 播放页 │ │ (全屏播放) │ └───────┬───────┘ │ 返回/播完 ▼ 回到详情页或列表页 用户可选其他影片 ``` ### 2.2 页面职责 | 页面 | 数据来源 | 职责 | |------|---------|------| | **启动页** | 后端 init/checkBenefits | 设备初始化、权益校验、SDK 初始化 | | **媒资列表页** | **橘视厅 SDK** | 栏目分类、影片海报网格、分页加载 | | **详情页** | **橘视厅 SDK** | 影片介绍、电视剧选集列表、播放入口 | | **播放页** | **橘视厅 SDK** + MediaPlayer | 获取播放地址、全屏播放、遥控器控制 | ## 三、EPG Intent 接收（核心入口） ### 3.1 Intent 注册 ```xml ``` ### 3.2 Intent 参数 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | mac | String | 否* | 设备 MAC | | wifiMac | String | 否 | WiFi MAC | | deviceSn | String | 否 | 设备 SN | | deviceUid | String | 否* | 设备唯一标识 | | programCode | String | 否 | **节目编码。有值=直接播放，无值=进入列表** | > *mac 和 deviceUid 至少传一个，用于后端 init 接口识别设备。优先级：EPG 传入 > 本地采集。 ### 3.3 启动分支逻辑 ``` 收到 Intent │ ├─ 步骤1：收集设备标识（优先 EPG 传入，兜底本地采集） ├─ 步骤2：调 init 接口 -> 获取 sign ├─ 步骤3：调 checkBenefits -> 获取 thirdCardNo + status ├─ 步骤4：用 thirdCardNo 初始化橘视厅 SDK │ ├─ 有 programCode？ │ ├─ YES -> 调 SDK 获取播放地址 -> 跳转播放页（全屏） │ └─ NO -> 跳转媒资列表页 │ └─ 播放页返回后 -> 进入媒资列表页（用户可继续浏览） ``` ## 四、init 与 checkBenefits 接口 ### 4.1 设备初始化接口 ``` POST http://{后端地址}/api/jst/init Content-Type: application/json 请求体： { "mac": "EC:F7:2B:03:1F:97", "deviceUid": "TEST-UID-001" } 响应体： { "code": 0, "msg": "success", "sign": "OToxNzg1...", // 鉴权凭证，后续接口 Header 携带 "data": { "device": { "deviceId": 9 } } } ``` ### 4.2 权益查询接口 ``` POST http://{后端地址}/api/jst/checkBenefits Header: sign: {init 返回的 sign} Content-Type: application/json 响应体： { "code": 0, "msg": "success", "data": { "status": "ACTIVE", // ACTIVE=已激活 / UNBOUND=未绑定 "thirdCardNo": "DbzgHwPRK18pDKVZIS3AdBfQw", // 橘视厅 SDK uid 参数 "cardNo": "7D9AFE7677A758CD", "expireAt": "2026-07-29 17:25:05" } } ``` ### 4.3 心跳续期接口 ``` POST http://{后端地址}/api/jst/heartBeat Header: sign: {init 返回的 sign} // 每 30 分钟调用一次，sign 过期后需重新调 init ``` > **后端只负责以上三个接口。媒资、详情、分集、播放地址全部由橘视厅 SDK 提供。** ## 五、橘视厅 SDK 能力（媒资+播放，全部 SDK 提供） ### 5.1 SDK 初始化 checkBenefits 返回 `thirdCardNo` 后，初始化 SDK： ```java JetsenxSdk.init( agcode, // thirdCardNo（checkBenefits 返回） mac, // 设备 MAC uid, // thirdCardNo（checkBenefits 返回） "huashitv", // tenant（固定值） secret, // 密钥（由橘视厅分配） accesser, // 访问者标识（由橘视厅分配） 2, // utype（固定值） "", // extendJson "" // comboCode ); ``` ### 5.2 SDK 提供的能力 | 能力 | SDK 方法 | 说明 | |------|---------|------| | 媒资列表 | SDK 提供 | 栏目分类、影片列表、海报、分页 | | 内容详情 | SDK 提供 | 影片介绍、演员、评分等 | | 电视剧分集 | SDK 提供 | 选集列表，每集 contentcode | | 播放地址（付费） | `JetsenxSdk.getVideoUrls(productCode, programCode, callback)` | 返回 VideoInfo[]，含 720P/1080P 地址 | | 播放地址（免费） | `JetsenxSdk.getFreeVideoUrls(programCode, callback)` | parentContentType="8" 时调用 | | 产品定价 | `JetsenxSdk.getAllAssetPrices(accesser, secret, callback)` | 获取 productCode（packageCode 字段） | ### 5.3 播放地址获取要点 ``` 1. productCode = getAllAssetPrices() 返回的第一个 packageCode 2. 根据 parentContentType 选择接口： - "8" -> getFreeVideoUrls(programCode) - 其他 -> getVideoUrls(productCode, programCode) 3. 返回 VideoInfo[]，按 format 字段区分清晰度 4. programCode 必须是分集级编码（非电视剧父级编码） ``` ## 六、播放页 ### 6.1 技术方案 使用系统原生 **MediaPlayer + SurfaceView**（兼容 Android 4.2，**不用 ExoPlayer**）： - 支持 HLS（.m3u8）格式 - 全屏横屏播放 - 遥控器控制：OK键暂停/播放、左右键快进快退、返回键退出 - 播放地址带时效性 `auth_key` ### 6.2 播放完成流转 ``` 播放完成 / 用户按返回 ├── EPG 直接播放进入的 -> 返回媒资列表页 └── 详情页进入的 -> 返回详情页（可继续选集播放） ``` ## 七、技术约束（Android 4.2 兼容） | 依赖 | 版本 | 原因 | |------|------|------| | minSdk | 17 | Android 4.2 | | Retrofit | **2.6.0** | 2.9+ 传递依赖 OkHttp 3.14 不兼容 | | OkHttp | **3.12.0**（force） | 3.12.1+ 含 Android10Platform，VerifyError | | Gson | **2.8.6** | 2.9+ 含 ReflectionHelper，VerifyError | | Coroutines | **1.6.4** | 1.7+ 要求 minSdk 21 | | 视频播放 | **MediaPlayer** | ExoPlayer 2.14+ 不兼容 | | 主题 | **AppCompat** | MaterialComponents 主 dex 方法数超限 | | multidex | 启用 | 主 dex 保留 androidx.appcompat.** / kotlinx.coroutines.** / retrofit2.** | ## 八、参考代码 测试阶段已验证的代码在 `partner-test-app/` 目录： | 文件 | 作用 | |------|------| | `JetsenxSdkUtil.kt` | SDK 封装：init + getVideoUrls + getFreeVideoUrls | | `PartnerSignManager.kt` | 后端接口：init + checkBenefits + heartBeat | | `PartnerApiService.kt` | Retrofit 接口定义 | | `VideoPlayerActivity.kt` | MediaPlayer + SurfaceView 播放实现 | | `multidex-config.pro` | Android 4.2 multidex 配置 |