d11464d466
包含内容： - thirdparty flavor 独立 applicationId + Intent 入口（ThirdPartyEntryActivity） - 58 后端接口适配（单 /api 路径、code 0/200、camelCase 字段、UNBOUND 轮询） - MAC 硬件锚定校验（防一凭证多设备共用） - EPG mac 覆盖 SDK init（sMacOverride）+ ChannelManger 初始化对齐 - 提示文案优化（设备未注册/权益未绑定）
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 配置 |
|