Rewarded Popup

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 #

On zones with reward postback (enabled by default), the Promise returned by the SDK resolves after Monetag confirms the event for this open. The SDK waits about 2 seconds after the tab opens, then polls for the confirmation for up to about 9 seconds. The result contains reward_event_type (valued or non_valued).

If no confirmation arrives, the Promise rejects with Failed to verify the ad show, even though the tab was opened. .then() does not confirm that the user visited the page. Decide on the reward by reward_event_type in the result or in the postback.

On zones with reward postback turned off, the Promise resolves right after the tab opens.

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 plus a popup show ID, for example user-123_pop_5
UUID
Any custom string unique for each popup show and meaningful to your backend

If ymid is not provided, {ymid} in the postback is empty. The SDK does not use the Telegram user ID as ymid. The SDK sends the Telegram user ID separately (when the Telegram Web App API is initialized), and it arrives as {telegram_id}.

Using `requestVar` for Tracking #

requestVar arrives in the postback as {request_var} with the main zone ID as a prefix: <main zone ID>_<requestVar>.

// main zone ID: 123456
show_123456({ type: 'pop', requestVar: 'daily_popup' })

The postback arrives with request_var=123456_daily_popup. To get your own value, cut the prefix:

const { request_var } = req.query // '123456_daily_popup'
const placement = request_var.slice(request_var.indexOf('_') + 1) // 'daily_popup'

Rewarded Interstitial sends requestVar without a prefix. In-App Interstitial always sends auto. Use only letters, digits, -, _ and . in requestVar: Monetag puts the value into your postback URL without URL-encoding.

Rewarded Popup sends an impression postback with the popup zone ID in sub_zone_id. It can also send a click postback from a zone linked to the popup zone. That postback has a different sub_zone_id.

zone_id is the main zone ID in both cases. Both arrive with the same ymid. Pass a unique ymid for each popup show and grant one reward per ymid when a postback arrives with reward_event_type=valued, whatever the event_type.

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 calls made without a user click and failed confirmation
Design fallback logic if an external page fails to open

Common Mistakes to Avoid #

Trying to trigger the popup without a user interaction: the SDK rejects the Promise with Ad can only be opened directly in response to a user's click
Not using .catch(): you miss rejected calls and failed confirmations
Using a sub-zone ID — must always use the main SDK zone
Assuming .then() means the user visited the page: it means Monetag registered the event. Check reward_event_type
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.

Rewarded Popup – Integration Guide #