更新记录

1.0.0（2026-07-02）

• 新增自建聚合页推荐列表、观看记录、收藏列表和搜索 API。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

tt-short-djx

🚀 穿山甲短剧 SDK 插件，为 uni-app x & uni-app App 端提供短剧内容集成能力，支持短剧列表、推荐、搜索、收藏、观看记录、详情播放页和激励视频解锁回传。

插件定位为 API-only：只提供短剧 API，不提供列表 UI 组件。业务侧可以完全自定义短剧首页、推荐位、搜索页、播放入口和广告解锁策略。

📖 目录

• SDK版本信息
• 重要提示
• 环境配置
  • 前置条件
  • Android平台配置
  • iOS平台配置
• 快速开始
• 基础使用
  • 创建短剧实例
  • 获取推荐列表并打开播放页
  • 处理激励视频解锁
• 功能介绍
  • 获取全量短剧列表
  • 获取推荐短剧列表
  • 查询短剧信息
  • 获取观看记录
  • 获取收藏列表
  • 搜索短剧
  • 打开短剧播放页
  • 短剧播放事件
  • 短剧解锁事件
• API参考
• 错误处理
• 常见问题

SDK版本信息

📚 推荐阅读：接入前请先在穿山甲后台开通短剧能力，下载当前应用对应的 SDK_Setting.json，并确认 uni-app 项目已勾选穿山甲 GroMore 模块。

重要提示

⚠️ 必须使用自定义基座或云打包真机运行，浏览器、普通小程序环境无法调用原生短剧 SDK。
⚠️ 插件不内置短剧列表 UI，业务侧需要自行绘制列表、搜索、收藏、观看记录等页面。
⚠️ 插件不会接收或保存激励视频广告位 ID，解锁广告请在业务侧使用 uni.createRewardedVideoAd({ adpid }) 自行创建。
⚠️ 必须在项目中勾选穿山甲 GroMore 模块，否则广告 SDK 相关能力可能无法正常初始化。
⚠️ 必须使用穿山甲官网/后台为当前应用生成的 SDK_Setting.json，不要直接使用示例或其他应用的配置文件。
⚠️ 初始化短剧 SDK 前会检查穿山甲广告 SDK 状态；如未初始化，会优先读取 SDK_Setting.json 的 init.site_id 并尝试初始化。
⚠️ 如项目中同时接入官方广告、GroMore 或其他穿山甲相关插件，请注意 SDK 版本和依赖冲突。

环境配置

前置条件

1. 开通穿山甲短剧功能：在穿山甲 / 巨量引擎相关后台为当前应用开通短剧内容能力，并确认应用、包名、Bundle ID、短剧权限已审核通过。
2. 勾选穿山甲 GroMore：在 HBuilderX / manifest.json 的 App 模块或广告相关配置中，勾选穿山甲 GroMore 模块；未勾选时广告 SDK 初始化和激励视频能力可能不可用。
3. 下载 SDK_Setting.json：从穿山甲官网/后台下载当前应用对应的短剧 SDK 配置文件，文件内通常包含 init.site_id、app_id、partner、secure_key、license_config 等信息。
4. 替换插件配置文件：将下载的 SDK_Setting.json 替换到插件对应平台目录，不能使用示例应用或其他应用的配置文件。
5. 准备激励视频广告位：如需自定义解锁广告，准备业务侧激励视频广告位 ID，即 uni.createRewardedVideoAd({ adpid }) 使用的 adpid。
6. 制作自定义基座或云打包：将插件放入 uni_modules/tt-short-djx 后，重新制作自定义基座，或提交云打包后在真机验证。

Android平台配置

Android 依赖已在插件内自动配置，正常情况下无需业务侧手动添加 Maven 或 Gradle 依赖。

插件内置配置位置：

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

请从穿山甲官网/后台下载 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 包名一致。
• 后台已为该应用开通短剧功能，并已配置短剧相关广告位。
• HBuilderX / manifest.json 已勾选穿山甲 GroMore 模块。

也可以在创建实例时通过 adSiteId 传入媒体 ID，优先级高于 SDK_Setting.json 中的 init.site_id：

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

iOS平台配置

iOS 依赖已在插件内通过 Pod 配置，正常情况下无需业务侧手动添加 Pod。

插件内置配置位置：

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

请从穿山甲官网/后台下载 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 一致。
• 后台已为该应用开通短剧功能，并已配置短剧相关广告位。
• HBuilderX / manifest.json 已勾选穿山甲 GroMore 模块。

如打包时出现 Pod 拉取失败、SDK 版本冲突等问题，请优先检查本地 CocoaPods、HBuilderX 版本、项目中是否存在其他穿山甲相关插件。

快速开始

1. 导入插件

uni-app x 版本

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

uni-app 版本

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

const shortDrama = createShortDrama()

2. 获取推荐短剧

shortDrama.getRecommendedList(
  {
    page: 1,
    pageSize: 20
  },
  (res) => {
    console.log('推荐短剧列表', res.list)
  },
  (err) => {
    console.error('推荐短剧获取失败', err)
  }
)

3. 打开短剧播放页

shortDrama.open(
  {
    dramaId: 123456,
    startEpisode: 1,
    unlockEpisodeCount: 1,
    freeEpisodeCount: 1
  },
  () => {
    console.log('短剧播放页打开成功')
  },
  (err) => {
    console.error('短剧播放页打开失败', err)
  }
)

基础使用

创建短剧实例

建议在业务侧维护一个短剧单例，避免重复初始化原生 SDK。

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

export const shortDrama = createShortDrama({
  // 可选，不传时读取 SDK_Setting.json 中的 init.site_id
  adSiteId: '你的穿山甲媒体 ID'
})

获取推荐列表并打开播放页

import type {
  ShortDramaInfo,
  ShortDramaListResult
} from '@/uni_modules/tt-short-djx/utssdk/interface.uts'

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

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

处理激励视频解锁

短剧触发解锁时，插件会通过 onUnlockEvent() 通知业务侧。业务侧播放自己的激励视频广告后，需要调用 completeUnlock() 回传结果。

import type { ShortDramaUnlockEvent } from '@/uni_modules/tt-short-djx/utssdk/interface.uts'

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

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

  const taskId = event.taskId

  rewardAd.onClose((res) => {
    shortDrama.completeUnlock({
      taskId,
      success: res.isEnded === true,
      cpm: '0',
      extra: {
        isEnded: res.isEnded
      } as UTSJSONObject
    })
  })

  rewardAd.load(() => {
    shortDrama.notifyUnlockAdWillShow({
      taskId,
      cpm: '0'
    })
    rewardAd.show()
  })
})

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

功能介绍

获取全量短剧列表

shortDrama.getList(
  { page: 1, pageSize: 20, order: 'default' },
  (res) => console.log(res.list),
  (err) => console.error(err)
)

获取推荐短剧列表

shortDrama.getRecommendedList(
  { page: 1, pageSize: 20 },
  (res) => console.log(res.list),
  (err) => console.error(err)
)

查询短剧信息

// 查询单个短剧
shortDrama.getInfo(
  { dramaId: 123456 },
  (res) => console.log(res.list[0]),
  (err) => console.error(err)
)

// 查询多个短剧
shortDrama.getInfo(
  { dramaIds: [123456, 789012] },
  (res) => console.log(res.list),
  (err) => console.error(err)
)

获取观看记录

shortDrama.getWatchHistory(
  { page: 1, pageSize: 20 },
  (res) => console.log(res.list),
  (err) => console.error(err)
)

获取收藏列表

shortDrama.getFavorites(
  { page: 1, pageSize: 20 },
  (res) => {
    console.log('收藏列表', res.list)
    console.log('附加信息', res.extra)
  },
  (err) => console.error(err)
)

搜索短剧

shortDrama.search(
  {
    keyword: '霸总',
    fuzzy: true,
    page: 1,
    pageSize: 20
  },
  (res) => console.log(res.list),
  (err) => console.error(err)
)

打开短剧播放页

shortDrama.open(
  {
    dramaId: 123456,
    startEpisode: 1,
    unlockEpisodeCount: 1,
    freeEpisodeCount: 1
  },
  () => console.log('打开成功'),
  (err) => console.error('打开失败', err)
)

短剧播放事件

shortDrama.onPlayEvent((event) => {
  console.log('播放事件', event.type, event.data)
})

常见 type 可能包括：startPlay、pause、progress、playError 等，实际以原生短剧 SDK 返回为准。

短剧解锁事件

shortDrama.onUnlockEvent((event) => {
  console.log('解锁事件', event.type, event.taskId)
})

API参考

createShortDrama(options?)

创建短剧实例。

ShortDrama 方法

ShortDramaListOptions

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

ShortDramaInfoOptions

ShortDramaSearchOptions

ShortDramaOpenOptions

NotifyUnlockAdWillShowOptions

CompleteUnlockOptions

ShortDramaListResult

ShortDramaInfo

ShortDramaUnlockEvent

ShortDramaPlayEvent

ShortDramaError

错误处理

常见错误码

推荐写法

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

常见问题

1. 为什么浏览器运行时没有效果？

本插件依赖穿山甲原生短剧 SDK，只支持 App 端。请使用自定义基座或云打包后的真机 App 调试。

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

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

3. 激励视频广告位 ID 要传给插件吗？

不需要。插件不会保存 adpid。业务侧在 unlockRequired 事件中自行调用 uni.createRewardedVideoAd({ adpid }) 展示激励视频，然后把结果通过 completeUnlock() 回传。

4. adSiteId 和 adpid 有什么区别？

• adSiteId：穿山甲广告 SDK 媒体 ID，用于广告 SDK / 短剧 SDK 初始化。
• adpid：激励视频广告位 ID，用于业务侧创建激励视频广告。

5. notifyUnlockAdWillShow() 必须调用吗？

建议调用。它用于通知短剧 SDK 业务侧激励视频广告即将展示。如果漏调，completeUnlock() 会尽量兜底，但推荐按流程显式调用。

6. 页面销毁时需要做什么？

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