更新记录

1.0.9（2026-10-28）

滑滑流和聚合页组件新增短剧备案筛选及内容隐私配置属性

1.0.8（2026-10-26）

修复滑滑流组件属性透传问题

1.0.7（2026-10-23）

滑滑流新增详情页外观配置，可控制奖励弹窗、返回按钮、信息区及操作按钮显示

平台兼容性

uni-app x(5.26)

其他

tt-djx-standard

穿山甲短剧自包含标准组件插件，为 uni-app x App 端同时提供短剧 API、原生弹窗、滑滑流组件和聚合页组件，支持 VDOM 与 Vapor。

支持能力：

• 短剧列表、推荐、分类、搜索、短剧信息查询。
• 观看记录、收藏列表、清空观看记录。
• 点赞 / 取消点赞，收藏 / 取消收藏。
• 分集解锁状态查询。
• 业务账号解锁记录绑定、解绑和绑定状态查询。
• 原生详情播放页、滑滑流 openDraw()、原生聚合页 openHome()。
• 默认 SDK 解锁和业务侧自定义激励视频解锁回传。
• 可覆盖短剧原生页面的 Loading、Toast 和确认提示框。
• 短剧内容个性化、青少年模式、备案内容和内容 SDK 设备标识权限配置。
• 标准组件 tt-djx-draw（滑滑流）和 tt-djx-home（聚合页）。
• 标准组件 tt-djx-detail：在 Android / iOS 内嵌短剧详情内容，并通过默认插槽叠加业务自定义悬浮窗。

tt-djx-standard 与 tt-djx-compat 内含相同原生 SDK 和资源，请按技术栈二选一，不要在同一项目中同时安装。

与 API 插件的区别

组件版包含 tt-short-djx 的完整 API，额外提供可直接嵌入业务页面的滑滑流和聚合页。API 插件的 openDraw()、openHome() 会打开独立原生页面，不能作为当前页面布局的一部分。

如果只需要通过 API 打开独立原生页面，不需要页面内嵌组件，可以购买 穿山甲短剧 API 插件；需要把短剧内容放进现有页面、tabBar 或指定尺寸区域时，选择组件插件。

标准组件快速使用

<template>
  <view class="container">
    <tt-djx-draw class="drama" @load="onLoad" @error="onError" />
  </view>
</template>

<style>
.container, .drama { flex: 1; width: 100%; }
</style>

聚合页将标签替换为 tt-djx-home。API 直接从本插件导入：

import { createShortDrama } from '@/uni_modules/tt-djx-standard'

const shortDrama = createShortDrama()
shortDrama.showLoading({ title: '加载中…', mask: true })
shortDrama.showToast({ title: '加载完成' })

如需在短剧详情内容上叠加可由业务修改的悬浮窗，可使用 tt-djx-detail。悬浮窗本身写在默认插槽内，因此其样式、位置、大小和点击交互均由 uvue 控制：

<template>
  <tt-djx-detail class="drama" :drama-id="dramaId">
    <view class="float-window" @click.stop="handleFloatClick">
      <text class="float-window__text">活动</text>
    </view>
  </tt-djx-detail>
</template>

<script setup lang="uts">
const dramaId = ref('实际短剧 ID')

function handleFloatClick() {
  uni.showToast({ title: '点击了悬浮窗', icon: 'none' })
}
</script>

<style>
.drama { flex: 1; width: 100%; }
.float-window {
  position: absolute;
  right: 16px;
  top: 140px;
  width: 64px;
  height: 64px;
  border-radius: 32px;
  background-color: rgba(124, 58, 237, 0.92);
  align-items: center;
  justify-content: center;
  z-index: 100;
}
.float-window__text { color: #ffffff; }
</style>

悬浮窗使用普通 uvue 编写，绝对定位以 tt-djx-detail 容器为参照，样式、位置、大小和点击逻辑均由业务控制。不要在插槽中增加全屏透明遮罩，否则会拦截详情页的点击和上下滑动；超出详情组件边界的内容会被裁剪。

tt-djx-detail 支持 Android 和 iOS。短剧详情内容仍由穿山甲 SDK 渲染。只有内嵌详情组件支持 uvue 悬浮窗，通过 open() 打开的独立原生播放页不支持插槽。

示例项目中的可运行页面：

• pages/draw-api/index：open()、openDraw()、openHome()、页面事件和原生 Loading / Toast / Modal。
• pages/api-data/index：列表、推荐、分类、搜索、详情查询、观看记录、收藏、点赞、分集解锁状态、内容个性化和自定义激励解锁。
• pages/detail-component/index：详情组件、自定义悬浮窗以及在播放内容上方显示原生弹窗。

账号解锁记录绑定依赖业务服务端生成签名参数，示例不会内置服务端密钥或伪造签名；请按“解锁记录绑定”章节接入真实服务端参数。

组件挂载前初始化广告

组件挂载时会自动初始化短剧 SDK，不需要业务侧调用 createShortDrama()。因此必须在组件首次渲染前创建并保留一个 UniAd 广告实例，否则可能出现 -9001。初始化必须在用户同意隐私协议之后执行。

let rewardedVideoAd: RewardedVideoAd | null = null

function initShortDramaAd() {
  if (rewardedVideoAd != null) return
  rewardedVideoAd = uni.createRewardedVideoAd({
    adpid: '当前应用的激励视频广告位 ID'
  })
  rewardedVideoAd?.onError((error) => {
    console.error('UniAd 初始化失败', error)
  })
}

请在隐私授权完成后、包含短剧组件的页面显示前调用 initShortDramaAd()。这里仅用于初始化 UniAd/GroMore，不需要主动调用 show()。

短剧内容个性化与隐私配置

在用户同意隐私协议后、首个短剧组件挂载前调用：

import { configureShortDrama } from '@/uni_modules/tt-djx-standard'

configureShortDrama({
  personalizationEnabled: true,
  teenagerMode: false,
  onlyICPContent: false,
  allowAndroidId: true,
  allowOAID: true,
  allowIDFA: true
})

除内容个性化外，其他字段都是初始化配置，SDK 启动后修改不会重新生效。用户运行中切换内容个性化时可调用 shortDrama.setContentPersonalization(enabled, success?, fail?)。

tt-djx-draw 和 tt-djx-home 也支持直接传入这组配置属性。只需在组件标签上设置需要覆盖的字段；未传字段会沿用 configureShortDrama() 或 createShortDrama() 设置的值。配置必须在第一次短剧 API 请求或短剧组件创建前确定；组件初始化后更改属性不会重新初始化 SDK。该设置只影响短剧内容推荐，不会修改 UniAd/穿山甲广告的个性化开关；广告个性化应由应用的广告层统一处理。

标准组件参考

内容合规与隐私配置组件属性

以下属性可用于 tt-djx-draw 和 tt-djx-home；属性名在模板中使用 kebab-case。它们对应 CreateShortDramaOptions / ShortDramaContentConfig 的全局初始化配置：

备案筛选示例：

<tt-djx-draw class="drama" :only-icp-content="true" />

这些设置是 SDK 初始化配置，需在第一次短剧 API 请求或组件初始化前传入。详情组件只播放指定 dramaId，不会进行列表筛选；需要限制全局内容时，请在首次短剧 API 请求或组件创建前通过 configureShortDrama() 配置。

tt-djx-draw 滑滑流组件

滑滑流和进入后的详情页都使用纵向手势。组件所在页面必须在 pages.json 中配置 disableScroll: true，避免 uni-app x Vapor 页面自身的默认滚动与原生滑动手势冲突：

{
  "path": "pages/drama-draw/index",
  "style": {
    "navigationBarTitleText": "短剧",
    "disableScroll": true
  }
}

如果组件放在 tabBar 页面，同样需要为该 tabBar 子页面设置 disableScroll: true。不要再把组件包进纵向 scroll-view；组件高度直接由外层 view 的布局控制。

穿山甲 SDK 当前没有提供统一的组件暂停 / 恢复接口。若切换 tabBar 后不希望后台继续播放，应在页面隐藏时通过 v-if 卸载组件，在页面重新显示时创建组件：

<tt-djx-draw v-if="componentVisible" class="drama" />

<script setup lang="uts">
const componentVisible = ref(true)
onShow(() => { componentVisible.value = true })
onHide(() => { componentVisible.value = false })
</script>

这种方式会销毁并重新创建原生内容，播放位置不会自动续接；如需续播，应由业务保存短剧 ID 和集数后重新传入。

在组件标签上直接传属性，模板中使用 kebab-case。下面示例隐藏详情页奖励弹窗和操作控件，并将 Android 详情页顶部、底部偏移分别设为 120px 和 80px：

<template>
  <tt-djx-draw
    class="drama"
    channel-type="recommend"
    :hide-reward-dialog="true"
    :hide-back="true"
    :hide-top-info="true"
    :hide-bottom-info="true"
    :hide-more="true"
    :hide-like-button="true"
    :hide-favor-button="true"
    :top-offset="120"
    :bottom-offset="80"
  />
</template>

<style>
.drama { flex: 1; width: 100%; }
</style>

top-offset 和 bottom-offset 仅 Android 生效。

嵌入组件没有独立页面关闭按钮，因此内部固定 hideClose: true，不对外提供 hideClose 属性。

tt-djx-home 聚合页组件

嵌入组件没有独立页面返回按钮，内部固定 showBackBtn: false、topOffset: 0；这两个 API 页面参数不是组件属性。

tt-djx-detail 详情组件

tt-djx-detail 在当前页面内嵌短剧详情内容，默认插槽用于放置业务自定义悬浮窗。组件会固定隐藏 SDK 返回按钮，页面返回由外层 uni-app x 页面负责。组件所在页面应在 pages.json 中设置 disableScroll: true，避免页面滚动与详情页上下滑动手势冲突。

支持 load、error、playEvent、adEvent、unlockEvent 事件，并暴露 reload()、notifyUnlockAdWillShow(options)、completeUnlock(options) 方法。属性变化会重新创建详情内容；卸载组件时会自动销毁原生内容。

组件事件

标准组件事件处理函数直接接收对应事件数据：

<tt-djx-draw
  @load="handleLoad"
  @error="handleError"
  @drawEvent="handleDrawEvent"
/>

组件方法

三个组件均通过模板引用暴露以下方法：

组件属性改变时会自动重新加载原生内容，可能重置当前滚动位置或播放状态；不要在高频响应式数据中反复修改组件属性。

组件自定义广告流程

unlockAdMode="sdk" 不需要处理 unlockEvent。使用 custom 时，应监听 unlockRequired，通过当前组件引用完成广告展示和结果回传：

<tt-djx-draw
  ref="drawRef"
  unlock-ad-mode="custom"
  @unlockEvent="handleUnlockEvent"
/>

流程要求：

1. 收到 unlockRequired 后保存其 taskId。
2. 广告真实展示前调用组件的 notifyUnlockAdWillShow({ taskId, cpm })。
3. 奖励下发后调用 completeUnlock({ taskId, success: true, cpm })。
4. 加载失败、展示失败或用户跳过时调用 completeUnlock({ taskId, success: false })。

布局、tabBar 与样式边界

• 组件宽高完全由外层布局决定，必须给组件或父容器提供明确的宽高或 flex: 1。
• 普通页面和 tabBar 子页面都可以直接放置组件，不需要 active 属性。
• 原生 tabBar 可能覆盖 native-view 底部，页面应根据 uni.getWindowInfo().windowBottom 预留空间；取不到时可使用“50px + 底部安全区”兜底。
• 外层可以控制宽高、间距和所在布局区域；SDK 内部卡片、字体、颜色、封面比例等不能任意换肤。
• 内部样式只能通过组件公开的频道、标题和显示/隐藏属性有限调整。
• 业务页面上的 Loading、Toast 和确认框请使用本插件的 showLoading()、showToast()、showModal() 原生 API，确保能显示在短剧原生内容上方。

接入前必读

• 仅支持 App 真机环境；请使用自定义基座或云打包后的 App 调试，浏览器和小程序环境不能调用本插件。
• Android 平台运行时不要勾选“清理构建缓存”，否则运行时可能报错。
• 最低支持 HBuilderX 5.26，低于该版本不保证能够编译或运行。
• 应用须先在穿山甲 / 巨量引擎后台开通短剧内容能力，并在 HBuilderX / manifest.json 中勾选穿山甲 GroMore 模块。
• 必须勾选 HBuilderX / manifest.json 中的穿山甲 GroMore（UniAd）模块，并先调用一次 UniAd 广告 API（例如 uni.createRewardedVideoAd()）完成广告 SDK 初始化，再调用 createShortDrama()；否则可能出现 UniAd 错误 -9001。
• SDK_Setting.json、Android 包名或 iOS Bundle ID 必须与当前应用及其短剧授权一致；不要使用示例应用或其他应用的配置文件。
• 短剧仅支持广告解锁，不支持 IAP、会员付费解锁或将短剧全量设为免费观看。短剧 SDK 会校验免费集数和解锁集数，不符合规则时会强制展示广告，规避广告解锁可能导致应用被封禁。
• 短剧解锁广告必须包含穿山甲广告，并产生真实广告曝光。
• 建议开通 UniAd，并联系相关人员在激励视频广告位瀑布流中配置穿山甲广告，穿山甲广告填充率须大于 6%。
• 相关规则请参阅：穿山甲支持中心说明。

目录

• 与 API 插件的区别
• 标准组件快速使用
• 标准组件参考
• 版本信息
• 接入前必读
• 配置文件
• 快速开始
• 常用能力示例
• 自定义解锁流程
• API 参考
• 事件说明
• 平台差异
• 错误码
• 常见问题

版本信息

HBuilderX 兼容性

最低支持 HBuilderX 5.26。请使用该版本或更高版本进行自定义基座制作、云打包和真机调试。

配置文件

完成“接入前必读”的检查后，将当前应用对应的 SDK_Setting.json 放入插件目录。

Android 配置

将 Android 应用对应的 SDK_Setting.json 放到：

uni_modules/tt-djx-standard/utssdk/app-android/assets/SDK_Setting.json

重点检查：

• init.site_id 是当前 Android 应用的穿山甲媒体 ID。
• license_config.PackageName 与项目 Android 包名一致。
• 后台已为该应用开通短剧功能，并配置短剧相关广告位。

iOS 配置

将 iOS 应用对应的 SDK_Setting.json 放到：

uni_modules/tt-djx-standard/utssdk/app-ios/Resources/SDK_Setting.json

重点检查：

• init.site_id 是当前 iOS 应用的穿山甲媒体 ID。
• license_config.BundleId 与项目 iOS Bundle ID 一致。
• 后台已为该应用开通短剧功能，并配置短剧相关广告位。

adSiteId 与 adpid

• adSiteId：穿山甲广告 SDK 媒体 ID，用于广告 SDK / 短剧 SDK 初始化。不传时插件会读取 SDK_Setting.json 的 init.site_id。
• adpid：激励视频广告位 ID，仅业务侧自定义解锁流程使用，不需要传给 createShortDrama()。

创建实例时可显式传入 adSiteId：

const shortDrama = createShortDrama({
  adSiteId: '你的穿山甲媒体 ID'
})

快速开始

导入并创建实例

import { createShortDrama } from '@/uni_modules/tt-djx-standard'
import type { ShortDrama } from '@/uni_modules/tt-djx-standard/utssdk/interface.uts'

let shortDrama: ShortDrama | null = null

// 先触发 UniAd/GroMore 初始化，再创建短剧 SDK 实例。
uni.createRewardedVideoAd({ adpid: '你的激励视频广告位 ID' })

export default {
  onLoad() {
    shortDrama = createShortDrama()
  },
  onUnload() {
    shortDrama?.destroy()
    shortDrama = null
  }
}

获取推荐并打开播放页

shortDrama?.getRecommendedList(
  { page: 1, pageSize: 20 },
  (res) => {
    if (res.list.length === 0) return

    const item = res.list[0]
    shortDrama?.open(
      {
        dramaId: item.dramaId,
        startEpisode: item.currentEpisode > 0 ? item.currentEpisode : 1,
        freeEpisodeCount: 1,
        unlockEpisodeCount: 1,
        unlockAdMode: 'sdk'
      },
      () => console.log('打开成功'),
      (err) => console.error('打开失败', err)
    )
  },
  (err) => console.error('推荐列表获取失败', err)
)

默认 unlockAdMode: 'sdk' 使用 SDK_Setting.json 中的短剧解锁广告配置，不需要业务侧传入激励视频广告位 ID。

常用能力示例

列表、分类、搜索

shortDrama.getList({ page: 1, pageSize: 20, order: 'default' }, success, fail)
shortDrama.getRecommendedList({ page: 1, pageSize: 20 }, success, fail)
shortDrama.getCategories(success, fail)
shortDrama.getListByCategory({ category: '霸总', page: 1, pageSize: 20 }, success, fail)
shortDrama.search({ keyword: '霸总', fuzzy: true, page: 1, pageSize: 20 }, success, fail)
shortDrama.getInfo({ dramaId: '123456' }, success, fail)
shortDrama.getInfo({ dramaIds: ['123456', '789012'] }, success, fail)

观看记录与收藏列表

shortDrama.getWatchHistory({ page: 1, pageSize: 20 }, success, fail)
shortDrama.getFavorites({ page: 1, pageSize: 20 }, success, fail)
shortDrama.clearWatchHistory(success, fail)

点赞与收藏操作

shortDrama.like({ dramaId: '123456', episode: 1 }, success, fail)
shortDrama.unlike({ dramaId: '123456', episode: 1 }, success, fail)

shortDrama.favorite({ dramaId: '123456', episode: 1 }, success, fail)
shortDrama.unfavorite({ dramaId: '123456', episode: 1 }, success, fail)

说明：

• like() / unlike() 操作指定短剧集。
• favorite() / unfavorite() 操作短剧收藏；iOS 收藏 / 取消收藏接口不使用 episode，传入也会被忽略。

分集解锁状态

shortDrama.getEpisodeUnlockStatus(
  { dramaId: '123456', freeEpisodeCount: 1 },
  (res) => {
    const locked = res.list.filter((item) => item.locked)
    console.log('锁定集数', locked)
  },
  fail
)

打开详情播放页

shortDrama.open(
  {
    dramaId: '123456',
    startEpisode: 1,
    freeEpisodeCount: 1,
    unlockEpisodeCount: 1,
    unlockAdMode: 'sdk',
    hideLikeButton: false,
    hideFavorButton: false
  },
  success,
  fail
)

打开滑滑流

shortDrama.openDraw(
  {
    channelType: 'recommend',
    hideChannelName: false,
    hideDramaEnter: false,
    hideClose: false,
    dramaFree: 1,
    topDramaId: '0',
    freeEpisodeCount: 1,
    unlockEpisodeCount: 1,
    unlockAdMode: 'sdk'
  },
  success,
  fail
)

打开原生聚合页

shortDrama.openHome(
  {
    showPageTitle: true,
    showBackBtn: true,
    topDramaId: '0',
    freeEpisodeCount: 1,
    unlockEpisodeCount: 1,
    unlockAdMode: 'sdk'
  },
  success,
  fail
)

原生 Loading、Toast 和提示框

弹窗会从当前最上层 Activity/ViewController 展示，因此通过 open()、openDraw()、openHome() 打开的原生页面也可以显示。

shortDrama.showLoading({ title: '正在加载…', mask: true })
shortDrama.hideLoading()

shortDrama.showToast({
  title: '加载成功',
  duration: 2000,
  position: 'center'
})

shortDrama.showModal(
  {
    title: '提示',
    content: '是否继续播放？',
    showCancel: true,
    cancelText: '取消',
    confirmText: '继续'
  },
  (result) => {
    console.log(result.confirm ? '继续' : '取消')
  }
)

自定义解锁流程

默认 SDK 解锁不需要监听 onUnlockEvent()，也不需要调用 completeUnlock()。只有当 unlockAdMode: 'custom' 时，业务侧才需要监听 unlockRequired、展示激励视频，并把结果回传给短剧 SDK。

const rewardAd = uni.createRewardedVideoAd({
  adpid: '你的激励视频广告位 ID'
})

// 广告实例的生命周期回调只注册一次，不要放进 onUnlockEvent。
let pendingTaskId = ''

function showPendingRewardAd() {
  if (pendingTaskId.length === 0) return

  // 广告真实展示前通知短剧 SDK。
  shortDrama.notifyUnlockAdWillShow({ taskId: pendingTaskId })
  rewardAd.show()
}

rewardAd.onLoad(() => {
  showPendingRewardAd()
})

rewardAd.onClose((res) => {
  if (pendingTaskId.length === 0) return

  shortDrama.completeUnlock({
    taskId: pendingTaskId,
    success: res.isEnded === true,
    extra: { isEnded: res.isEnded } as UTSJSONObject
  })
  pendingTaskId = ''
})

rewardAd.onError((err) => {
  if (pendingTaskId.length === 0) return

  shortDrama.completeUnlock({
    taskId: pendingTaskId,
    success: false,
    extra: { error: err } as UTSJSONObject
  })
  pendingTaskId = ''
})

shortDrama.onUnlockEvent((event) => {
  if (event.type !== 'unlockRequired') return

  pendingTaskId = event.taskId
  rewardAd.load()
})

广告加载失败、展示失败或用户跳过广告时，也应调用 completeUnlock({ taskId, success: false })，避免解锁任务挂起。

广告曝光回调 onADWillShow 和奖励下发结果应优先回传广告真实 CPM。无法获取 CPM 时可以传空字符串 ''。

解锁记录绑定

有业务账号体系时，在业务登录成功且短剧 SDK 初始化完成后，先由业务服务端使用穿山甲后台的 server key 生成签名参数，再调用绑定接口。签名参数格式为 nonce=...&ouid=...&timestamp=...&sign=...；不要把 server key 下发、保存或传入客户端。

// params 由业务服务端返回，ouid 为稳定的业务账号 ID。
shortDrama.bindUnlockRecord({ params }, (result) => {
  console.log('解锁记录已绑定', result.bound, result.extra)
}, (err) => {
  console.error('绑定失败', err.code, err.message)
})

// 账号切换：先等待旧账号解绑成功，再绑定新账号。
shortDrama.unbindUnlockRecord(() => {
  // 调用 bindUnlockRecord({ params: newAccountParams })
})

// 仅在业务账号真实退出登录时调用；关闭播放页或 destroy() 不应自动解绑。
shortDrama.unbindUnlockRecord()

绑定后，短剧 SDK 会将该账号的已解锁剧集权益同步到当前设备；未绑定时按游客状态处理。应在读取分集解锁状态或打开播放页前完成绑定。

API 参考

createShortDrama(options?)

ShortDrama 方法

success / fail 均可省略。未传 fail 时，插件会把错误转发到 onError()；offXxx(callback?) 在 Android / iOS 均统一为清空当前事件的全部监听，不保证只移除传入的单个 callback。

Options

ShortDramaListOptions

适用于 getList()、getRecommendedList()、getWatchHistory()、getFavorites()。

ShortDramaCategoryListOptions

ShortDramaInfoOptions

ShortDramaEpisodeUnlockStatusOptions

ShortDramaUserActionOptions

适用于 like()、unlike()、favorite()、unfavorite()。

ShortDramaSearchOptions

ShortDramaOpenOptions

ShortDramaDrawOptions

ShortDramaHomeOptions

NotifyUnlockAdWillShowOptions

CompleteUnlockOptions

Result 与数据类型

ShortDramaListResult

ShortDramaInfo

ShortDramaCategoryListResult / ShortDramaCategoryInfo

ShortDramaEpisodeUnlockStatusResult / ShortDramaEpisodeUnlockStatusInfo

ShortDramaError

事件说明

播放、滑滑流、聚合页与广告事件

事件对象通用字段：

解锁事件

unlockRequired 只在 unlockAdMode: 'custom' 的业务侧自定义解锁流程中需要处理。

payload 约定

Android / iOS 会尽量统一补齐以下字段；原生 SDK 没有返回时字段可能为空：

业务逻辑建议优先使用标准字段，不要直接依赖 rawData 的平台私有结构。

平台差异

• tt-djx-detail：Android / iOS 均支持内嵌详情页和无限下滑；topOffset、bottomOffset 当前仅 Android 生效。
• openDraw()：Android 支持 hideDramaInfo 和 enableRefresh；当前 iOS SDK 的 DJXDrawVideoVCConfig 未暴露对应字段，因此这两个参数在 iOS 被忽略。
• openHome()：Android / iOS 均为原生聚合页；iOS 使用 DJXPlayletAggregatePageViewController，支持导航栏标题、返回按钮、置顶短剧和详情播放配置；showChangeBtn、topOffset 当前仅 Android 生效。
• favorite() / unfavorite()：iOS 收藏 / 取消收藏接口不使用 episode。
• offXxx(callback?)：Android / iOS 已统一为清空当前事件的全部监听。
• 示例自定义激励视频广告位：Android 默认 953685911，iOS 默认 953685880，均来自示例 SDK_Setting.json，正式接入请替换。

错误码

推荐统一监听错误事件：

shortDrama.onError((err) => {
  console.error('短剧插件错误', err.code, err.message, err.detail)
})

常见问题

默认 SDK 解锁需要传激励视频广告位 ID 吗？

不需要。默认 SDK 解锁广告位来自当前应用的 SDK_Setting.json。只有 unlockAdMode: 'custom' 时，才需要业务侧自行调用 uni.createRewardedVideoAd({ adpid }) 展示激励视频，并通过 completeUnlock() 回传结果。

SDK 解锁和自定义解锁如何选择？

unlockAdMode: 'sdk' 由插件使用 SDK_Setting.json 中的短剧解锁广告配置，接入简单，但业务侧不能调整广告请求逻辑。unlockAdMode: 'custom' 由业务侧通过 uni.createRewardedVideoAd({ adpid }) 请求广告，适用于已接入 UniAd 的项目；对应瀑布流必须包含穿山甲广告，并在广告曝光、奖励下发、用户跳过或广告失败时，通过 notifyUnlockAdWillShow() 和 completeUnlock() 回传解锁状态。

自定义解锁失败时如何排查？

先检查业务侧激励视频广告的加载或展示失败回调；广告未展示、用户跳过或广告失败时，必须使用当前 taskId 调用 completeUnlock({ taskId, success: false }) 结束任务。广告完整观看并发放奖励后，再调用 completeUnlock({ taskId, success: true })。同时确认 UniAd 瀑布流包含穿山甲广告且填充正常。

应用重装后为什么仍保留解锁记录？

接入登录并绑定用户数据时，解锁记录会随用户账号保留；未绑定账号时，短剧 SDK 的解锁记录可能与设备关联。业务侧的登录退出或账号切换逻辑需要自行处理。

自定义广告不回传 CPM 会怎样？

CPM 可以传空字符串 ''。但若 CPM 为空且平台未监测到合理广告展示，短剧 SDK 会强制切换为 SDK 直出广告，并屏蔽自定义解锁逻辑。应在广告真实曝光时调用 notifyUnlockAdWillShow({ taskId, cpm })，并在奖励下发时通过 completeUnlock({ taskId, success: true, cpm }) 回传同一广告的 CPM。

可以设置全部免费观看吗？

不可以。短剧仅支持广告解锁，不支持 IAP、会员付费或全量免费观看；免费集数由短剧 SDK 强校验。本插件的 freeEpisodeCount 公开参数范围为 1-20，不能通过该参数设置全量免费观看。

Android 运行时为什么会报错？

Android 平台运行时不要勾选 HBuilderX 的“清理构建缓存”选项，否则可能导致插件运行时报错。请取消该选项后重新打包运行。

页面销毁时需要做什么？

如果当前页面或模块不再使用短剧实例，建议调用 destroy() 解绑事件监听，避免重复回调。

出现初始化失败时优先检查什么？

优先检查穿山甲短剧能力是否开通、GroMore（UniAd）模块是否勾选、是否先调用了 uni.createRewardedVideoAd() 等广告 API、SDK_Setting.json 是否属于当前应用、包名 / Bundle ID 是否与 license 配置一致，以及原生日志中的 UniAd -9001 初始化错误。