Interstitial Ad Component

1. Recommendations for Usage Scenarios

The interstitial ad component is suitable for the following scenarios:

Tab switching

• Show ads when switching from the home page to the store tab.

• Show ads when switching back to the home page from the personal page tab.

Game round completion

• Show ads at the end of each game round.

• Show ads after completing a game level.

Video playback pauses

• Show ads when a video stops playing.

• Show ads when a video is paused.

Workflow completion

• Show ads when completing a shopping and checkout process.

• Show ads after sharing content.

Not recommended for showing small program interstitial ads in the following scenarios:

• Do not insert ads when the user opens the small program.

• Do not interrupt the user's complete operation process.

• For example, do not insert ads during an immersive game process or a quick information flow pull-down refresh process.

2. API Documentation

Introduction

The interstitial ad component is composed of native image and text controls, and is the highest level component that covers regular components. Developers can call dlt.createInterstitialAd to create an interstitial ad component. Each time this method is called, a new instance is returned, which is only valid for the current page and cannot be used across pages.

Parameters

Attribute	Type	Required	Description	Minimum Supported Version Number	SDK Minimum Supported Version
appId	string	Yes	Total application ID of the small program (obtained from the Hisavana Platform)	2.9.0	2.2.0
codeSeatId	string	Yes	Small program code seat ID (obtained from the Hisavana Platform)	2.9.0	2.2.0
codeSeatType	string	Yes	Small program ad type field (obtained from the Hisavana Platform) 1: native 2: banner 3: interstitial 4: splash screen 5: rewarded video (4 and 5 are currently not supported)	2.9.0	2.2.0

Return Value

InterstitialAd

Ad Creation

The interstitial ad component is hidden by default, so it can be created in advance and the component can be initialized in advance. Developers can create an ad instance in the onLoad event callback of the small program page and repeat calling the ad instance in the lifecycle of the page.

// pages/index/index.js
Page({
  onLoad() {
    if (dlt.createInterstitialAd) {
      const interstitialAd = dlt.createInterstitialAd({
        codeSeatId: "xxxx",
        appId: "xxx",
        codeSeatType: "x",
      });
      interstitialAd.onLoad(() => {
        console.log("onLoad event emit");
      });
      interstitialAd.onError((err) => {
        console.log("onError event emit", err);
      });
      interstitialAd.onClose((res) => {
        console.log("onClose event emit", res);
      });
      this.interstitialAd = interstitialAd;
    }
  },
});

Display/Hide

The interstitial ad component is hidden by default, and developers need to call interstitialAd.show to display it. If the ad fails to load or is triggered by rate limiting, the interstitialAd.show() method will return a rejected Promise, and developers can listen to the error message. The error code information table is shown below.

interstitialAd.show().catch((err) => {
  console.error(err);
});

Users can actively close interstitial ads. Developers cannot control the hiding of interstitial ad components.

Ad Fetching Success and Failure

The interstitial ad component automatically fetches and updates ads. After the component is created, an ad will be fetched. After the user closes the ad, the next ad will be fetched. If the ad is fetched successfully, the callback function registered through interstitialAd.onLoad will be executed, and the callback function does not have any passed parameters.

interstitialAd.onLoad(() => {
  console.log("Interstitial ad loaded successfully");
});

If the ad fails to fetch, the callback function registered through interstitialAd.onError() will be executed, and the callback function's parameter is an object containing the error information.

interstitialAd.onError((err) => {
  console.log(err);
});

Listen for the User to Close the Ad

If the ad is closed, the callback function registered through interstitialAd.onClose() will be executed, and the callback function does not have any passed parameters.

interstitialAd.onClose((res) => {
  console.log("Interstitial ad closed");
});

Precautions

Multiple event callbacks such as interstitialAd.onLoad(), interstitialAd.onError(), and interstitialAd.onClose() will produce multiple event callbacks. It is recommended to listen once after the ad is created, or cancel the original listen event before reregistering it.

Error Code Information Table

If the interstitial ad fails to display, the InterstitialAd.show() method will return a rejected Promise, and the developer can get the error code and corresponding error message.

Code	Exception	Reason
2000	Call exception	The current version does not support interstitial ads.
2001	Trigger frequency limit	Interstitial ads are not allowed to be displayed within a certain time after the small program is started
2002	Trigger frequency limit	The time interval between the last display time of the small program interstitial ad is insufficient, and the interstitial ad cannot be displayed.
2003	Trigger frequency limit	An interstitial ad is being displayed, and another interstitial ad cannot be displayed.
2004	Ad rendering failure	This error is not an exception handling made by the developer, or the ad rendering failed due to a switch of small program pages.
2005	Ad call exception	The interstitial ad instance cannot be called across pages.
2006	Ad call exception	The call failed due to the parameter not meeting the requirements.
2007	Ad call exception	The interstitial ad instance failed to fill.