更新记录

1.1.3（2026-08-12）

更新 示例与说明文档

1.1.2（2026-08-03）

修复 安卓自定义广告解锁回调异常问题 更新 示例项目新增模拟激励成功模式

1.1.1（2026-08-03）

修复 Android 自定义广告解锁时 DJXRewardAdResult 类型不匹配导致的回调失败

平台兼容性

uni-app(5.07)

uni-app x(5.07)

tt-short-djx

穿山甲短剧 SDK UTS 插件，为 uni-app x / uni-app App 端提供短剧内容接入能力。插件只提供 API，不提供列表 UI 组件；业务侧可自行实现首页、推荐、搜索、收藏、观看记录、播放入口和广告解锁流程。

支持能力：

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

接入前必读

• 仅支持 App 真机环境；请使用自定义基座或云打包后的 App 调试，浏览器和小程序环境不能调用本插件。
• 应用须先在穿山甲 / 巨量引擎后台开通短剧内容能力，并在 HBuilderX / manifest.json 中勾选穿山甲 GroMore 模块。
• SDK_Setting.json、Android 包名或 iOS Bundle ID 必须与当前应用及其短剧授权一致；不要使用示例应用或其他应用的配置文件。
• 短剧仅支持广告解锁，不支持 IAP、会员付费解锁或将短剧全量设为免费观看。短剧 SDK 会校验免费集数和解锁集数，不符合规则时会强制展示广告，规避广告解锁可能导致应用被封禁。
• 短剧解锁广告必须包含穿山甲广告，并产生真实广告曝光。
• 建议开通 UniAd，并联系相关人员在激励视频广告位瀑布流中配置穿山甲广告，穿山甲广告填充率须大于 6%。
• 相关规则请参阅：穿山甲支持中心说明。

目录

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

版本信息

授权说明

配置文件

完成“接入前必读”的检查后，将当前应用对应的 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：激励视频广告位 ID，仅业务侧自定义解锁流程使用，不需要传给 createShortDrama()。

创建实例时可显式传入 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

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
)

自定义解锁流程

默认 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 时可以传空字符串 ''。

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 的平台私有结构。

平台差异

• 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)
})

常见问题

插件是否提供短剧列表组件？

不提供。插件只提供 API，业务侧需要自行实现列表 UI、搜索 UI、收藏页、观看记录页和入口逻辑。

默认 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，不能通过该参数设置全量免费观看。

页面销毁时需要做什么？

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

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

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