uni.createDramaAd(options)

创建短剧广告实例：创建即自动加载短剧模块（自动加载模式），加载结果经 onLoad / onError 上报

短剧广告：通过短剧内容生态（穿山甲内容联盟）变现的高价值广告形式。开发者将短剧内容（列表、播放页）嵌入自己的应用，用户免费观看指定集数后，需观看激励视频解锁后续剧集，从而实现广告变现。

uni-app x 内置短剧 uni-drama，提供两种接入方式：

接入方式	说明	适用场景
API 模式	通过 uni.createDramaAd 创建实例，自行搭建短剧列表页，调用查询接口获取短剧数据，再调用 open 打开原生播放页	需要自定义短剧列表页样式、深度定制业务
组件模式	使用 <ad-drama> 组件（native-view）	快速接入，直接使用渠道提供的短剧首页

组件模式另见：ad-drama 组件。 示例Demo另见：详见

开通配置广告

开通广告步骤详情

Tips

• 标准基座不支持测试短剧功能。
• 使用短剧组件需要先开通穿山甲广告。开通问题请咨询：uni-ad交流群。
• 标准基座不包含短剧运行时，需制作自定义基座后运行，否则报错 -5020。

配置文件

在穿山甲后台 内容输出->接入管理 找到需要接入内容SDK的应用，点击"下载SDK参数配置"，然后将SDK配置文件（例如 sdk_setting_file.json）拷贝到项目的 assets 文件夹下。

文件下载之后重命名为：gm_SDK_Setting.json，然后将文件放到项目根目录的nativeResources->android->assets目录下。

服务器回调

用户观看激励视频解锁剧集后，为防止客户端伪造看完广告的凭据，解锁集数的发放由服务器回调完成，这是业内通行的安全方案。调用 open 时传入 urlCallback（userId/extra），激励发放时会透传到业务服务器参与校验。服务器回调机制详见 激励视频广告服务器回调。

createDramaAd 兼容性 ^?

Web	微信小程序	支付宝小程序	Android
x	x	x	5.31

参数

名称	类型	必填	兼容性	描述
options	CreateDramaAdOptions	是		uni-drama 短剧插件类型定义（原 uni-ad-dom2 短剧部分独立拆分）。 依赖 uni-ad-dom2 广告插件（提供 SDK 初始化与 AAR），本文件只包含短剧 API 与组件类型。
名称 类型 必备 兼容性 描述 adpid string 是 短剧广告位标识

返回值

类型	描述
DramaAd	短剧广告实例：自建聚合页场景的列表/搜索/详情能力入口。 创建实例（uni.createDramaAd）即自动加载短剧模块（自动加载模式）， 加载结果经 onLoad / onError 上报。

DramaAd 的方法

getList(options : DramaListOptions) : void

getList 显式加载短剧模块（已注释：当前版本创建即自动加载，无需此方法； 如恢复手动加载模式，放开下面声明并同步放开实现处的注释）。

getList 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性	描述
options	DramaListOptions	是		列表查询参数：page 从 1 开始；success/fail/complete 与 open(options) 形态一致。
名称 类型 必备 兼容性 描述 page number 否 pageSize number 否 order string 否 success (res: DramaListResult) => void 否 查询成功的回调函数 fail (err: IUniDramaError) => void 否 查询失败的回调函数 complete () => void 否 查询结束的回调函数（成功失败都会执行）

DramaListResult 的属性值

名称	类型	必备	兼容性
dramas	Array<DramaInfo>	是
名称 类型 必备 兼容性 dramaId string 是 title string 是 coverUrl string 是 desc string 是 categoryId number 是 categoryName string 是 currentEpisode number 是 totalEpisodes number 是 groupId number 是 unlockIndex number 是 styleType number 是 duration number 是 rawInfo UTSJSONObject 否
extra	UTSJSONObject	是

IUniDramaError 的属性值

名称	类型	必备	兼容性	描述
errCode	number	是		短剧错误对象。
errSubject	string	是		统一错误主题（模块）名称
data	any	否		错误信息中包含的数据
cause	Error	否		源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

getRecommendedList(options : DramaListOptions) : void

getRecommendedList

getRecommendedList 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性	描述
options	DramaListOptions	是		列表查询参数：page 从 1 开始；success/fail/complete 与 open(options) 形态一致。
名称 类型 必备 兼容性 描述 page number 否 pageSize number 否 order string 否 success (res: DramaListResult) => void 否 查询成功的回调函数 fail (err: IUniDramaError) => void 否 查询失败的回调函数 complete () => void 否 查询结束的回调函数（成功失败都会执行）

DramaListResult 的属性值

名称	类型	必备	兼容性
dramas	Array<DramaInfo>	是
名称 类型 必备 兼容性 dramaId string 是 title string 是 coverUrl string 是 desc string 是 categoryId number 是 categoryName string 是 currentEpisode number 是 totalEpisodes number 是 groupId number 是 unlockIndex number 是 styleType number 是 duration number 是 rawInfo UTSJSONObject 否
extra	UTSJSONObject	是

IUniDramaError 的属性值

名称	类型	必备	兼容性	描述
errCode	number	是		短剧错误对象。
errSubject	string	是		统一错误主题（模块）名称
data	any	否		错误信息中包含的数据
cause	Error	否		源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

getCollectionList(options : DramaListOptions) : void

getCollectionList

getCollectionList 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性	描述
options	DramaListOptions	是		列表查询参数：page 从 1 开始；success/fail/complete 与 open(options) 形态一致。
名称 类型 必备 兼容性 描述 page number 否 pageSize number 否 order string 否 success (res: DramaListResult) => void 否 查询成功的回调函数 fail (err: IUniDramaError) => void 否 查询失败的回调函数 complete () => void 否 查询结束的回调函数（成功失败都会执行）

DramaListResult 的属性值

名称	类型	必备	兼容性
dramas	Array<DramaInfo>	是
名称 类型 必备 兼容性 dramaId string 是 title string 是 coverUrl string 是 desc string 是 categoryId number 是 categoryName string 是 currentEpisode number 是 totalEpisodes number 是 groupId number 是 unlockIndex number 是 styleType number 是 duration number 是 rawInfo UTSJSONObject 否
extra	UTSJSONObject	是

IUniDramaError 的属性值

名称	类型	必备	兼容性	描述
errCode	number	是		短剧错误对象。
errSubject	string	是		统一错误主题（模块）名称
data	any	否		错误信息中包含的数据
cause	Error	否		源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

getHistoryList(options : DramaListOptions) : void

getHistoryList

getHistoryList 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性	描述
options	DramaListOptions	是		列表查询参数：page 从 1 开始；success/fail/complete 与 open(options) 形态一致。
名称 类型 必备 兼容性 描述 page number 否 pageSize number 否 order string 否 success (res: DramaListResult) => void 否 查询成功的回调函数 fail (err: IUniDramaError) => void 否 查询失败的回调函数 complete () => void 否 查询结束的回调函数（成功失败都会执行）

DramaListResult 的属性值

名称	类型	必备	兼容性
dramas	Array<DramaInfo>	是
名称 类型 必备 兼容性 dramaId string 是 title string 是 coverUrl string 是 desc string 是 categoryId number 是 categoryName string 是 currentEpisode number 是 totalEpisodes number 是 groupId number 是 unlockIndex number 是 styleType number 是 duration number 是 rawInfo UTSJSONObject 否
extra	UTSJSONObject	是

IUniDramaError 的属性值

名称	类型	必备	兼容性	描述
errCode	number	是		短剧错误对象。
errSubject	string	是		统一错误主题（模块）名称
data	any	否		错误信息中包含的数据
cause	Error	否		源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

search(options : DramaSearchOptions) : void

search

search 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性	描述
options	DramaSearchOptions	是		搜索参数：isFuzzy 为 true 时模糊匹配（默认 true）；success/fail/complete 与 open(options) 形态一致。
名称 类型 必备 兼容性 描述 searchWord string 是 isFuzzy boolean 否 page number 否 pageSize number 否 success (res: DramaListResult) => void 否 搜索成功的回调函数 fail (err: IUniDramaError) => void 否 搜索失败的回调函数 complete () => void 否 搜索结束的回调函数（成功失败都会执行）

DramaListResult 的属性值

名称	类型	必备	兼容性
dramas	Array<DramaInfo>	是
名称 类型 必备 兼容性 dramaId string 是 title string 是 coverUrl string 是 desc string 是 categoryId number 是 categoryName string 是 currentEpisode number 是 totalEpisodes number 是 groupId number 是 unlockIndex number 是 styleType number 是 duration number 是 rawInfo UTSJSONObject 否
extra	UTSJSONObject	是

IUniDramaError 的属性值

名称	类型	必备	兼容性	描述
errCode	number	是		短剧错误对象。
errSubject	string	是		统一错误主题（模块）名称
data	any	否		错误信息中包含的数据
cause	Error	否		源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

getInfo(options : DramaInfoOptions) : void

getInfo

getInfo 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性	描述
options	DramaInfoOptions	是		指定短剧信息查询参数：dramaId 与 dramaIds 二选一；success/fail/complete 与 open(options) 形态一致。
名称 类型 必备 兼容性 描述 dramaId number 否 dramaIds Array<number> 否 success (res: DramaListResult) => void 否 查询成功的回调函数 fail (err: IUniDramaError) => void 否 查询失败的回调函数 complete () => void 否 查询结束的回调函数（成功失败都会执行）

DramaListResult 的属性值

名称	类型	必备	兼容性
dramas	Array<DramaInfo>	是
名称 类型 必备 兼容性 dramaId string 是 title string 是 coverUrl string 是 desc string 是 categoryId number 是 categoryName string 是 currentEpisode number 是 totalEpisodes number 是 groupId number 是 unlockIndex number 是 styleType number 是 duration number 是 rawInfo UTSJSONObject 否
extra	UTSJSONObject	是

IUniDramaError 的属性值

名称	类型	必备	兼容性	描述
errCode	number	是		短剧错误对象。
errSubject	string	是		统一错误主题（模块）名称
data	any	否		错误信息中包含的数据
cause	Error	否		源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

open(options : DramaOpenOptions) : void

open

open 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性	描述
options	DramaOpenOptions	是		打开短剧播放页参数（含 success/fail/complete 回调）。
名称 类型 必备 兼容性 描述 dramaId string 是 短剧 ID（与 DramaInfo.dramaId 一致，统一为 string） episode number 否 起播集数，默认 1 lock number 否 单次激励视频解锁的集数，默认 1 free number 否 初始免费观看集数，默认 1 urlCallback DramaUrlCallback 否 服务端回调透传参数：激励发放时回传服务器校验。 名称 类型 必备 兼容性 userId string 否 extra string 否 success () => void 否 播放页打开成功的回调函数 fail (err: IUniDramaError) => void 否 播放页打开失败的回调函数 complete () => void 否 打开结束的回调函数（成功失败都会执行）

IUniDramaError 的属性值

名称	类型	必备	兼容性	描述
errCode	number	是		短剧错误对象。
errSubject	string	是		统一错误主题（模块）名称
data	any	否		错误信息中包含的数据
cause	Error	否		源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

destroy() : void

destroy

destroy 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

onLoad(callback : DramaSimpleCallback) : void

onLoad

onLoad 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性
callback	(res: UTSJSONObject) => void	是

offLoad(callback : DramaSimpleCallback) : void

offLoad

offLoad 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性
callback	(res: UTSJSONObject) => void	是

onError(callback : DramaErrorCallback) : void

onError

onError 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性
callback	(err: IUniDramaError) => void	是

IUniDramaError 的属性值

名称	类型	必备	兼容性	描述
errCode	number	是		短剧错误对象。
errSubject	string	是		统一错误主题（模块）名称
data	any	否		错误信息中包含的数据
cause	Error	否		源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

offError(callback : DramaErrorCallback) : void

offError

offError 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性
callback	(err: IUniDramaError) => void	是

IUniDramaError 的属性值

名称	类型	必备	兼容性	描述
errCode	number	是		短剧错误对象。
errSubject	string	是		统一错误主题（模块）名称
data	any	否		错误信息中包含的数据
cause	Error	否		源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

onPlayEvent(callback : DramaEventCallback) : void

onPlayEvent

onPlayEvent 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性
callback	(res: DramaEventResult) => void	是

DramaEventResult 的属性值

名称	类型	必备	兼容性
event	string	是
info	UTSJSONObject	是

offPlayEvent(callback : DramaEventCallback) : void

offPlayEvent

offPlayEvent 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性
callback	(res: DramaEventResult) => void	是

DramaEventResult 的属性值

名称	类型	必备	兼容性
event	string	是
info	UTSJSONObject	是

onAdEvent(callback : DramaEventCallback) : void

onAdEvent

onAdEvent 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性
callback	(res: DramaEventResult) => void	是

DramaEventResult 的属性值

名称	类型	必备	兼容性
event	string	是
info	UTSJSONObject	是

offAdEvent(callback : DramaEventCallback) : void

offAdEvent

offAdEvent 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性
callback	(res: DramaEventResult) => void	是

DramaEventResult 的属性值

名称	类型	必备	兼容性
event	string	是
info	UTSJSONObject	是

onUnlockEvent(callback : DramaSimpleCallback) : void

onUnlockEvent

onUnlockEvent 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性
callback	(res: UTSJSONObject) => void	是

offUnlockEvent(callback : DramaSimpleCallback) : void

offUnlockEvent

offUnlockEvent 兼容性 ^?

Web	微信小程序	支付宝小程序
x	x	x

参数

名称	类型	必填	兼容性
callback	(res: UTSJSONObject) => void	是

Tips

• 短剧广告仅支持 Android 平台。

参见

• 相关 Bug
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

通用类型

GeneralCallbackResult

名称	类型	必备	描述
errMsg	string	是	错误信息