更新记录

1.2.2（2026-09-30）

统一短剧 ID 与分组 ID 为字符串类型，避免长整型精度丢失

1.2.1（2026-09-30）

修复已知问题

1.2.0（2026-09-30）

新增 可覆盖短剧原生页面的 Loading、Toast 和确认提示框 API

平台兼容性

uni-app(5.07)

uni-app x(5.07)

其他

tt-short-djx

穿山甲短剧 SDK UTS 插件，为 uni-app x / uni-app App 端提供短剧内容 API 和原生页面接入能力。

支持能力：

• 短剧列表、推荐、分类、搜索、短剧信息查询。
• 观看记录、收藏列表、清空观看记录。
• 点赞 / 取消点赞，收藏 / 取消收藏。
• 分集解锁状态查询。
• 业务账号解锁记录绑定、解绑和绑定状态查询。
• 原生详情播放页、滑滑流 openDraw()、原生聚合页 openHome()。
• 默认 SDK 解锁和业务侧自定义激励视频解锁回传。
• 可覆盖短剧原生页面的 Loading、Toast 和确认提示框。

需要页面内嵌组件？

本插件通过 API 打开独立的原生详情页、滑滑流和聚合页，不提供页面内嵌组件。如果需要将滑滑流或聚合页嵌入普通页面、tabBar 子页面或指定尺寸的容器中，请根据项目技术栈选择组件插件：

• uni-app App-nvue：穿山甲短剧兼容组件
• uni-app x VDOM / Vapor：穿山甲短剧标准组件

接入前必读

• 仅支持 App 真机环境；请使用自定义基座或云打包后的 App 调试，浏览器和小程序环境不能调用本插件。
• HBuilderX 版本与插件版本必须匹配：HBuilderX 5.25 及以上版本推荐使用插件 1.2.1；HBuilderX 5.25 之前版本请使用 1.1.6 之前的插件版本。不同版本的 iOS Pod 依赖不同，混用可能导致云打包或本地打包依赖冲突。
• 应用须先在穿山甲 / 巨量引擎后台开通短剧内容能力，并在 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 参考
• 事件说明
• 平台差异
• 错误码
• 常见问题

版本信息

HBuilderX 兼容性

请勿跨表混用 HBuilderX 与插件版本，否则可能因 iOS Pod 依赖版本不同导致打包冲突。

1.2.1 升级注意

1.2.1 统一了跨平台 ID 类型：dramaId、dramaIds、topDramaId 以及返回数据中的 dramaId、groupId 均为字符串。升级后请将数字字面量改为字符串，例如 dramaId: '123456'、topDramaId: '0'，并同步调整业务模型、缓存字段和相等比较；不要再将短剧 ID 转为 number，以免长整型 ID 丢失精度。

配置文件

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

Android 配置

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

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

重点检查：

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

iOS 配置

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

uni_modules/tt-short-djx/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：UniAd 激励视频广告位 ID，不传给 createShortDrama()。SDK 广告和自定义广告模式都需要先通过它创建一次广告实例以初始化 UniAd/GroMore；仅自定义广告模式需要业务侧主动加载、展示并处理广告回调。

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

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

快速开始

导入并创建实例

import { createShortDrama } from '@/uni_modules/tt-short-djx'
import type { ShortDrama } from '@/uni_modules/tt-short-djx/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 传给短剧插件，但仍需提前调用一次 uni.createRewardedVideoAd({ adpid }) 初始化 UniAd/GroMore。

常用能力示例

列表、分类、搜索

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) 只移除传入的监听，省略 callback 或传 null 时清空该事件的全部监听。

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 的平台私有结构。rawData 和 extra 是高级透传字段，结构可能随平台或原生 SDK 版本变化，不属于稳定的跨平台协议。

平台差异

• openDraw()：Android 支持 hideDramaInfo 和 enableRefresh；当前 iOS SDK 的 DJXDrawVideoVCConfig 未暴露对应字段，因此这两个参数在 iOS 被忽略。
• openHome()：Android / iOS 均为原生聚合页；iOS 使用 DJXPlayletAggregatePageViewController，支持导航栏标题、返回按钮、置顶短剧和详情播放配置；showChangeBtn、topOffset 当前仅 Android 生效。
• favorite() / unfavorite()：iOS 收藏 / 取消收藏接口不使用 episode。
• offXxx(callback?)：传 callback 时精确移除该监听；省略 callback 或传 null 时清空该事件的全部监听。

错误码

推荐统一监听错误事件：

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

常见问题

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

默认 SDK 解锁广告位来自当前应用的 SDK_Setting.json，不需要把 adpid 传给短剧插件；但在创建短剧实例前，仍需调用一次 uni.createRewardedVideoAd({ adpid }) 初始化 UniAd/GroMore，且不需要主动展示。只有 unlockAdMode: 'custom' 时，业务侧才需要自行加载和展示激励视频，并通过 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，不能通过该参数设置全量免费观看。

页面销毁时需要做什么？

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

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

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