In-App Interstitial

In-App Interstitial – Integration Guide #

In-App Interstitial is a passive ad format that automatically displays full-screen ads at set intervals while the user interacts with your Mini App. It’s designed for background monetization without requiring direct user interaction or rewards.

Example

This format is best suited for apps with long session durations or frequent navigation between screens or sections.

⚠️ Important: For proper positioning of UI elements (e.g. the close button and timer), it’s recommended to use the official Telegram WebApp SDK (Telegram.WebApp).
If the SDK is not available, Monetag cannot detect safe visual areas, and interface elements might overlap with Telegram or system UI (as seen on some devices).
To ensure visual stability, you should connect the Telegram SDK manually.

Key Characteristics #

  • Ads appear automatically, based on your configured frequency
  • Does not require explicit user actions
  • Returns a Promise that resolves as soon as the schedule is set. It does not wait for any ad. It rejects if inAppSettings is missing frequency, capping, interval or timeout
  • Sends an impression postback for each ad shown, to the postback URL of the main zone. It never sends click. {request_var} is always auto: a requestVar passed in the setup call does not reach the postback
  • Works silently in the background while the app is in use

You can trigger this format either via SDK configuration in JavaScript or through parameters in the SDK script tag.

Manual Setup via SDK #

The SDK provides a method to enable auto-display logic programmatically:

show_XXX({
  type: 'inApp',
  inAppSettings: {
    frequency: 2,
    capping: 0.1,
    interval: 30,
    timeout: 5,
    everyPage: false
  }
})

Explanation of parameters:

  • frequency: maximum number of ads per session
  • capping: duration of session in hours (e.g. 0.1 = 6 minutes)
  • interval: time in seconds between ads
  • timeout: seconds after each page load before an ad can appear
  • everyPage: if true, the session resets on each page load and on each URL change

You can also use this approach in React via the npm SDK:

import createAdHandler from 'monetag-tg-sdk'

const adHandler = createAdHandler(MAIN_ZONE_ID)

adHandler({
  type: 'inApp',
  inAppSettings: {
    frequency: 3,
    capping: 0.5,
    interval: 30,
    timeout: 10,
    everyPage: false
  }
})

Configuration via Script Tag #

You can enable in-app interstitials using the data-auto attribute directly in the script tag:

<script
  src="https://domain.com/sdk.js"
  data-zone="XXX"
  data-sdk="show_XXX"
  data-auto="2/0.1/30/5/0">
</script>

This example displays up to 2 ads over 6 minutes (0.1 hours), with 30 seconds between them and a 5-second delay before the first ad. The final 0 means the session continues across pages.

Custom Timers with Fallback Logic #

If you prefer full control, you can build your own timer-based logic using the SDK and handle fallback scenarios manually:

setInterval(() => {
  show_XXX({ type: 'preload' }).then(() => {
    show_XXX()
  }).catch(() => {
    showOtherAd()
  })
}, 1000 * 60 * 5) // every 5 minutes

This allows you to display alternate ads or messages if Monetag inventory is unavailable.

Best Practices #

  • Use moderate frequency settings to avoid annoying users
  • Place logic in a persistent part of the app (not tied to one screen)
  • Avoid triggering too soon after the app opens — use a delay
  • Track user engagement to avoid showing ads during critical interactions
  • Test in both light and dark modes of Telegram WebView

Common Mistakes to Avoid #

  • Calling show_XXX({ type: 'inApp' }) more than once: repeated calls are ignored, so new inAppSettings do not replace the ones already running. If the script tag has data-auto, its values are used instead of inAppSettings
  • Forgetting to preload if using manual timers
  • Using aggressive frequency (e.g. more than 1 ad per minute)
  • Misplacing the SDK script or using the wrong zone ID (must be the main zone)

In-App Interstitial is an excellent way to monetize passive engagement while maintaining a clean user experience. When configured correctly, it can run silently and effectively in the background of your app.