Do not treat every blank result as the same bug
“The ad did not show” can mean the script never loaded, the wrong zone was used, the function ran too early, Telegram blocked a popup, the request had no matching inventory, the app was not approved or the ad displayed but the reward postback failed. Randomly moving the script or repeatedly calling show makes those cases harder to distinguish.
Draw the delivery chain and mark the last confirmed event: app opened, SDK request completed, function became available, preload resolved, display started, display completed, frontend callback resolved and postback arrived. The first missing event is the problem boundary.
Open → load SDK → preload → user action → show → completion → postback → rewardRead the rejected Promise before adding a retry
Monetag’s SDK methods return Promises. Attach a catch handler to every call and log the error message with the zone, placement, requestVar, ymid, Telegram platform and app version. The official reference lists examples such as an empty ad feed, a misconfigured zone, a network error, a timeout and a popup that was not triggered from a user action.
A retry is appropriate only after you know what failed. An empty feed can fall back to normal product behavior and become eligible again later. A wrong zone will fail until configuration changes. An early call needs a ready state. An automatic popup needs a direct click. Retrying any of those in a tight loop creates a worse product without fixing the cause.
- Error message
- Main zone ID
- Generated function name
- Placement name
- ymid
- Device and OS
- Telegram client
- Timestamp
- Network status
- Last confirmed stage
Check the script and zone together
Use the network panel to confirm the SDK request returns successfully over HTTPS. A content security policy, ad blocker, DNS filter or failed third-party request can stop the file before your application code runs. Keep the normal product action available so a network dependency does not trap the user.
- Open the generated tag in your Monetag dashboard
Do not compare against a tutorial screenshot or an old project.
- Confirm the main zone ID
The current SDK guidance warns against initializing with a sub-zone ID.
- Match data-sdk to the function you call
A renamed or mistyped global function produces an immediate JavaScript failure.
- Load the tag once
Duplicate tags can create inconsistent state and make framework navigation harder to debug.
- Wait for readiness
Enable the ad button only after the script has loaded and the function exists.
Rewarded Popup requires a real user gesture
Browsers and mobile WebViews restrict unsolicited tabs. Monetag documents that the pop format must be called directly inside a user action such as a button click. Calling it after a timer, on page load or after an unrelated asynchronous chain can lose the gesture and be blocked even though the rest of the Mini App works.
Keep the click handler short: explain the sponsored action before the tap, call the SDK from that handler and catch rejection. Do not disguise the destination or auto-redirect the user. Monetag’s application requirements prohibit deceptive behavior and require external navigation to be intentional.
Separate no-fill from a broken integration
An empty feed means the SDK was reachable but no suitable advertisement was available for that request. Inventory can vary by geography, device, time, format, advertiser demand and traffic quality. It is not proof that the placement will never work, and it is not permission to hammer the endpoint until something appears.
Record no-fill as a normal outcome. Restore the button, keep the base reward or action intact, and optionally offer another approved monetization path. Compare the fill rate by country and placement over a meaningful sample. If every request across devices and times fails, then review zone status, moderation and configuration with Monetag support.
| Signal | Likely category | Next action |
|---|---|---|
| Function is undefined | SDK lifecycle or script failure | Inspect load order, URL and console |
| Zone misconfigured | Credential mapping | Copy the main zone and generated tag again |
| Ad feed is empty | Temporary inventory / targeting | Use fallback and measure fill by cohort |
| Popup not triggered from user action | WebView gesture rule | Move the call into the direct click handler |
| Ad shows but no reward | Callback or postback chain | Trace ymid, valued result and idempotency |
| Works on Android only | Platform-specific WebView path | Reproduce and log on iOS Telegram |
If the ad shows but the reward does not arrive
Treat display and reward delivery as separate systems. Confirm that the chosen format supports the postback you configured, the ad was actually shown rather than only preloaded, the endpoint is public over HTTPS and successful requests return HTTP 200. Log all incoming query values before applying a balance change.
Retries can produce duplicate deliveries when the server does not acknowledge the first event. Deduplicate with ymid and make the handler idempotent. Monetag’s postback guidance also notes that telegram_id may be empty; use your own attempt mapping and do not award an unidentified balance based on a guessed session.
- Supported rewarded format
- Postback enabled for the zone
- Public HTTPS endpoint
- 200 response after processing
- Unique ymid
- Valued event check
- Duplicate protection
- Server-side log retained
Verify moderation and application requirements
A technically correct tag still depends on an eligible application. Monetag requires a functional HTTPS Telegram Mini App, JavaScript and DOM access, mobile optimization, safe navigation and compliance with its publisher policies. Aggressive refreshes, forced redirects, deceptive controls or prohibited content can lead to restricted delivery or rejection.
Test the core application without advertising first. It should load quickly, navigate cleanly and remain usable in Telegram WebView. Then add logical placement points. If the app is under review or delivery is restricted, code changes will not substitute for resolving the account or policy status in the Monetag dashboard.
Send support a reproducible packet
If the failure remains after local diagnosis, send evidence that lets support reproduce it: publisher account, main zone, Mini App URL, bot entry point, format, UTC timestamp, country, Telegram client, device, sanitized console error and the exact sequence of taps. Include whether a test zone behaves differently.
Do not send bot tokens, private signing secrets or user personal data in a public ticket. A precise packet turns “ads do not work” into a traceable delivery question and avoids repeated requests for basic context.
- Reproduce once with logging enabled
- Capture the first error, not ten downstream errors
- State whether it fails for all users or one cohort
- Share the main zone ID but never private credentials
- Keep the user-facing fallback active while investigating
Common questions
Why is the Monetag show function undefined?
The SDK tag may not have loaded, may be blocked, may use a different generated function name or may be called before initialization. Confirm the exact dashboard tag and wait for readiness.
What does “Ad feed is empty” mean?
It generally indicates that no suitable inventory was available for that request. Handle it as no-fill, preserve the normal user path and measure the pattern before escalating.
Why does Rewarded Popup fail inside Telegram?
The pop call must happen during a direct user gesture. Timers, automatic loads and delayed asynchronous calls can be blocked by browser or WebView popup rules.
Why do I receive duplicate reward postbacks?
A provider may retry when your endpoint does not acknowledge delivery. Return 200 after successful handling and make the reward operation idempotent using ymid.
Sources and further reading
Technical and product claims were checked against these primary sources.