Developer FAQ

Developer FAQ #

This section addresses the most common questions developers ask when integrating Monetag ads into their Telegram Mini Apps. All answers are based on real-world usage, support cases, and internal best practices.

What zone ID should I use in the SDK? #

Always use the main zone ID provided by Monetag.
Each SDK setup includes one main zone and several linked sub-zones — only the main zone should be used in:

The <script> tag (data-zone="XXX")
The npm SDK call (createAdHandler(XXX))

Using a sub-zone ID will cause the SDK to work incorrectly or not at all.

What is `ymid` and do I need it? #

ymid is an optional identifier that you can pass when calling show_XXX() to help you match postbacks with user actions on your backend.

You can use:

User ID
Session ID
UUID
Any string that helps link the action to your system

If ymid is not provided, the SDK will try to detect the Telegram user ID, but this only works if the Telegram WebApp API is connected and initialized.

What’s the difference between `requestVar` and `ymid`? #

ymid is used for backend tracking (appears in the postback)
requestVar is used for analytics and reporting (visible in Monetag statistics)

Use requestVar if you want to distinguish different placements (e.g. different buttons).

Can I preload ads before showing them? #

Yes. Preloading is highly recommended for Rewarded Interstitials and In-App Interstitials.

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

This reduces latency and improves UX.

Can I use multiple ad formats at once? #

Yes, the SDK supports Rewarded Interstitial, Rewarded Popup, and In-App Interstitial — and you can use them together in one app.
However, we recommend avoiding too many ads in short time spans.

Why isn’t the ad appearing? #

Check the following:

Are you using the correct (main) zone ID?
Is the SDK script actually loaded before calling the function?
Are you calling the ad method from a user interaction (especially for popups)?
Is .catch() implemented for error handling?
Is there ad inventory available at that moment?

Do I need to wait for the SDK to be ready before calling it? #

Yes. Make sure the SDK script is loaded. In React or modern frameworks, call it from useEffect or after DOM is ready.

Can I use the SDK with Next.js / React? #

Yes. Use the npm package monetag-tg-sdk and call createAdHandler(zoneId) once, then use the returned function where needed.

Example:

import createAdHandler from 'monetag-tg-sdk'

const adHandler = createAdHandler(YOUR_ZONE_ID)

const onClick = () => {
  adHandler({ ymid: 'user-123' }).then(() => {
    // success logic
  }).catch(() => {
    // fallback
  })
}

What if the ad fails to load or show? #

Always use .catch() to detect failure and show fallback logic (another ad, retry, or notification).