uni-ad-drama

uni-app x（蒸汽模式）短剧示例项目，演示 uni-drama 插件（v1.0.2）的两种接入方式。

• AppID：__UNI__XXXXXX
• 渲染模式：vapor（蒸汽）
• 平台：仅 App-Android（其他平台显示"仅支持 Android"占位提示）
• 最低要求：HBuilderX 5.32+，uni-app-x 5.31+

---

⚠️ 前置申请（必读，缺一不可）

短剧功能依赖 uni-ad 一体化申请，以下三项必须全部就绪才能正常运行。

1. 申请短剧广告位（adpid）

登录 uni-ad 后台，申请短剧广告位，获取 adpid。 在示例的右上角"参数"弹窗中填入，或直接修改页面代码中的 DEFAULT_ADPID。

2. 申请并替换 gm_SDK_Setting.json

通过 uni-ad 一体化申请后，从穿山甲后台 内容输出 → 接入管理 下载 SDK 参数配置文件，重命名为 gm_SDK_Setting.json，放到：

nativeResources/android/assets/gm_SDK_Setting.json

本项目已内置一份示例配置文件，绑定包名 com.bytedance.djxdemo，仅供参考结构，不可用于生产。接入自己的应用时必须替换为自己申请的文件。

详见：gm_SDK_Setting.json 配置说明

3. 云打包包名必须与 gm_SDK_Setting.json 一致（关键）

gm_SDK_Setting.json 中 license_config 的 PackageName 与云打包 Android 包名强绑定，不一致会导致进入短剧播放页直接崩溃。

• 当前示例绑定包名：com.bytedance.djxdemo
• 云打包时【发行 → 原生App-云打包】的 Android 包名 必须填写与 license_config.PackageName 完全一致的值
• 使用自己的包名时，须重新到穿山甲后台下载对应包名签发的 gm_SDK_Setting.json

4. 使用自定义调试基座

标准基座不含短剧运行时，会报 -5020。必须在 HBuilderX 【发行 → 原生App-云打包】中勾选"制作自定义调试基座"，使用云打包后的基座运行调试。

---

页面结构

pages.json

共注册 4 个页面：

path	标题	说明
pages/index/index（启动页）	uni-drama 短剧示例	导航首页，两个接入入口卡片
pages/ad-drama-demo/ad-drama-demo	短剧场	API 模式：短剧聚合首页
pages/ad-drama-search/ad-drama-search	搜索短剧	API 模式：独立搜索页
pages/ad-drama-component-demo/ad-drama-component-demo	短剧组件模式	组件模式：内嵌短剧首页

globalStyle：导航栏黑字、背景 #F6F7F5。

---

页面详解

首页（pages/index/index）

两张入口卡片，分别 uni.navigateTo 跳转到 API 模式页（短剧场）和组件模式页。

API 模式 — 短剧场（pages/ad-drama-demo）

完整的短剧聚合首页，功能包括：

• 模块加载：onMounted 时调用 uni.createDramaAd 创建实例（创建即自动加载）；全屏 loading 转环 + 点点动画 + 已等待秒数（20s 兜底超时）
• 频道 Tab：推荐（getRecommendedList）/ 榜单（getList）/ 收藏（getCollectionList）/ 记录（getHistoryList）；切换频道自动重置分页并刷新
• 海报网格：两列布局，scroll-view 实现；下拉刷新（refresherrefresh）+ 触底加载更多（scrolltolower）；请求序号机制防止快速切换时旧响应污染新数据
• 骨架屏：首次加载/切频道时展示
• 搜索入口：顶部胶囊点击跳转至独立搜索页（携带 adpid/free/lock 参数）
• 打开播放页：点击海报调用 dramaAd.open，携带 dramaId、起播集数、免费/解锁集数、服务器回调参数
• 空态处理：区分错误/无数据/收藏空/记录空，各含不同提示和按钮
• 参数弹窗（右上角"参数"按钮）：可配置 adpid / 免费集数 / 解锁集数 / 每页数量（默认 20）/ userId / extra；adpid 变更后自动重建实例，其他参数变更刷新当前频道
• 重试机制：模块失败 → 重建实例；数据失败 → 刷新当前频道
• 页面生命周期：onShow 时若模块就绪且当前为收藏/记录频道则自动刷新；onUnmounted 时销毁实例

API 模式 — 搜索页（pages/ad-drama-search）

独立搜索页，从短剧场首页跳转时携带 adpid/free/lock，也可独立使用（使用默认值）。

• 搜索历史：本地存储（uni_drama_search_history），最多保留 10 条，点击历史标签直接触发搜索
• 实例创建：onLoad 时创建实例；若用户在模块就绪前已提前发起搜索，onLoad 到达后自动补发第一页
• 分页：DEFAULT_PAGE_SIZE = 10；翻页时按 dramaId 去重后追加，翻页结果为空或全部重复时判定无更多
• 下拉刷新 + 触底加载：同 API 模式首页
• 全局 loading + 超时兜底：20s 超时
• onUnmounted 销毁实例

组件模式（pages/ad-drama-component-demo）

使用 <ad-drama> 组件内嵌短剧首页 Fragment。

• 全局 loading 转环：组件挂载即展示（startDots() 在 setup 顶层同步启动），20s 兜底超时
• 错误面板：加载失败或超时后展示错误原因 + "重新加载"按钮（重建组件：变更 dramaKey）
• 参数弹窗（右上角"参数"按钮）：配置 adpid / 免费集数（free）/ 解锁集数（lock）/ 服务器回调 userId+extra；"保存并重载"后立即重建组件生效
• 事件回调：@load / @error / @click / @close（close 携带 isEnded，表示关闭前是否已收到解锁奖励）
• 解锁广告：由短剧 AAR 内部完成，页面无需处理
• onUnmounted 停止秒表计时器

计时时序说明：AAR 已就绪时组件 @load 事件可能早于页面 onMounted 到达，因此 startDots() 必须放在 setup 顶层同步启动，不可放在 onMounted 里，否则 load 到达后秒表不会停。

---

原生资源配置

nativeResources/
└── android/
    └── assets/
        └── gm_SDK_Setting.json   ← 穿山甲 SDK 配置 + VOD 播放 license

manifest.json uni-ad 模块配置

app.distribute.modules.uni-ad 中必须包含 gm-content 渠道，这是短剧能力的核心依赖，云打包时必须勾选。

云打包自定义基座配置示例：

---

uni-drama 插件（uni_modules/uni-drama）

项	值
版本	1.0.2
类型	uts-vue-component
支持渲染模式	vapor ✓
平台	App-Android（minVersion: 21）
HBuilderX 要求	^5.32
uni-app-x 要求	^5.32
依赖其他插件	无（独立运行，无需手动导入 AAR）

提供的能力：

• uni.createDramaAd(options) — API 模式，返回 DramaAd 实例
• <ad-drama> 组件 — 组件模式，native-view 内嵌短剧首页 Fragment

---

错误排查

现象	原因	处理
报 -5020	标准基座不含短剧运行时	使用自定义调试基座
进入播放页崩溃	包名与 gm_SDK_Setting.json 中 license_config.PackageName 不一致	云打包时填写一致包名，或下载新包名对应的配置文件
首页一直 loading / 超时	adpid 未开通短剧能力、网络异常、渠道不可用	检查 uni-ad 后台广告位状态；看控制台 [drama-home] 日志
短剧列表无内容	init 凭证与穿山甲后台应用不匹配	核对 gm_SDK_Setting.json 中 init 字段
搜索无结果	搜索词不在渠道数据库 / 模块未就绪	等模块 loading 消失后再搜索；换词重试
图片加载失败	封面 URL 含时效签名已过期	重新拉取列表刷新 URL；控制台搜索 [图片验证] 定位