Rewarded Popup

Rewarded Popup – Integration Guide #

Rewarded Popup is an ad format that opens an advertiser’s page when the user interacts with a specific element in your app (such as a button). This format is best suited for scenarios where users are incentivized to visit an offer page.

Example

Unlike interstitials, Rewarded Popup does not display a full-screen ad inside your app — instead, it redirects the user externally, while allowing you to control when and how that happens.

Key Characteristics #

  • Can only be triggered by a direct user action (e.g. button click)
  • Opens the advertiser’s page in a browser environment
  • Works well for incentivized navigation (e.g. “Visit and earn”)
  • Can be tracked with ymid and requestVar parameters

Important:
The ad may open in one of the following environments:

  • Telegram’s built-in browser (default behavior)
  • A separate tab inside the Telegram browser
  • The device’s external system browser

This behavior depends on the Telegram client version and the user’s browser preferences. Telegram allows users to configure how external links are opened — they can choose to always use the internal browser, set a specific browser app, or delegate to the default system browser.

How Reward Handling Works #

Currently, the Promise returned by the SDK resolves immediately after the app attempts to open the advertiser’s link. At this point, we cannot determine whether the user actually visited the page or interacted with it.

We are actively working on an improved solution that will resolve the Promise only after our backend infrastructure confirms the user’s visit to the landing page.

Until then, you should treat .then() as confirmation that the popup was triggered — not necessarily that it was viewed.

Basic Usage (Script Tag) #

button.addEventListener('click', () => {
  show_XXX({ type: 'pop' }).then(() => {
    console.log('Popup attempt completed')
  }).catch(() => {
    console.log('Popup ad failed to open')
  })
})

Replace XXX with your main zone ID.

Basic Usage (React + npm package) #

import createAdHandler from 'monetag-tg-sdk'

const adHandler = createAdHandler(REWARDED_INTERSTITIAL_ZONE_ID)

const ShowAdButton = () => {
  const onClick = () => {
    adHandler({ type: 'pop' }).then(() => {
      console.log('Popup attempt completed')
    }).catch(() => {
      console.log('Popup ad failed to open')
    })
  }

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

Using ymid for Tracking #

You can pass an identifier to match the postback with a specific user or event:

show_XXX({ type: 'pop', ymid: 'event-123' })

React version:

adHandler({ type: 'pop', ymid: 'event-123' }).then(() => {
  // reward logic
})

Possible values for ymid include:

  • User ID
  • Session ID
  • Placement ID
  • Any custom string meaningful to your backend

If ymid is not provided, the SDK will attempt to retrieve the Telegram user ID automatically (if the Telegram Web App API is initialized in your app).

Best Practices #

  • Always trigger show_XXX({ type: 'pop' }) directly from a user-initiated event (e.g. click)
  • Clearly inform the user what reward they get for tapping the button
  • Use requestVar to track performance of different buttons or placements
  • Use .catch() to handle popup blockers or user interruptions
  • Design fallback logic if an external page fails to open

Common Mistakes to Avoid #

  • Trying to trigger the popup without a user interaction — browsers will block it
  • Not using .catch() — results in missed handling if the tab fails to open
  • Using a sub-zone ID — must always use the main SDK zone
  • Assuming the Promise means the user visited the page — it only confirms an attempt
  • Forgetting to pass ymid — backend postbacks will be harder to trace

Rewarded Popup is quick to integrate, and when used in the right flow, can become a valuable source of monetization while offering users optional engagement.