Docs

In-App Ads: Interstitial Ads

Interstitial ads are used to display one-time, full-screen ads within TikTok Minis. They are suitable for transitions between chapters, page switches, or completion of stage-based milestones.

Your frontend creates an interstitial ad instance by calling TTMinis.createInterstitialAd(), and then pulls up the ad via show(). After the ad is closed, the frontend resumes the subsequent business process.

The overall process is consistent with the interstitial ad integration solution for mini games, except that the frontend JavaScript API is replaced with the Minis specific TTMinis.createInterstitialAd().

Prerequisites

Before setting up interstitial ads, you must have completed the following preconditions:

Your app page has completed integration with the Minis JSSDK
SDK initialization has been correctly completed in HTML

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

The current project can be successfully launched locally and meets the following basic requirements:

The project root directory exists package.json
Package.json at least provide dev or start startup script
The project root directory exists minis.config.json

You have completed business verification
You have enabled the IAA capability on the Developer Portal
You have created and activated an interstitial ad placement on the Developer Portal
It is recommended to check environmental support through TTMinis.canIUse('createInterstitialAd') first

If you need to directly display timing diagrams in Feishu or other document systems that support PlantUML, you can use the file in the same directory:

docs/capabilities/ad/interstitial-ad.puml

Applicable scenarios

We recommend integrating interstitial ads in the following scenarios:

Inserting an ad impression before or after page jumps
Providing monetization upon completion of a stage-based task

Not recommended:

Triggering upon opening TikTok Minis or opening a short drama
High-frequency continuous triggering
Repeatedly interrupting users during key operations

Best practices

Perform canIUse detection before ad display
Activate the ad placement immediately after creation
Use a new ad instance for each display
Resume the business process after the ad is closed
Have a fallback strategy when the ad fails; do not block the main process

Interstitial ads integration process

Step 1: Create and activate an interstitial ad placement

Before officially calling the interstitial ad, you must first complete these steps on your app page in the Developer Portal:

Go to your app's Monetization page under the Operation tab.
Go to the In-App Ads (IAAs) tab, then click the Ad placements toggle.
Click the Add ad placement button.

Enter the name of your ad, select the ad type, then click the Add button.

Rewarded ad
Interstitial ad

Switch the ad's status toggle to Active.

Note: Ad placements are inactive by default and must be switched to Active to be used.

Obtain the Placement ID of the ad you want to introduce as an interstitial ad.

Step 2: Frontend version compatibility

Check the TikTok version to ensure compatibility with interstitial ads:

if (TTMinis.canIUse(createInterstitialAd)) {
// Interstitial ads can be called
} else {
// Show a pop-up with a message such as: "Your TikTok version is outdated; please update TikTok."
}

Step 3: Frontend creates an interstitial ad instance

Your frontend calls:

const interstitialAd = window.TTMinis.createInterstitialAd({
  adUnitId: 'your_interstitial_ad_unit_id',
});

Step 4: Frontend registers callbacks

You should register at least two types of callbacks:

onClose is used to detect whether the ad has been closed.
onError is used to monitor anomalies, such as ad material retrieval failures or playback failures.

Step 5: Frontend calls show() to display the ad

Your frontend uses .show to initiate ad display.

interstitialAd.show()

Step 6: Resume business process after the ad closes

Interstitial ads themselves do not carry the business semantics of "granting rewards after finishing." The general practice is:

Wait for the ad to close after it has been displayed successfully
Resume the original page flow after the ad is closed
If the ad fails, determine whether to gracefully degrade and continue execution

Frontend integration example

const interstitialAd = window.TTMinis.createInterstitialAd({
  adUnitId: 'your_interstitial_ad_unit_id',
});

const handleClose = () => {
  interstitialAd.offClose(handleClose);
  console.log('Interstitial ad closed; proceeding with the next steps');
  continueBusinessFlow();
};

const handleError = (err) => {
  interstitialAd.offError(handleError);
  console.error('interstitial ad error', err);
  continueBusinessFlow();
};

interstitialAd.onClose(handleClose);
interstitialAd.onError(handleError);

interstitialAd.show().catch((err) => {
  console.error('interstitial ad show failed', err);
  continueBusinessFlow();
});

Debugging recommendations

We recommend conducting joint debugging in the following order:

First, confirm that the interstitial ad placement has been created and activated
Use TTMinis.canIUse('createInterstitialAd') to determine whether the current environment supports it
Start minis dev
Connect to the client environment by scanning the QR code
Trigger ad display at the business transition node
Verify separately:

Normal display followed by closure
Ad material retrieval failure
Client unsupported

Frequently asked questions

Why does the client not support interstitial ads?

The interstitial ad capability relies on the client version. We recommend that developers always perform canIUse detection before calling.

Why does the ad close immediately after displaying?

Common causes include:

Failed to retrieve ad creatives
An exception occurred during playback
The current ad placement or environment does not meet display conditions

Can one ad instance repeatedly call show()?

This is not recommended. The current recommended practice is:

Recreate a new interstitial ad instance before each display

Do interstitial ads need to grant rewards?

Generally, no. Interstitial ads typically provide display and impressions. Unlike rewarded video ads, they do not require granting rewards based on isEnded.

Are there any frequency control requirements?

We recommend handling frequency control at your business layer to avoid:

Repeated display within an excessively short time period
Multiple interruptions to the user during a single session

Was this document helpful?