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.

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
• Does not return a Promise or trigger postbacks
• 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: delay before the first ad appears (in seconds)
• everyPage: if true, resets the session on each page reload

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' }) multiple times in a row — this may reset the internal logic and interrupt the ad flow
• 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.