Macro Reference #

This section provides a complete list of all macros supported in Monetag’s rewarded postback system.

Macros are special placeholders you can use in your postback URL. At runtime, Monetag automatically replaces them with actual values from the confirmed ad event.

Supported Macros #

Detailed Descriptions #

{ymid} #

A unique string or numeric identifier for the ad event.
You set it in the SDK when showing an ad:

show_XXX({ ymid: 'user123_ad_5' })

Use this to link frontend actions with postback responses. Always use a unique ymid per event.

{zone_id} #

Your main Monetag zone ID — the same one passed to the SDK when initializing:

Use this to distinguish between monetized apps or SDK.

{sub_zone_id} #

Identifies the actual zone that served the ad. May be the same as zone_id or a sub-placement within a parent zone.

Useful for internal diagnostics, fraud detection, or more detailed attribution.

{request_var} #

Custom placement identifier sent via SDK:

show_XXX({ requestVar: 'shop_button' })

Use this to track which UI element or context triggered the ad. Common values: level_3_reward, main_banner, video_end_button, etc.

{telegram_id} #

Telegram user ID automatically extracted from the Telegram WebApp SDK.

• You do not need to set it manually.
• Our SDK will include it if available.
• Telegram may not provide this value for all users or sessions, so it can be empty.

{event_type} #

Possible values:

• impression — the ad was rendered and visible to the user
• click — the user clicked the ad (only for Rewarded Interstitial)

{reward_event_type} #

Tells you whether the event was paid or filtered:

• valued — the event is monetized, the publisher is paid
• not_valued — no payout (e.g. fallback traffic, invalid session, fraud)

Use this to control reward distribution or filter postback events in your backend.

{estimated_price} #

A decimal value representing approximate revenue in USD.

• Comes from real bidding data (CPM, CPC)
• Can be 0 for unmonetized events and in some specific cases, so, use reward_event_type as source of true of event value
• Use for analytics, reward scaling, or performance monitoring

Example: 0.003700 → ~0.0037 cents earned from this ad interaction

Example Postback URL #

https://yourdomain.com/postback? ymid={ymid} &event={event_type} &value={reward_event_type} &zone={zone_id} &sub={sub_zone_id} &price={estimated_price} &source={request_var} &telegram_id={telegram_id}

Monetag will automatically replace each macro with a real value when sending the postback.

Recommendations #

• ✅ Use structured values in request_var (e.g. home_top_button)
• ✅ Validate all macro values on your server
• ✅ Use ymid and reward_event_type for reward control and deduplication
• ❌ Don’t assume telegram_id is always present — check for null/empty