tencent cloud

Tencent Cloud Super App as a Service

Short Drama

下载
聚焦模式
字号
最后更新时间: 2026-09-22 16:07:54
Note:
To enable the new short drama logic, configure "playlet": true in app.json.
The APIs require the superapp to integrate the Short Drama extension library. For integration instructions, see Extension SDK: Android | iOS

createPlayletPage

This API is called using wx.createPlayletPage().
Feature description:Initializes the player and returns the corresponding player instance PlayletPlugin.
Return value: PlayletPlugin.
const plugin = wx.createPlayletPage({
fail: (res) => {
console.error('[createPlayletPage] failed:', res.errMsg);
}
});
Note:
Due to the Mini Program page-stack limit (10 layers), the total number of business pages plus opened short-drama pages must be ≤ 10. When opening an episode would exceed this limit, the fail callback of wx.createPlayletPage() will receive the error: createPlayletPage:fail page stack is full, please navigate back first.

PlayletPlugin

PlayletPlugin is the player instance created using wx.createPlayletPage().

.onPageLoad(Function func)

This API is called using PlayletPlugin.onPageLoad(Function func).
Feature description:onPageLoad corresponds to the short drama page’s onLoad event, listening for when the short drama page finishes loading.
Parameter and description:
function func:Operations to execute when the short drama page loads.
Callback function parameter: Object res.
Property
Type
Description
playerId
String
Player Id
Example
playletPlugin.onPageLoad((res) => {
console.log('Page loaded, Player ID:', res.playerId);
});

.onPageDestroy(Function func)

This API is called using PlayletPlugin.onPageDestroy(Function func).
Feature description:Listens for the short drama page’s destroy event.
Parameter and description:
function func:Operations executed when the short drama page is destroyed.
Callback function parameter: Object res.
Property
Type
Description
playerId
String
Player ID
Example
playletPlugin.onPageDestory((res) => {
console.log('Page destroyed, Player ID:', res.playerId);
});

.getPluginVersion()

This API is called using PlayletPlugin.getPluginVersion().
Feature description:Retrieves the plugin version information.
Return value: String res version information.

playletPlugin.PlayletManager

Feature description:PlayletManager is a class that manages the player. It controls the core functions of short drama playback and can be accessed through playletPlugin.PlayletManager.getPageManager(playerId). Most APIs are provided on this instance, such as getInfo, setPlaylets, and more.
Parameters and descriptions: number playerId: Player ID.
Return value: PlayletManager, the player management instance.
Example

plugin.onPageLoad((info) => {
const playletManager = plugin.PlayletManager.getPageManager(info.playerId);
console.log('manager',manager);
})
In many APIs, you can obtain the playerId—for example, from the onPageLoad event, and then use the playerId to get the PlayletManager instance. Below is a detailed introduction to more APIs for the PlayletManager instance:

PlayletManager.setPlaylets (Object object)

Feature description:Initialize the episode status.
Parameter and description: Object object.
Field
Type
‍Required
Default value
Description
id
String
true
-
Drama ID
serialNo
Number
true
-
Episode ID
title
String
true
-
Drama name
imgUrl
String
false
''
Drama cover image
introduction
String
false
''
Short drama description
tags
Array
false
[]
Short drama tags
playRate
Number
false
1
Playback speed
extParam
String
false
{}
Extended parameters
clarity
Array
false
[
{ clarity: 240 * 426, title: "360P" },
{ clarity: 480 * 852, title: "480P" },
{ clarity: 720 * 1280, title: "720P" },
{ clarity: 1080 * 1920, title: "1080P" }
]
Video quality options
defaultClarity
Object
false
{ clarity: 480 * 852, title: "480P" }
Default video quality
initial-time
Number
false
0 
Initial playback time
data
Array
true
-
List of episode status
interaction
Object
false
-
Drama-level interaction data (favorite / share). See table below.
interaction (drama-level interaction data):
Field
Type
Required
Default
Description
interaction.favorite.enabled
Boolean
false
-
Whether to show the favorite button. Defaults to false.
interaction.favorite.isFavorited
Boolean
false
-
Whether currently favorited.
interaction.favorite.count
String
false
-
Favorite count text. Formatted by the business side (e.g. "1.2w").
interaction.share.enabled
Boolean
false
-
Whether to show the share button.
interaction.share.count
String
false
-
Drama-level total share count (string).
interaction.share.title
String
false
-
Share card title.
interaction.share.path
String
false
-
Share redirect path.
interaction.share.imageUrl
String
false
-
Custom share image. Supports local / code-package / network images.
Definition of the data field (Array of episodes, each item corresponds to an episode):
Field
Type
‍Required
Default
Description
status
Number
true
-
Playback status: 0 = free; 1 = unlocked; 2 = locked
VideoUrl
String
false
''
Video URL; not required for paid episodes
coverImg
String
false
-
Cover image; shown if imgUrl is not set
license-url
String
false
''
The license URL for playback
certificate-url
String
false
''
Certificate URL
provision-url
String
false
''
Device provisioning URL
interaction
Object
false
-
Episode-level interaction data (including likes) is detailed in the table below.
data[].interaction (episode-level interaction data):
Field
Type
Required
Default
Description
data[].interaction.like.enabled
Boolean
false
-
Whether to show the like button.
data[].interaction.like.isLiked
Boolean
false
-
Initial like state for this episode.
data[].interaction.like.count
String
false
-
Like count for this episode (string).
Example
PlayletManager.setPlaylets({
id: "sid", // Drama ID
serialNo: 1, // Episode ID, starting from 1
title: "Name",
imgUrl: "Image URL",
introduction: "Short drama introduction",
tags: ["Friendship", "Fantasy"],
playRate: 1,
extParam: "{{xxx}}",
clarity: [{"360p": 240 * 426}, {"480p": 480 * 852}, {"720p": 720 * 1280}, {"1080p": 1080 * 1920}], // Effective only under HLS
defaultClarity: {"720p": 720 * 1280}, // Default video quality
'initial-time': 0,
interaction: { // Drama-level interaction data (favorite / share)
favorite: { enabled: true, isFavorited: false, count: "1.2w" },
share: { enabled: true, count: "567", title: "Share title", path: "pages/xxx/xxx?id=1", imageUrl: "" }
},
data: [{
license-url: "",
certificate-url: "",
provision-url: "",
status: 0,
videoUrl: "Playback URL", // Not required for paid episodes
coverImg: "Cover image", // Not required
interaction: { // Episode-level interaction data (like)
like: { enabled: true, isLiked: false, count: "2.2w" }
},
}]
})

PlayletManager.setLockMenu( Object object )

Feature description:Sets the popup window for unlocking episodes. When playback reaches a locked episode, this popup will appear.
Parameter and description: Object object.
Field
Type
‍Required
Default value
Description
List
Array<FreeItem>
true
-
Episode unlock pop-up items, supports up to four entries
Definition of FreeItem fields:
Field
Type
‍Required
Default value
Description
Title
String
true
-
Name of the unlock operation
Callback
Function
true
-
The specific unlock operation
Example

PlayletManager.setLockMenu([
{
title: "Watch ad to unlock",
callback: (data) => {
if (!data.serialNo) {
return;
}
PlayletManager.setCanPlay(data.serailNo, 1)
}
},
{
title: "Purchase single episode",
callback: (data) => {
if (!data.serialNo) {
return;
}
PlayletManager.setCanPlay(data.serailNo, 1)
}
}
])
Note:
PlayletManager.setLockMenu() only sets the buttons shown in the unlock popup window. It does not control the display or hiding of the unlock page itself. You must use setCanPlay to actually control the visibility of the unlock page.

PlayletManager.hideLockMenu()

This API is called using PlayletManager.hideLockMenu().
Feature description:Hides the locked menu.

PlayletManager.setCanPlay(object object)

Feature description:Sets the unlock status of episodes.
Parameter and description: Object object.
Field
Type
‍Required
Default value
Description
SerialNo
Number
true
-
Episode ID
Status
Number
true
-
Playback status
VideoUrl
String
true
-
Playback URL
Example

const unlockData = [{
serialNo: 6, // Episode number
status: 1,
videoUrl: videoUrl // Playback URL
}];
PlayletManager.setCanPlay(unlockData);


PlayletManager.onCheckIsCanPlay(Function func)

Feature description:Event triggered when playback reaches an episode that requires unlocking.
Parameter and description:
function func:A callback function that listens for whether an episode can be played.
Example

manager.onCheckIsCanPlay((data) => {
let episodes = [];
if (data.episodes) {
episodes = data.episodes;
}

// Batch check and set status
const results = episodes.map(ep => {
const serialNo = ep.serialNo;
let status;

if (parseInt(serialNo) <= 3) {
// Assume the first 3 episodes are free
status = 0;
} else {
status = 2;
}
return { serialNo: serialNo, status: status };
});
manager.setCanPlay(results);
});


PlayletManager.onBack(Function func)

Feature description:Event triggered when clicking the back button in the top-left corner of the player.
Parameter and description:
function func:The callback function to listen for the back button click event.
Note:
Clicking the back button in the top-left corner of the short drama playback interface will trigger PlayletManager.onBack(). After returning, the player will be destroyed.

PlayletManager.play()

Feature description:Plays the episode.

PlayletManager.onPlay(Function func)

Feature description:Listens for the short drama play event.
Parameter and description:
function func:The callback function for when the short drama starts playing.

PlayletManager.pause()

Feature description:Pauses the video.

PlayletManager.onPause(Function func)

Feature description:Listen for the short drama video pause event.
Parameter and description:
function func:The callback function for when the short video is paused.

PlayletManager.onError(Function func)

Feature description:Listens for playback error events.
Parameter and description:
function func:The callback function for playback failure events.
Callback parameter:
Property
Type
Description
eventId
Number
Type of playback error event

PlayletManager.destroy()

Feature description:Destroys the short drama player.

PlayletManager.getInfo()

Feature description:Retrieves information about the current episode. Returns an object with the following fields:
Property
Type
Description
serialNo
Number
Episode ID
playerId
String
Player ID
exParam
String
Sharing extension parameters
duration
String
Total duration of the current episode
playtime
String
Current playback time

PlayletManager.onCustomEvent(Function func)

Feature description:Receives native player status events, including user actions like switching episodes, changing playback speed, etc.
Parameter and description:
Function func:A callback function listening for user interactions with the native player.
Callback parameter:
Property
Type
Description
EventType
String

'CHANGE_SERIAL': Episode changed. Example: { slideType: 1 }. slideType values:
1: Auto-switch after playback ends (regardless of completion).
2: Switched by gesture slide.
3: Switched via episode selection popup.
'CHANGE_SPEED': Playback speed changed. Example: { source: 1, speedType: 1.5 }, source: Currently fixed at 1; speedType: Current playback speed.
'CHANGE_CLARITY': Playback clarity changed; returns the current clarity level.
Example
manager.onCustomEvent((data) => {
if (data.eventType === 'CHANGE_CLARITY') {
console.log('User changed clarity:', data.clarity);
}
if (data.eventType === 'CHANGE_SERIAL') {
console.log('User switched episode:', data.slideType);
}
if (data.eventType === 'CHANGE_SPEED') {
console.log('User changed playback speed:', data.speedType, data.source);
}
});

PlayletManager.onDataReport (Function func)

Feature description:Developers can register a callback function via this method to receive data reporting callbacks. Each event represents a reporting point, where event is an enum with the following possible values. Each reporting event includes some common fields sent back to the developer:
Field
Description
playerId
Player Id
extParam
Sharing extension parameters
serialNo
Current episode index, starting from 1
playTime
Current playback time
duration
Total duration of the current episode
totalCount
Total number of episodes
Additional fields specific to each event:
Field
Description
Description of additional fields
LOAD
Enter the player page
-
SHOW
Player page show
-
START_PLAY
Start to play
-
UNLOAD_OR_HIDE
Leave the page or return to the background
Example: {{type}} 1 }. Where type 1 = unload, type 2 = hide.
video.play()
Play event
-
VIDEO_TIME_UPDATE
Time update event
Parameters correspond to video component’s timeupdate event.
VIDEO_END
Video playback ended
-

PlayletManager.setInteractionState (Object object)

This API is called using PlayletManager.setInteractionState({...}).
Feature description:After the business side handles the like / favorite / share logic on its own, call this API to sync the UI state.
Example:
manager.setInteractionState({
serialNo: 1, // Episode number: required for type=like; optional for type=favorite/share
type: 'like', // Interaction type: 'like' | 'favorite' | 'share'
isActive: true, // Whether it is active (optional when type=share)
count: "1.2w" // Count text, string, formatted by the business side
})
Parameter description:
Field
Type
Required
Description
serialNo
Number
Only required for like
Episode number
type
String
true
'like' / 'favorite' / 'share'
isActive
Boolean
Optional for share
Whether it is active
count
String
false
Count text

PlayletManager.onLikeClick(Function func)

This API is called using PlayletManager.onLikeClick(func).
Feature description:Listens for the user's tap on the like button. After receiving the callback, the business side handles the like logic on its own (persistence / logging) and then pushes the latest state back to the component via setInteractionState.
Example:
manager.onLikeClick((args) => {
// args.playerId current player id
// args.id drama id
// args.serialNo episode number
// args.currentState state before the tap (false = not liked previously)
// args.extParam the extParam passed through in setPlaylets
})

PlayletManager.onFavoriteClick(Function func)

This API is called using PlayletManager.onFavoriteClick(func).
Feature description:Listens for the user's tap on the favorite button. Favorite is a drama-level action (not episode-level), so the callback has no serialNo.
Example:
manager.onFavoriteClick((args) => {
// args.playerId
// args.id
// args.currentState favorite state before the tap
// args.extParam
})

PlayletManager.onShareClick(Function func)

This API is called using PlayletManager.onShareClick(func).
Feature description:Listens for the user's tap on the share button.
Example:
manager.onShareClick((args) => {
// args.playerId
// args.id
// args.serialNo
// args.extParam
})

PlayletManager.setActivityInfo (Object object)

This API is called using PlayletManager.setActivityInfo({logo}).
Feature description:Displays a logo entry at a designated position on the playback page, commonly used for campaign redirects or promotional slots.
Example:
manager.setActivityInfo({
logo: 'https://miniprogram.tcsas-superapp.com/xxx/xxx.png'
})
Parameter description:
Field
Type
Required
Description
logo
String
true
URL of the promotional logo image (a square PNG, 24 × 24, is recommended)

PlayletManager.onSetActivityInfo(Function func)

This API is called using PlayletManager.onSetActivityInfo(func).
Feature description:Triggered when the user taps the promotional logo. The business side can open a campaign popup, navigate, or activate a custom area here.
Example:
manager.onSetActivityInfo((args) => {
// Triggered when the user taps the promotional logo
})

PlayletManager.updateOpenArea (Object object)

This API is called using PlayletManager.updateOpenArea({...}).
Feature description:Injects a custom component area on the left side of the player, for use as a campaign card, check-in area, ad slot, etc.
Example:
manager.updateOpenArea({
showLeft: true, // Whether to show the left custom area
playerId: '<optional>', // Specify the target player id
serialNo: 1, // Current episode number
ext: JSON.stringify({ dramaId: 1 }) // Extra data (string) passed through to the custom component
})
Parameter description:
Field
Type
Required
Description
showLeft
Boolean
true
true to show, false to collapse
playerId
String
false
Specifies the target player instance in multi-player scenarios
serialNo
Number
false
Current episode number, passed to the component as a prop
ext
String
false
Custom pass-through data. JSON.stringify() before passing is recommended
Return value:Boolean — true / false, indicating whether the call succeeded.

Custom component integration

The business side must provide a standard Component in the Mini Program, which the plugin mounts inside the custom area. The component receives the following props:
Prop
Type
Source
ext
String
Passed through from updateOpenArea({ ext })
playerId
String
Current player id
serialNo
Number
Current episode number
The component may notify the plugin to close the custom area by calling triggerEvent('close').
Important:
The custom component must use native components such as cover-view / cover-image as its container, otherwise it will be occluded by the video layer and cannot display or receive taps properly. Regular view / image tags will be covered when placed above the player layer.
Minimal example - JS (pages/components/open-area-left/open-area-left.js):
Component({
properties: {
ext: { type: String, value: '' },
playerId: { type: String, value: '' },
serialNo: { type: Number, value: 0 }
},
methods: {
onJoinTap() {
// Business logic: navigate to the campaign page / open a popup, etc.
},
onCloseTap() {
this.triggerEvent('close'); // Notify the plugin to close the custom area
}
}
});
Minimal example - WXML (pages/components/open-area-left/open-area-left.wxml):
<cover-view style="display: flex; flex-direction: column; align-items: center; justify-content: center; width: 100%; height: 100%;">

<!-- Campaign banner image -->
<cover-image
src="https://miniprogram.tcsas-superapp.com/hackthon/upload_1755932019262.jpg"
style="width: 500rpx; height: 500rpx; border-radius: 16rpx;"
/>

<!-- Campaign title -->
<cover-view style="margin-top: 30rpx; font-size: 36rpx; font-weight: bold; color: #fff;">
Limited-time reward campaign
</cover-view>

<!-- Campaign description -->
<cover-view style="margin-top: 16rpx; font-size: 26rpx; color: rgba(255,255,255,0.8); text-align: center;">
Watch an ad to unlock all episodes for free
</cover-view>

<!-- Button area -->
<cover-view style="display: flex; flex-direction: row; margin-top: 40rpx; width: 100%; justify-content: center;">
<cover-view
style="width: 200rpx; height: 100rpx; line-height: 80rpx; font-size: 28rpx; background: #FF6B6B; color: #fff; border-radius: 36rpx; text-align: center; margin-right: 20rpx;"
bindtap="onJoinTap"
>Join now</cover-view>
<cover-view
style="width: 200rpx; height: 100rpx; line-height: 80rpx; font-size: 28rpx; background: rgba(255,255,255,0.3); color: #fff; border-radius: 36rpx; text-align: center;"
bindtap="onCloseTap"
>Close</cover-view>
</cover-view>

</cover-view>

PlayletManager.setRecommend (Array list)

This API is called using PlayletManager.setRecommend([...]).
Feature description:Sets the recommendation list inside the player. During playback the user may tap to switch to another drama.
Example:
manager.setRecommend([
{ id: 'drama_2', name: 'Palace Drama: Harem Legend', imgUrl: 'https://example.com/cover.jpg' },
{ id: 'drama_3', name: 'Mystery: Escape Room', imgUrl: 'https://example.com/cover.jpg' }
])
Parameter description:
Field
Type
Required
Description
id
String
true
Unique identifier of the recommendation item, echoed back unchanged in the callback
name
String
true
Name of the recommended drama
imgUrl
String
true
URL of the recommendation cover image

PlayletManager.onRecommendItemClick(Function func)

This API is called using PlayletManager.onRecommendItemClick(func).
Feature description:Listens for taps on a recommendation item. The business side can switch or open a new player based on the id.
Example:
manager.onRecommendItemClick((args) => {
// args.id — id of the recommendation item the user tapped (matches the id passed to setRecommend)
})

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈