Rewarded Interstitial – Integration Guide #

Rewarded Interstitial is a full-screen ad format that grants a reward to the user after they watch the ad. The Monetag SDK provides a simple method to display and control this format, with support for preloading, user tracking, and fallback handling.

This guide explains how to implement the format in your Telegram Mini App using both standard JavaScript and React (via the official npm package).

⚠️ 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.

Basic Usage (Script Tag) #

If you’re using the SDK via HTML, trigger the ad with:

show_XXX().then(() => {
  console.log('Ad closed');
}).catch(() => {
  console.log('Ad failed to load or show');
});

Replace XXX with your main zone ID — the one provided in your Monetag dashboard for the SDK setup.
The main zone controls the entire SDK behavior and links to all related sub-zones.

Basic Usage (React + npm package) #

import createAdHandler from 'monetag-tg-sdk'

const adHandler = createAdHandler(REWARDED_INTERSTITIAL_ZONE_ID)

const ShowAdButton = () => {
  const onClick = () => {
    adHandler().then(() => {
      console.log('Ad closed')
    }).catch(() => {
      console.log('Ad failed to load or show')
    })
  }

  return <button onClick={onClick}>Show Ad</button>
}

Tracking Events with ymid #

You can pass a unique identifier using the ymid parameter:

show_XXX({ ymid: 'user-id-or-event-id' })

This identifier will be included in the postback and can be used on your backend to match the ad impression to a specific user or event.

You can use:

• A user ID from your system
• A session ID
• A UUID
• Any unique string that helps you identify the action

If you do not pass ymid, {ymid} in the postback is empty. The SDK does not use the Telegram user ID as ymid. The user ID arrives separately as {telegram_id}.

Call Telegram.WebApp.ready() so the SDK can send the Telegram user ID as {telegram_id}.

Preloading the Ad #

To reduce delay at the moment of ad display, you can preload it:

show_XXX({ type: 'preload', ymid: 'event-id-123' }).then(() => {
  show_XXX({ ymid: 'event-id-123' })
})

React example:

const [adReady, setAdReady] = useState(false)

useEffect(() => {
  show_XXX({ type: 'preload', ymid: 'event-id-123' }).then(() => setAdReady(true))
}, [])

const onClick = () => {
  show_XXX({ ymid: 'event-id-123' })
}

Fallback Logic #

If the ad is unavailable or fails to show, you can fall back to another ad source:

show_XXX({ type: 'preload', ymid: 'event-id' }).then(() => {
  show_XXX({ ymid: 'event-id' }).catch(() => {
    showOtherAd()
  })
}).catch(() => {
  showOtherAd()
})

Common Mistakes to Avoid #

• Calling show_XXX() without .catch() – no way to handle failures or show fallback
• Not passing ymid - the postback is still sent, but {ymid} in it is empty. If the Telegram WebApp API is initialized, the user ID arrives separately as {telegram_id}
• Using sub-zone ID instead of the main zone ID – the SDK may not work properly
• Not preloading – ads may appear with a noticeable delay
• Triggering ads before the SDK has loaded
• Including multiple SDK tags on the same page

Best Practices #

• Preload ads before enabling “Watch Ad” buttons
• Provide user feedback (e.g. loading states) during preloading
• Grant the reward only when .then() resolves and result?.reward_event_type is 'valued': the Promise also resolves when the user closes the ad early
• Use ymid to link postbacks to internal user or event logic
• Use requestVar if you want to track different placements or buttons. It arrives in the postback as {request_var}, exactly as you passed it
• Always test your integration inside Telegram, not just in a browser

Once Rewarded Interstitial is working, you can confidently implement reward logic and start monetizing your app effectively.