抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台

接入说明

使用限制

在使用插件中的组件和 API 前,需要对行业插件有一个基本了解,可以参考文档:行业插件介绍

版本校验

短剧拓展只在抖音、抖音极速版、抖音火山版 30.3 及以上版本支持,使用前可通过 canIUse 校验当前抖音能否使用。若不支持,开发者可使用 video-player 组件或提示用户升级抖音。
// 看播页内部 if (!tt.canIUse('PlayletExtension')) { // 调用构造器前,判断是否可用 // 跳转至开发者自有播放页 或提示用户升级抖音 tt.navigateTo({ url: `xxx`, }); } PlayletExtension({ xxx })

拓展引入

新建小程序组件,在index.json中对插件进行绑定
{ "extends": "ttf57583c86a3aace011://playlet-plugin", "usingComponents": { "player": "../components/player/player", "charge": "../components/charge/charge" }, "isPageExtension": true }
在 js 文件中,通过 PlayletExtension 构造器来注册扩展,并提供扩展的属性定义、内部数据和自定义方法。
const { PlayletExtension, getPlayletManager } = plugin; PlayletExtension({ pm: undefined, data: { xxx: '', }, methods: { onLoad(option) {}, onReady() { // 通过返回的handler pm 对插件页进行操作 const pm = getPlayletManager(this); this.pm = pm; this.pm.setConfig(...); }, // 开发者自定义方法 customFunction() {}, }, });

跳转和query

可直接跳转至绑定短剧的页面。
tt.navigateTo({ url: `/page/xxx/index?tt_album_id=${albumId}&tt_episode_id=${episodeId}`, });
续播
播放器支持自动定位到用户上次观看的集数和播放进度,需要开发者在query中增加is_continue=1,即可开启。当传入1时,播放器会根据当前tt_album_id续播用户上次播放的集数,如果没有观看记录,则播放tt_episode_id指定的集数。
续播需要用户观看时长超过5s,且更新时间有一定延迟。
参数说明
属性名
类型
必填
说明
tt_album_id
string
拓展要打开的剧ID
tt_episode_id
string
拓展要打开的集数ID
is_continue
string
是否开启自动续播功能,传1为开启

沉浸式观看体验

在页面index.json 中,配置 "transparentTitle": "always" 对顶部导航栏透明化。
{ "extends": "ttf57583c86a3aace011://playlet-plugin", "usingComponents": {}, "transparentTitle": "always" }

避免Android拖动进度条触发返回

需在页面 index.json 中配置 "disableSwipeBack": "true" 以禁止当前页面侧滑返回
{ "extends": "ttf57583c86a3aace011://playlet-plugin", "usingComponents": {}, "transparentTitle": "always", "disableSwipeBack": true }

插件生命周期

onLoad

页面初始化时触发。一个页面只会调用一次。
    1.调用页面路由传递的参数可以在目标页面的 onLoad 中获取;
    2.在 onLoad 中不支持调用 setConfig、setCatalog 等主动 API

onShow

页面显示/切入前台时触发。该时机不能保证页面渲染完成,且会随页面可见性状态变化多次触发,如有页面/组件元素相关操作建议在 onReady 中处理

onReady

页面初次渲染完成时触发。 一个页面只会调用一次,代表页面已经准备妥当,可以和视图层进行交互。
建议在onReady中注册播放器事件的回调;

onUnload

页面卸载时触发。

onHide

页面隐藏/切入后台时触发。

开发者主动调用

setConfig - 开发者设置分享信息和自定义icon

开发者为播放器设置分享、自定义icon等参数

语法

pm.setConfig(options)

参数说明

options 为 object 类型,属性如下:
属性名
类型
必填
说明
shareParam
ShareParam
小程序分享参数
activityInfo
ActivityInfo[]
配置右下角自定义button,当前仅展示Array中的第一个icon
showLockPage
boolean
是否展示解锁页,默认为true
objectFit
'contain' | 'cover' | 'fill'
设置视频展现形式,竖屏场景默认为cover,横屏场景默认为contain
playbackRate
0.75 | 1.0 | 1.25 | 1.5 | 2
播放倍速,默认为1
catalogLockEnable
boolean
开启setCatalog超时默认锁定全部剧集数的兜底,默认true
catalogLockTimeout
number
setCatalog超时时间,单位秒,默认5s

ShareParam

配置分享参数
属性名
类型
说明
title
string
要转发的小程序标题
desc
string
这是默认的转发文案,用户可以直接发送,也可以在发布器内修改
path
string
示例:'page/xxx/index?tt_album_id=${albumId}&xxx=xxx'
后面的参数会在转发页面打开时传入onLoad方法
imageUrl
string
支持本地或远程图片,默认是小程序 icon
templateId
string
是开发者后台设置的分享素材模板id (获取可看小程序分享__抖音开放平台)

ActivityInfo

配置右下角自定义button
属性名
类型
说明
icon
string
自定义 icon 的图片(暂不支持本地文件)
title
string
自定义icon的标题,须填写 1-3 个汉字

PlaybackRate

配置播放器默认倍速
    同一剧集数仅支持设置一次,后续调用无效,需在 onReady 生命周期中设置。
    建议切换剧集数后可再次设置,应在 onChangeEpisode 时判断剧集数切换并设置。若不设置则保持与上一剧集数相同播放倍速。
// 首次进入时设置 onReady() { pm.setConfig({ playbackRate: 1.25 }) } // 推荐切剧 时再次设置 pm.onChangeEpisode((e) => { if (e.albumId !== this.albumId) { pm.setConfig({ playbackRate: 1.5 }) } })

返回值

使用示例

pm.setConfig({ shareParam: { // 分享数据 title: '测试小程序测试短剧 ', // 这是要转发的小程序标题 desc: '这是默认的转发文案,用户可以直接发送,也可以在发布器内修改', path: 'page/xxx/index?tt_episode_id=1&tt_album_id=${albumId}', // ?后面的参数会在转发页面打开时传入attached方法 imageUrl: 'https://e.com/e.png', // 支持本地或远程图片,默认是小程序 icon templateId: '这是开发者后台设置的分享素材模板id' }, activityInfo: [{ icon: 'https://xxx/xxx.png', title: '开辅助', }], playbackRate: 1.25, // 默认以1.25速度播放 catalogLockEnable: false, // 超时不锁定 });

getPlayletInfo - 开发者获取当前剧集数信息

开发者获取当前剧集数信息
在 onReady 生命周期时,页面逻辑刚开始执行可能无法获取剧集数信息,建议在切换剧集数时获取。

语法

pm.getPlayletInfo()

参数说明

返回值

返回一个promise对象;
属性名
类型
说明
albumId
string
剧ID
seq
number
集数
episodeId
string
集数ID

使用示例

pm.getPlayletInfo().then(res => { this.setData({ albumId: res.albumId, seq: res.seq, episodeId: res.episodeId }) });

setCatalog - 开发者更新目录设置

开发者主动更新当前目录
    pm.setCatalog的调用需要在生命周期 - onReady中onReady后
    如果该方法未按要求调用,则默认 5s 后设置剧集数锁定。

语法

pm.setCatalog()

参数说明

options 为 object 类型,属性如下:
属性名
类型
默认值
必填
说明
lockList
{start_episode_no: number, end_episode_no: number}[]
[]
拓展目录中,已锁定的页面范围
unlockList
{start_episode_no: number, end_episode_no: number}[]
[]
拓展目录中,已解锁的页面范围
freeList
{start_episode_no: number, end_episode_no: number}[]
[]
拓展目录中,免费的页面范围

返回值

使用示例

pm.setCatalog({ freeList: [{ start_episode_no: 1, end_episode_no: 5 }], unlockList: [{ start_episode_no: 6, end_episode_no: 10 }, { start_episode_no: 16, end_episode_no: 20 }, ], lockList: [{ start_episode_no: 11, end_episode_no: 15 }, { start_episode_no: 21, end_episode_no: 76 }, ], });

toggleCustomDialog - 开发者(打开 /关闭)自定义模块

充值模块显示规则:仅在短剧未解锁时出现

语法

pm.toggleCustomDialog(type?: 'open' | 'close')

参数说明

返回值

使用示例

// 观众点击“解锁按钮”时,可弹出自定义模块 pm.onClickUnlock((e) => { console.log("触发点击解锁按钮onClickUnlock回调:" , JSON.stringify(e,null,2)) pm.toggleCustomDialog(); })

setCurrentUnlock - 开发者设置当前集数为解锁

剧集数状态改变可以使用 setCatalog(范围)和 setCurrentUnlock(单集数)两种方式。
如果本集数处于解锁状态,则该方法不生效。

语法

pm.setCurrentUnlock()

参数说明

返回值

使用示例

this.ad.onClose((data) => { if (data.isEnded) { console.log("观看了", data.count, "个视频"); pm.setCurrentUnlock(); } else { console.log("未观看完视频"); }

setPlayStatus - 开发者设置暂停/播放状态

调用后,可控制当前视频的暂停或播放状态。

语法

pm.setPlayStatus(status)

参数说明

status 为 string 类型,属性如下:
属性名
类型
默认值
必填
说明
status
'play' 或者 'pause'

返回值

使用示例

pm.setPlayStatus('play') // 播放 pm.setPlayStatus('pause') // 暂停

setRecommendConfig - 设置推荐位

注意事项:目前推荐剧的toast弹窗需开发者自行制作,后续平台推出「基于平台算法推荐剧目」逻辑后,将自行封装 toast 弹窗(无需开发者开发)。
功能说明:新增短剧完播、左上角返回按钮支持推荐剧,开发者可设置推荐其他剧目。
开发者主动设置推荐位信息 详见:推荐位接入文档

setUnlockPreview - 设置试看

支持为已解锁剧集数设置指定时长的免费观看权限
接入文档详见:

setAdConfig - 配置Draw流广告策略

支持开启Draw流广告组件
接入文档详见:Draw流广告接入文档

观众行为回调

开发者可以使用 handler 处理注册的各种官方回调
pm.onPlay((e) => { console.log("触发开始播放onPlay回调:" , JSON.stringify(e,null,2)) }); pm.onPause((e) => { console.log("触发暂停播放onPause回调:" , JSON.stringify(e,null,2)) }); pm.onEnded((e) => { console.log("触发播放到末尾onEnded回调:" , JSON.stringify(e,null,2)) }); pm.onError((e) => { console.log("触发onError回调:" , JSON.stringify(e,null,2)) });

onPlay 视频开始播放

当视频开始播放时触发 play 事件。

使用示例

pm.onPlay((e) => { console.log("触发开始播放onPlay回调:" , JSON.stringify(e,null,2)) });

onPause 视频暂停

当视频暂停播放时触发 pause 事件。

使用示例

pm.onPause((e) => { console.log("触发暂停播放onPause回调:" , JSON.stringify(e,null,2)) });

onEnded 视频完成播放

当视频播放到末尾时触发 ended 事件。

使用示例

pm.onEnded((e) => { console.log("触发播放到末尾onEnded回调:" , JSON.stringify(e,null,2)) });

onError 视频播放出错

视频播放出错时触发 error 事件。
视频播放类错误码可参考:video 视频

使用示例

pm.onError((e) => { console.log("触发onError回调:" , JSON.stringify(e,null,2)) });

onTimeUpdate 播放进度变化时

当播放进度变化时触发该事件,返回当前播放时间点及视频总时长,单位:秒(s)。

返回值

属性名
类型
说明
currentTime
number
当前时间
duration
number
视频总时长

使用示例

pm.onTimeUpdate((e) => { console.log("触发播放进度变化onTimeUpdate回调:" , JSON.stringify(e,null,2)) })

onProgress 视频缓冲进度更新

视频缓冲进度变化时触发该事件。

返回值

属性名
类型
说明
buffered
number
百分比,取值是 [0, 100] 中的整数,如 buffered 为 50 表示当前视频缓冲了 50%。

使用示例

pm.onProgress((e) => { console.log("触发onProgress回调:" , JSON.stringify(e,null,2)) })

onWaiting 视频出现缓冲

视频出现缓冲时触发该事件。

使用示例

pm.onWaiting((e) => { console.log("触发onWaiting回调:" , JSON.stringify(e,null,2)) })

onPlayBackRateChange 视频倍速改变完成

视频倍速改变完成时触发该事件。返回改变后的倍速值。

返回值

属性名
类型
说明
playbackRate
number
视频倍速

使用示例

pm.onPlayBackRateChange((e) => { console.log("触发onPlayBackRateChange回调:" , JSON.stringify(e,null,2)) })

onControlTap - 点击控件

点击控件时触发。返回当前点击的控件类型。取值见表 controlType 的合法值。
注意:IDE 上的点赞、点亮是模拟操作,非真实抖音用户行为

controlType

说明
play
播放控件
pause
暂停控件
playbackRate
在倍速选择面板点击具体速度
progress
进度控件,在刚开始拖动进度条时触发
like
点击喜欢
unlike
点击不喜欢
share
点击分享
subscribe
点击追剧
unsubscribe
点击取消追剧
openCatalog
点击打开目录页
closeCatalog
点击关闭目录页
userCloseCharge
用户点击蒙层关闭充值页
openRatePanel
点击打开播放速度选择面板
closeRatePanel
点击关闭播放速度选择面板

使用示例

pm.onControlTap((e) => { console.log("触发onControlTap回调:" , JSON.stringify(e,null,2)) })

onOpenCatalog

当用户点击选集数时,系统触发该事件并通知开发者

使用示例

pm.onOpenCatalog((e) => { console.log("触发onOpenCatalog回调:" , JSON.stringify(e,null,2)) })

onChangeEpisode 观众切换剧集数

当用户点击选集数页中的具体集数,或通过上下滑动切换剧集数时,系统将触发事件并通知开发者

返回值

属性名
类型
说明
albumId
string
剧ID
seq
number
集数
status
'free'|'lock'|'unlock'
解锁状态
scene
'first_play' | 'swipe_next' | 'swipe_prev' | 'seq_select'
切换集数归因,分别因为“首次播放” | “滑动向下” | “滑动向上” | “选集数”导致的剧集数变化;
当 scene === 'first_play'(首次播放)时,status 字段为 undefined,此时剧集数锁定状态尚未完成初始化(需执行 setCatalog 方法)

使用示例

pm.onChangeEpisode((e) => { this.printLog("触发选集数切换onChangeEpisode回调:", JSON.stringify(e, null, 2)) })

onClickUnlock 观众点击解锁按钮

观众在播放界面点击了“立即解锁”按钮
如果setConfig中设置了showLockPagefalse,则蒙层与按钮不展示,无法触发该方法;

返回值

属性名
类型
说明
albumId
string
剧ID
seq
number
集数
episodeId
string
集数ID

使用示例

pm.onClickUnlock((e) => { this.ad.show(); // 监听视频播放完成 this.ad.onClose((data) => { if (data.isEnded) { console.log("观看了", data.count, "个视频"); // 也可以用 pm.setCatalog({}); 范围解锁 pm.setCurrentUnlock(); } else { tt.showToast({ title: '未观看完视频', }); } }); })

onTapShare 用户点击分享按钮,开发者返回实时分享参数

    1.path 参数必须以'/'开头,缺失该符号将导致分享链接失效
    2.onTapShare 的优先级高于 shareParam,如果同时设置则优先使用 onTapShare;

返回值

属性名
类型
说明
albumId
string
剧ID
seq
number
集数
episodeId
string
集数ID

使用示例

pm.onTapShare((e) => { const {} return { // 分享数据 title: '小程序标题', // 这是要转发的小程序标题 desc: '描述', path: 'page/xxx/index?tt_episode_id=1&tt_album_id=${albumId}', // ?后面的参数会在转发页面打开时传入attached方法 imageUrl: 'https://e.com/e.png', // 支持本地或远程图片,默认是小程序 icon templateId: '这是开发者后台设置的分享素材模板id' }, })

onShareSuccess 观众分享成功

使用示例

pm.onShareSuccess((res) => { console.log('shareSuccess-uuuu', res); })

onShareFail 观众分享失败

使用示例

pm.onShareFail((err) => { console.log('shareFail-uuuu', err); })

onTapCustomIcon 点击右下角自定义icon

返回值

属性名
类型
说明
index
number
点击第几个自定义icon

使用示例

pm.onTapCustomIcon((e) => { // 调用开发者自定义逻辑 })

onAddShortCut 添加桌面相关能力回调

当用户展示、关闭或点击添加桌面功能时,系统将触发对应事件
请使用tt.canIUse('playlet-plugin.onAddShortCut')判断该 API 是否可用

使用示例

pm.onAddShortCut((e) => { console.log("触发开始播放onAddShortCut回调:" , JSON.stringify(e,null,2)) });

返回值

属性名
类型
说明
type
'show' | 'click' | 'close'
播放器展示、点击或关闭添加桌面按钮时
position
'bottom' | 'function_area'
添加桌面位置:底部、功能区

开发者自定义组件

该能力已完成对外,官方文档:插件扩展能力
在短剧拓展场景中,需要定制的能力包括以下两种场景

创建插槽节点

自定义组件名必须包含 player 和 charge,否则组件将无法被正确识别和渲染。
在 js 文件中,通过 PlayletExtension 构造器来注册扩展,并提供扩展的属性定义、内部数据和自定义方法。
const { PlayletExtension, getPlayletManager } = plugin; PlayletExtension({ data: { idNo: '', }, methods: { // 开发者自定义方法 customFunction() {}, }, });
在对应的页面json文件中,配置自定义组件的路径;
{ "extends": "ttf57583c86a3aace011://playlet-plugin", "usingComponents": { "player": "../components/player/player", "charge": "../components/charge/charge" }, "disableSwipeBack": true, "isPageExtension": true }
在对应路径正常开发自定义组件;

OpenAPI

新播放插件页外--取消追剧

接口

基本信息

HTTP URL
HTTP Method
POST
HTTP Header
    Content-Type : 传固定值application/json

请求参数

字段名
类型
是否必填
描述
示例值
open_id
string
关联小程序下具体用户
"_000PwN_t4yU4LqFa9fvtspS75sn0x3lq_L_"
action_type
number
固定值,填2
2
action
number
固定值,填2
2
album_id
string
剧ID
"7330893816926962228"

响应参数

字段名
类型
是否必填
描述
示例值
err_no
number
错误码
    0 表示取消成功
0
err_msg
string
错误信息
""

请求示例

// 请求示例 curl --location 'https://open.douyin.com/api/resource_library/v1/user_action/' \ --header 'Tt-Host-Scheme: https' \ --header 'Content-Type: application/json' \ --header 'X-Tt-Logid: 02172051122807000000000000000000000ffff0a9a641dd13b7d' \ --header 'jaeger-baggage;' \ --header 'access-token: clt.XXXXXXXXXXX_hl' \ --header 'byted-trace-id: 108f945fa829c54506e16058b8b2f73:15247a0ac834c93e:15247a0ac834c926:5' \ --header 'traceparent: 02-0108f945fa829c54506e16058b8b2f73-15247a0ac834c93e-05' \ --header 'tracestate;' \ --header 'Cookie: passport_csrf_token=551e70161bac7ca39949a9edd36a81eb; passport_csrf_token_default=551e70161bac7ca39949a9edd36a81eb' \ --data '{ "open_id": "_000PwN_t4yU4LqFa9fvtspS75sn0x3lq_L_", "action_type": 2, "action": 2, "album_id": "1234" }' // 响应示例 { "err_no": 0, "err_msg": "", "log_id": "02172051122807000000000000000000000ffff0a9a641dd13b7d" }

第三方框架接入

uniapp
在page.json中进行依赖配置
"pages": [ //pages数组中第一项表示应用启动页,参考:https://uniapp.dcloud.io/collocation/pages { "path": "pages/index/index" }, { "path": "pages/playlet/index", "style": { "extends": "ttf57583c86a3aace011://playlet-plugin", "isPageExtension": true } } ],
在对应页面中进行插件声明
<template> </template> // template标签中的dom不会被应用在插件页中 <script> import Player from '@/components/player/player.vue'; import Charge from '@/components/charge/charge.vue'; const { PlayletExtension } = plugin; export default { components: { Player, Charge }, methods: { onShow() { console.log('show'); } }, }; </script>
(如果需要)使用uniapp语法引入component自定义组件,参考{ Player, Charge }的引用
自定义组件与播放页无法进行通信,但可通过pm.getPlayletInfopm.onPlay获取参数
在 player 或 charge 组件中,通过 const pm = await getPlayletManager({ is: "player | charge" }) 建立通信(需与插槽名称一致)

附:无法播放、卡顿等常见播放问题指引

通用排查思路

关键词:播放器丨播放问题 | 卡顿 | 无法播放 | 卡死 | 播不了 | 不可播 | 不能播 | Video | 诊断工具 | 用户反馈
一、针对常见播放问题,各位开发者可通过诊断工具快速获取原因。
二、查看用户反馈截图上所打印的信息,进一步判断可能的原因。
反馈时所处播放生命周期(status):
创建 video 中(onCreate)
    正在准备播放(onPrepare)
    已准备好播放(onPrepared)
    缓冲中(onBufferStart)
    缓冲结束(onBufferEnd)
    遇到报错(onError(code=XXX, msg=XXX))
反馈时所播放视频的码率信息(bitRate)
    截图打印信息中的码率的单位为 bps,建议不大于 1024kbps,建议值为 600kbps
    如果较多的反馈处于 onPrepare、onBufferStart 状态或 bitRate 显示大于 1024kbps,则可能与视频码率过大有关。
    如果处于onError状态,可以通过参照错误码列表进行处理。
    如果仅有“截图已打印调试信息”字样,无其他内容,则尚未走到播放环节,请排查前置流程。
三、如您已明确问题与视频码率有关,可按如下步骤处理:
【推荐】使用抖音云MP4转码,建议选择极致超清 MP4 720P H.265(在同等观感下码率更低);
修改您的转码参数:
    CRF质量等级不大于23
    编码格式为H.265
    分辨率不大于720P
四、若无法通过上述办法获取原因,请开发者在遇到问题时,立即通过小程序右上角进行反馈,并告知反馈内容或反馈 id。(此步骤有助于提升问题跟进和原因定位效率。)

白屏表现排查思路

黑屏表现排查思路

    1.视频没有声音没有画面,检查抖音云域名证书是否正常、域名是否欠费
    2.视频有声音没画面,重启抖音 App 并多次操作:关闭抖音 App 后台后重新进入