TikTok Minis Player

Your app must use the official TikTok Minis player (VePlayer) to play reviewed mini drama episodes. This helps protect copyright safety and ensures a consistent playback experience. After your content passes review, your server prepares the required playback data, such as album_id, episode_id, vid, and a play credential, and your app uses VePlayer through the TikTok Minis SDK to render and control playback.

Integrate VePlayer

Follow these steps to integrate VePlayer into your mini app.

Step 1: Get the player

1. Initialize the TikTok Minis SDK when the page loads.
2. Obtain and cache the VePlayer constructor.

Parameters

TTMinis.getPlayer(channel) // channel: 'byteplus' | 'volcengine'. Returns Promise<typeof VePlayer>. Call init() first.

Example:

let VePlayerCtor = null;
TTMinis.getPlayer().then((VePlayerClass) => {
  VePlayerCtor = VePlayerClass;
});

Step 2: Prepare playback data

Get approved video information from your server. This includes:

Step 3: Play video

Create player

Reserve a player container element on the playback page, and use the constructor of the player VePlayer obtained in the previous step to create the player as follows:

<div id="player-container-xx" style="width: 100%; height: 100%" />

const playerSdkIns = new VePlayer({
   id: 'player-container-xx', // The id of the player container element
   vid: 'sdsd3**33', // video id from BytePlus
   lang: 'en', // UI language
   albumId: videoInfo.album_id, // album id
   episodeID: videoInfo.episode_id, // episode id
   defaultDefinition: '720p', // default definition, If there is no need to transcode the video into multiple resolutions, it can be left unset.
   getVideoByToken: {
     playAuthToken: videoInfo.play_auth_token, // play temporary credential
   }
});

Each player instance must use a unique container. Make sure the container has the correct size through CSS.

If you use a framework such as React, you can also pass the corresponding root field through the HTMLElement object.

import { useEffect, useRef } from "react";
import * as React from "react";

export const PlayerComponent = (props) => {
  const rootRef = useRef(null);
  const playerSdkRef = useRef(null);

  useEffect(() => {
    const root = rootRef.current;
    if (!root) return;
    if (playerSdkRef.current) return;

    playerSdkRef.current = new VePlayer({
      root,
      vid: props.videoInfo.vid,
      albumId: props.videoInfo.album_id,
      episodeID: props.videoInfo.episode_id,
      getVideoByToken: {
        playAuthToken: props.videoInfo.play_auth_token,
      },
    });

    return () => {
      playerSdkRef.current?.destroy();
      playerSdkRef.current = null;
    };
  }, []);

  return React.createElement('div', { ref: rootRef, className: 'player-container' });
};

The player provides a rich set of UI plugins. Because mini dramas are immersive, choose a simpler configuration, for example:

const playerSdkIns = new VePlayer({
  id: 'player-container-xx', // player container id
  vid: 'sdsd3**33', // videovid
  lang: 'en', // UI language, support en、zh-cn、jp
  vid: videoData.vid, // video id
  albumId: videoData.albumId, // album id
  episodeId: videoData.episodeId, // episode id
  closeVideoClick: false, // Whether to toggle play/pause via video click/touchend behavior
  closeVideoDblclick: true, // Whether to toggle play/pause via video double click/touchend behavior
  videoFillMode: "fillWidth", // video fill mode
  getVideoByToken: {
    playAuthToken: videoData.playAuthToken, // play auth token
    needPoster: true, // whether to need poster
  },
  ignores: [
    "moreButtonPlugin", // more button plugin at the top right corner
    "enter", // enter plugin
    "fullscreen", // fullscreen plugin
    "volume", // volume plugin
    "play", // play plugin
    "pip", // picture in picture plugin
    "replay", // replay plugin
    "playbackrate", // playback rate plugin
    "sdkDefinitionPlugin", // definition plugin
  ],
  commonStyle: {
    playedColor: "#ffffff", // played color of the progress bar after playback is completed
  },
  mobile: {
    gradient: "none", // gradient of the container background in mobile
  },
  sdkErrorPlugin: {
    isNeedRefreshButton: false, // whether to need refresh button
  },
  start: {
    disableAnimate: true, // whether to disable animate
    isShowPause: true, // whether to show pause button
  },
});

Playback interface calls

1. Playback control is provided by the player kernel.

playerSdkIns.on(VePlayer.Events.READY, () => {
  const player = playerSdk.player; // Obtain player kernel
  console.log('player core', player);
})

1. Get the properties of the player kernel. For example, to get the current playback time:

const currentTime = playerSdkIns.player?.currentTime; // get current play time
const paused = playerSdkIns.player?.paused; // is paused
const ended = playerSdkIns.player?.ended; // is playing ended

1. Call the methods of the player kernel. Taking the call of the play and pause methods as an example, the sample code is as follows:

const playBtn = document.getElementById('play_btn'); // call player.play() based on user action
playBtn.addEventListener('click', (e) => {
  playerSdkIns.player?.play();
});

const pauseBtn = document.getElementById('pause_btn'); // call player.pause() based on user action
pauseBtn.addEventListener('click', (e) => {
  playerSdkIns.player?.pause();
});

1. Switch video: If you need to switch videos without destroying the player instance, you can call the playNext method and pass in the new video information.

playerSdkIns.playNext({
  albumId: nextVideoData.albumId,
  episodeId: nextVideoData.episodeId,
  vid: nextVideoData.vid,
  getVideoByToken: {
    playAuthToken: nextVideoData.playAuthToken, // play auth token
  },
}).then(() => {
  console.log('play next video completed');
});

Monitor playback status

The player provides a full event monitoring mechanism so you can implement playback-related features as needed.

• Listen for playback errors:

playerSdkIns.on(VePlayer.Events.ERROR, (error) => {
  // error TODO
})

• Listen and play

playerSdkIns.on(VePlayer.Events.PLAY, () => {
  // TODO after play
})

• Listen for playback time updates:

playerSdkIns.on(VePlayer.Events.TIME_UPDATE, (data) => {
  const { currentTime } = data;
  console.log('currentTime: ', currentTime);
})

For more information, refer to the events reference from BytePlus.

Destroy player

Destroy the player instance after playback is complete and the player is no longer needed.

playerSdkIns.destroy();

VePlayer reference documents

Other relevant documents for the VePlayer are listed. License configuration is not required for TikTok Minis.

• Web Player SDK: Initialization parameters
• Web Player SDK: External subtitles
• Web Player SDK: Customizing UI
• Web Player SDK: Player kernel
• Web Player SDK: Events

Acquire video playback token (for older client versions)

Invoke this API to retrieve a play credential used for video playback on older versions of the app (TikTok versions below 44.5.0).

Base info

Request parameters

Example

curl --location --request GET 'https://open.tiktokapis.com/v2/sg/shortdrama/play_token?client_key=mnxxxxxxxxxxxxx&episode_id=3453425324534' \
--header 'Authorization: Bearer xxxxx'

Response

Migrate from a third-party player

If you use a third-party player or native HTML video, TikTok will replace it with a default blocked UI. You can apply for an exemption to support gradual migration by submitting a support ticket or reaching out to your operations representative.

Before the exemption is available, if you need to customize the replaced UI elements, use the setValidateVideoReplaceElement API from the TikTok Minis SDK.

TTMinis.setValidateVideoReplaceElement(customReplaceElement: (
  videoEl: HTMLVideoElement,
  replaceReason: string,
) => HTMLElement | null)