更新记录

1.0.0（2026-09-30）

支持 穿山甲短剧

平台兼容性

uni-app(5.26)

tt-djx-compat

用于 uni-app App 的穿山甲短剧插件，包含可在 nvue 页面使用的滑滑流、聚合页兼容组件，以及可在 App Vue / nvue 中调用的短剧 API 和原生弹窗。

支持能力：

• 页面内嵌组件：tt-djx-draw-compat（滑滑流）和 tt-djx-home-compat（聚合页）。
• 短剧列表、推荐、分类、搜索、收藏、观看记录和分集解锁状态等 API。
• 原生详情播放页，以及通过 API 打开的独立滑滑流和聚合页。
• SDK 广告与业务侧自定义激励视频解锁。
• 可显示在短剧原生页面上的 Loading、Toast 和确认提示框。

页面内嵌兼容组件仅支持 App-nvue，普通 App Vue 页面可以使用短剧 API，但不能直接放置内嵌组件。uni-app x VDOM/Vapor 请使用 tt-djx-standard；两个组件插件都包含原生短剧 SDK，同一项目只能安装其中一个。

与 API 插件的区别

组件版包含完整短剧 API，并额外提供可嵌入业务页面的滑滑流和聚合页。API 插件的 openDraw()、openHome() 只能打开独立原生页面。

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

兼容组件快速使用

组件宽高由外层布局决定，可用于普通 nvue 页面或 tabBar 子页面。

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

<style>
.container, .drama { flex: 1; width: 750rpx; }
</style>

聚合页使用 tt-djx-home-compat。API 导入示例：

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

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

组件挂载前初始化广告

组件挂载时会自动初始化短剧 SDK，不需要业务侧调用 createShortDrama()。因此必须在组件首次渲染前创建并保留一个 UniAd 激励视频实例，用于触发 UniAd/GroMore 初始化，否则可能出现 -9001。SDK 广告和自定义广告模式都需要完成这一步；只有自定义广告模式需要业务侧主动加载和展示该实例。初始化必须在用户同意隐私协议之后执行。

let rewardedVideoAd = null

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

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

兼容组件参考

tt-djx-draw-compat 滑滑流组件

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

tt-djx-home-compat 聚合页组件

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

组件事件

兼容组件事件遵循 uni-app 兼容组件格式，业务侧从 event.detail 读取真实数据：

methods: {
  handleError(event) {
    const error = event.detail
    console.error(error.code, error.message)
  },
  handleUnlockEvent(event) {
    const detail = event.detail
    console.log(detail.type, detail.taskId)
  }
}

组件方法

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

<tt-djx-draw-compat ref="draw" />

this.$refs.draw.reload()

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

组件自定义广告流程

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

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

流程要求：

1. 从 event.detail 读取并保存 unlockRequired 的 taskId。
2. 广告真实展示前调用 this.$refs.draw.notifyUnlockAdWillShow({ taskId, cpm })。
3. 奖励下发后调用 this.$refs.draw.completeUnlock({ taskId, success: true, cpm })。
4. 加载失败、展示失败或用户跳过时调用 completeUnlock({ taskId, success: false })。

布局、tabBar 与样式边界

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

接入前必读

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

目录

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

运行要求

• 插件版本：1.0.0。
• HBuilderX：5.26 或更高版本。
• 运行环境：uni-app App；页面内嵌组件仅支持 nvue 页面。

配置文件

将当前应用对应的 SDK_Setting.json 放入插件目录。

Android 配置

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

uni_modules/tt-djx-compat/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-compat/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-djx-compat'
import type { ShortDrama } from '@/uni_modules/tt-djx-compat/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 初始化错误。