Docs

Develop Your Mini Drama

During this stage, you will locally develop your mini drama app and integrate with necessary APIs.

Info: TikTok Minis implement HTML5 (H5) web technology with client-side functionalities from TikTok.

User perspective: The mini drama effectively acts as a mobile webpage with a faster loading speed than an H5 alone.
Developer perspective: Leveraging the H5 technology stack has a low development cost, especially if you already have a developed H5 webpage or app.

This guide explains how to develop a mini drama based on H5 runtime. Development broadly happens in two stages:

Develop your mini drama app locally
Install command-line interface (CLI) tool
Integrate with TikTok APIs for mandatory client-side capabilities

Build your mini app locally

Develop your mini drama app locally as an H5 page, making sure to abide by the technical standards and development restrictions listed below.

Technical standards for app development

When building your mini app, you should follow technical standards for mobile webpage development, with some constraints and extra capabilities. A completed project file should include the following directory structure:

.
├── dist // Build output
│   ├── ...
│   ├── minis.config.json  // [auto generated by CLI tool] sync from ./minis.config.json
│   ├── ...
├── ...
├── minis.config.json  // declare TikTok Minis configurations, such as navigation color
└── package.json

Development restrictions

Using the eval() function in JavaScript code is forbidden.
Using the Function constructor is forbidden.
Using string parameters in setTimeout() and setInterval() functions is forbidden.
In addition to introducing fonts, the src of script and CSS can only come from self resources.
iframe is not supported.
Some web APIs are forbidden, such as clipboard, location, and vibration APIs.
Server request addresses must be registered as trusted domains in the Security configurations section of your app page.

Install command-line interface tool

Note: Before setting up the CLI, ensure your environment meets the following requirements:

An existing H5 project that represents your mini app (the CLI integrates Minis framework capabilities into your standard web application).
Node.js and npm installed on your machine.

After completing development of your H5 mini app, install the command-line interface (CLI) tool to generate config files and debug.

npm install @tiktok-minis/cli@latest -g

Next, initialize configuration of your TikTok Minis JSON file by running the init command:

cd path/to/your/project
ttdx minis init

Running the init command in the product directory does the following three things:

Automatically generates the minis.config.json file in the mini app. You must fill in the requested information in minis.config.json. Providing your app'sclient_key is required.

{
  "dev": {
    "_comment": "clientKey" //  The client key of the app. Before you start to debug your app, you should replace it with real clientKey, and also replace it in your index.html TTMinis.init.
    "clientKey": "your-client-key",
    "name": "{{your_game_name}}",
    "host": "localhost",
    "port": 3000,
    "iconUrl": "{{your_icon_url}}",
    "desc": "{{your_description}}",
    "ppLink": "{{your_private_policy_url}}",
    "tosLink": "{{your_terms_of_service_url}}"
  },
  "navbar": {
    "bgColorLight": "#ffffff",
    "bgColorDark": "#000000"
  },
  "build": {
    "htmlEntry": "index.html",
    "outputDir": "dist"
  }
}

Automatically injects TikTok Minis SDK initialization code in index.html. TikTok Minis SDK is the JavaScript toolkit that provides access to TikTok's client-side functionalities, including authentication from your web app to TikTok. You need to replace the client_Key passed in TTMinis() with a valid value.

Note: In the TikTok Minis index.html, introduce TikTok Minis SDK to the first script tag and call TTMinis. Please call TTMinis() after the script is imported, otherwise the SDK will not be injected and the call will fail.

// index.html
<head>
<script src="https://connect.tiktok-minis.com/drama/sdk.js"></script>
<script>
  TTMinis.init({
    clientKey: `${your_client_key}`,
  });
</script>
</head>

Automatically injects console scripts in index.html, downloading the Eruda JavaScript library to allow for mobile debugging.

// index.html
<head>
...
 <script src="https://connect.tiktok-minis.com/libs/eruda.js"></script>
 <script>
    eruda.init();
 </script>
</head>

JSON configuration parameters

The minis.config.json file specifies global settings for your app, such as navbar colors and development configurations. Here’s an example configuration:

{
  "navbar": {
    "lightModeBgColor": "#ffffff",
    "darkModeBgColor": "#000000"
  },
  "dev": {
    "port": "3000",
    "host": "localhost"
  },
  "build": {
    "htmlEntry": "index.html" or "public/index.html"
    "output": "build" or "dist"
  }
}

Below is list of TikTok Minis JSON configuration parameters.

Parameters	Required	Type	Description
Navbar
navbar	No	`object`	Configuration items related to TikTok Minis navigation bar
navbar.bgColorLight	No	`string`	Navigation bar background color in light mode
navbar.bgColorDark	No	`string`	Navigation bar background color in dark mode
Dev
dev	No	`object`	Local development configuration items
dev.host	No	`string`	Example: localhost Default: localhost
dev.port	No	`number`	Example: 4000 Default: 3000
Build
build	No	`object`	Product build related configuration
build.outputDir	No	`string`	The folder name of the build product Example: dist \| build Default: build
build.htmlEntry	No	`string`	The frontend project html entry Example：`index.html` \| `public/index.html` Default：`public/index.html`
domain
domain.trustedDomains	Yes	`string[]`	Allowed API Request List

Example

// minis.config.json
{
  "navbar": {
    "lightModeBgColor": "#ffffff",
    "darkModeBgColor": "#000000",
  },
  "dev": {
    "port": "3000",
    "host": "localhost"
  },
  "build": {
    "outputDir": "build",
    "htmlEntry": "public/index.html"
  },
  "domain": {
    "allowList": ["https://www.xxx.com"]
  }
}

Integrate APIs for TikTok capabilities

TikTok provides a number of open capabilities through two complementary API bundles:

TikTok Minis SDK (TTMinis): A client-side JavaScript SDK that runs inside the TikTok app. It provides in-app capabilities like login and authorization, payments, UI triggers, rewarded ads, lifecycle hooks, networking, and capability detection.
TikTok Minis Server APIs (open.tiktokapis.com): A secure, backend-only suite of endpoints that manages identity and commerce for mini apps via OAuth v2 and scope-based permissions. It provides OAuth token retrieval, scope-gated user info retrieval, order creation and management, and pricing. Your backend stores and manages tokens and trade orders.

The open capabilities offered through these APIs allow your mini app to integrate seamlessly with the TikTok in-app experience and access TikTok's client-side functionalities.

Important: You are required to integrate several of these capabilities for your mini app to run correctly on TikTok. Such capabilities are listed below.

Function	APIs	Description	Required
Silent login	`TTMinis.login` `https://open.tiktokapis.com/v2/oauth/token/`	Obtain the users' OpenID and access token without explicit authorization	Yes
Explicit authorization	`TTMinis.authorize` `https://open.tiktokapis.com/v2/oauth/token/` `https://open.tiktokapis.com/v2/user/info/`	Obtain additional user data like username and avatar, requires user consent through an authorization screen	No
In-app ads (rewarded ads)	`TTMinis.createRewardedVideoAd`	Insert rewarded video ads into your mini app; IAA must be enabled to configure	Yes
In-app purchases	`https://open.tiktokapis.com/v2/minis/trade_order/create/` `TTMinis.pay`	Allow purchases to be made within your mini app; IAP must be enabled to configure	No
Navigation bar	`TTMinis.setNavigationBarColor` `TTMinis.getMenuButtonBoundingClientRect`	Set up and customize a navigation bar in your mini game	Yes

Login and authorization methods

You must choose and configure a login method for your mini app. Different levels of data require different methods for user login:

No data needed: No login required.
Basic data: To retrieve basic data like OpenID and access token, use Silent login, which logs the user in without an authorization screen.
Profile data: To retrieve profile data like username and avatar in addition to basic data, use Explicit authorization, which opens an authorization screen and requires the user to confirm.

Note: If you need to obtain more sensitive user data like email address or mobile phone number, you must reach out to your TikTok operations representative to undergo an extra compliance process.

To choose and and configure a login method, do the following:

Choose a login method depending on your data requirements.

Scenario	JavaScript API	Backend API	User interaction	Data acquired
No user data needed	Do nothing	None	None	None
Only OpenID and access token needed (for IAP)	`TTMinis.login()`	`https://open.tiktokapis.com/v2/oauth/token/`	Silent login: the user has no immediate perception, and no authorization screen appears.	OpenID, access token
Additional user info needed (such as username, avatar)	`TTMinis.authorize()`	`https://open.tiktokapis.com/v2/oauth/token/` `https://open.tiktokapis.com/v2/user/info/`	Explicit authorization: the user sees an authorization screen and must consent to authorization.	OpenID, access token, profile data

Configure your login method by calling the relevant JavaScript and backend APIs. The setup methods are listed:

Silent login
Explicit authorization

Take note that access tokens are temporary: they can expire, or the user can manually revoke your app's authorization. Take the following precautionary steps for error handling and fallback.

Error handling: Your server should be designed to handle 401 (Unauthorized) errors from TikTok's open APIs. When a 401 is received, the server should prompt the frontend to re-initiate the login (.login) or authorization (.authorize) process.
Fallback: If the explicit .authorize call fails (perhaps the user denied the pop-up), the frontend should immediately use the .login method as a fallback to ensure you at least obtain the basic OpenID (silent login) and avoid losing the player entirely.

Silent login

If your platform only needs to obtain the user's OpenID without requiring additional user information, use silent login. This is the recommended default for basic functionalities like In-App Purchases (IAP), as it doesn't interrupt the user.

Call the JavaScript API: Let the frontend call TTMinis.login to trigger the silent OAuth process in the background.
Success callback: If successful, the app receives an encrypted code, which is a temporary authorization code used for the next step.
Backend step (exchange code): The frontend must pass the obtained code to your server, so the server is able to exchange open_id and access_token by calling https://open.tiktokapis.com/v2/oauth/token/.

Example code:

TTMinis.login({
  success: (result) => {
    // The user has logged in and authorized the application
    // You can get the code and send it to the backend to exchange for open_id, access_token, and more
    let code = result.code;
  },
  fail: (error) => {
    // Other errors or the user did not authorize; code will be null
  },
  complete: () => {
    // This callback is triggered regardless of success or failure
  }
});

Explicit authorization

If your platform needs to obtain additional user information such as username and avatar, use explicit authorization. This method necessitates user consent via an authorization screen.

Call the JavaScript API: Let the frontend call TTMinis.authorize , specifying the desired level of user data via the scope parameter.

Define scope: The scope user.info.basic tells the TikTok platform exactly what information you are requesting (in this case, basic user profile info like username and avatar). This triggers the user-facing pop-up.

Warning: Do not call this immediately when the user enters the app. Users may reject the request, and you will lose the chance to get their OpenID. Call this function only when the feature requiring the data (for example, a personalized leaderboard) is needed.

Success callback: If successful, the app receives an encrypted code, which is a temporary authorization code used for the next step.
Backend step (exchange code): The frontend must pass the obtained code to your server, so the server is able to exchange open_id and access_token by calling https://open.tiktokapis.com/v2/oauth/token/.
Backend step (get user data): After acquiring the access token, the server makes a second call to https://open.tiktokapis.com/v2/user/info/ to fetch the actual profile data (username, avatar) that the user explicitly authorized.

Example code:

TTMinis.authorize({
  // If you require other user permissions, please refer to https://developers.tiktok.com/doc/tiktok-api-scopes
  scope: "user.info.basic",
  success: (result) => {
    // The user has logged in and authorized the application
    // You can get the code, and send it to the backend to exchange for open_id, access_token
    let code = result.code;
  },
  fail: (error) => {
    // Other errors or unauthorized (user did not grant permission); code will be null
  },
  complete: () => {
    // This callback is triggered regardless of success or failure
  }
});

Learn more about TikTok's login and authorization JavaScript APIs.

Monetization features

If you plan on monetizing your mini app, you first enable monetization features in the Developer Portal to gain access to TikTok's monetization capabilities.

Review the monetization overview and process for mini apps.
Enable your desired monetization features in the Developer Portal. This step can only be performed by an organizational admin.
Configure monetization features for your mini app:

In-app ads
In-app purchases

In-app ads (IAA)

To configure in-app ads for your mini app, IAA must be enabled for your mini app. Rewarded ads specifically are required for mini apps.

Learn more about how to configure IAA for your mini app.

In-app purchases (IAA)

To configure in-app purchases for your mini app, IAP must be enabled for your mini app.

Note that there are two types of in-app purchaes: one-time purchases with TikTok Beans and subscriptions.

Learn more about how to configure IAP for your mini app.

User interface

Configure a navigation bar in your mini app that adapts to the user's device.

Navigation bar

Since it is necessary to adapt to the custom navigation bar, add it to the original configurationstyle. This allows developers to configure the style of the navigation bar. The specific config modification is as follows:

{
  "navbar": {
    "style": "custom",    // custom: custom navigation bar, default: default navigation bar
    "bgColorLight": "#ffffff",
    "bgColorDark": "#000000",
  },
  ...
}

Parameter	Description	Values
style	The style of the navigation bar, default style if not set	`custom`: Custom navigation bar. Developers can customize the style of the navigation bar. `default`: The default navigation bar is provided by Minis Framework and only supports color modification.

To set the foreground and background colors of the navigation bar, call TTMinis.setNavigationBarColor.

Parameter	Type	Description
frontColor	string	Foreground color value, including the color of buttons, titles, and status bars, only supports #ffffff and #000000
backgroundColor	string	Background color value, valid value is hexadecimal color

if (TTMinis.canIUse("setNavigationBarColor")) {
    TTMinis.setNavigationBarColor({
      frontColor: string;
      backgroundColor: string;
    }, function (res) {
      console.log(res.is_success);
    })
}

To customize the navigation bar, you must first obtain the position of the menu button. You can then create a custom navigation bar according to the position of the menu button. The position of the capsule button provides the TTMinis.getMenuButtonBoundingClientRect()API to get the layout position information of the menu button (the capsule button in the upper right corner). The coordinate information is based on the upper left corner of the screen as the origin.

Parameter	Type	Description
width	number	Width, unit: px
height	number	Height, unit: px
top	number	Upper boundary coordinate, unit: px
right	number	Right border coordinates, unit: px
bottom	number	Lower boundary coordinate, unit: px
left	number	Left boundary coordinate, unit: px

The menu button layout is formatted as such: capsuleButtonLayout = {"left": xx, "right": xx, "top": xx, "bottom": xx, "width": xx, "height": xx}

Note: Since the coordinate information is based on the upper left corner of the screen as the origin, this api only takes effect when style == custom. When style == default, these params are all 0

const capsuleButtonLayout = TTMinis.getMenuButtonBoundingClientRect();

// Based on the position of the button as a reference, set the position of other elements to achieve alignment and other capabilities

Obtain additional data

Note that TikTok user-specific data must obtained through TikTok Minis Server API according to the standard OAuth2.0 protocol, or through the APIs listed within TikTok Minis SDK.

If your project requires details about a user's environment, like language and operating system, you can obtain the data using standard browser capabilities. For example:

obtain language:

const currentLang = navigator.language || navigator.userLanguage;

obtain OS:

function getOS() {
    const userAgent = navigator.userAgent || navigator.vendor || window.opera;

Was this document helpful?