244 lines
9.0 KiB
Markdown
244 lines
9.0 KiB
Markdown
|
# 盛阳等三方支付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
|
|||
|
|
<activity android:name=".LaunchActivity" android:exported="true">
|
|||
|
|
<intent-filter>
|
|||
|
|
<action android:name="com.pukka.mediaapp.PARTNER_LAUNCH" />
|
|||
|
|
<category android:name="android.intent.category.DEFAULT" />
|
|||
|
|
</intent-filter>
|
|||
|
|
</activity>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 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 配置 |
|