SDK Reference #

This section contains a complete technical overview of Monetag’s JavaScript SDK for Telegram Mini Apps. It is designed for developers and integration engineers who need full control and understanding of ad behavior, callbacks, and monetization logic.

Overview #

The SDK serves as a high-level wrapper over Monetag’s ad tag. It creates a global function (e.g., show_123456) that you can call from your code to:

• Show Rewarded Interstitials, Rewarded Popups, or In-App Interstitials
• Preload ad content for later use
• Track ad completion and revenue events

The SDK exposes a Promise-based interface and manages ad lifecycle internally, including:

• Feed loading
• Preloading
• Postback resolution
• Retry logic

SDK Initialization #

To use the SDK, you must embed the following script tag:

<script
  src="https://yourdomain.com/sdk.js"
  data-zone="123456"
  data-sdk="show_123456">
</script>

• data-zone: Main Monetag zone ID
• data-sdk: Global function name available on window

After the script loads, the SDK creates a global function (show_123456) that accepts configuration and returns a Promise.

Method: show_123456(options) #

The core SDK method. Returns a Promise that resolves when the ad event completes successfully or rejects otherwise.

This method accepts either:

• an object with named parameters (recommended)
• or a string (used as shorthand for type)

String-based usage #

If you call show_123456('end'), it’s equivalent to:

show_123456({ type: 'end' })

Allowed values:

• 'end' (default fallback)
• 'start'
• 'pop'
• 'preload'
• 'inApp'

If you pass an invalid string, it will default to 'end'.

No-argument behavior #

If you call show_123456() without parameters:

• It will fallback to: show_123456({ type: 'end' })
• No ymid or requestVar will be passed

Use this only for testing or static setups.

Result promise: #

For type: 'end' (the default) and type: 'pop' on zones with reward postback (enabled by default), the Promise resolves with an object after Monetag confirms the event:

{
  reward_event_type: 'valued' | 'non_valued';
  event_type?: string; // 'impression' or 'click'
  estimated_price?: number; // absent when the value is 0
  sub_zone_id?: number;
  zone_id?: number;
  request_var?: string;
  variable2?: string; // your ymid
  telegram_id?: string;
}

In all other cases the Promise resolves with undefined: preload, start, inApp, and zones without reward postback. Check the result before you read it, for example result?.reward_event_type.

You can use these fields to:

• Confirm whether the ad was monetized (reward_event_type)
• Attribute earnings to UI elements (request_var)
• Track user context (variable2, which holds your ymid, and telegram_id)
• Handle revenue logic (estimated_price)

Parameters (object or string) #

The show_XXX(options) function accepts a configuration object that controls the behavior of each ad call. Below are all available options and their effects:

string | {
  type?: 'end' | 'start' | 'preload' | 'pop' | 'inApp',
  ymid?: string,
  requestVar?: string,
  timeout?: number,
  catchIfNoFeed?: boolean,
  inAppSettings?: {
    frequency: number,
    capping: number,
    interval: number,
    timeout: number,
    everyPage?: boolean
  }
}

Parameters #

type (string, optional, default value = ’end') #

Defines what kind of ad action to perform. Supported values:

• "end": Show a Rewarded Interstitial. The Promise resolves after the ad is shown and closed.
• "start": Also shows a Rewarded Interstitial, but the Promise resolves when the ad starts (before completion).
• "preload": Starts loading ad materials in background without showing. Call "end" later to show it.
• "pop": Opens a Rewarded Popup (in new browser tab or Telegram WebApp). Must be called inside a user action.
• "inApp": Triggers or configures an In-App Interstitial (can auto-show ads on interval or show immediately).

ymid (string, optional) #

Custom event or user identifier.
Used to match the frontend call with backend postbacks (ymid will appear in postback URL). If you pass none, {ymid} is empty. Use only letters, digits, -, _ and .: Monetag puts the value into your postback URL without URL-encoding.

Examples:

• ymid: 'user_abc_123'
• ymid: 'session-456'

requestVar (string, optional) #

Custom label for the placement or ad trigger source.
Used in reporting and passed in the reward postback as {request_var}. For Rewarded Popup the postback value is <main zone ID>_<requestVar>. Use only letters, digits, -, _ and .: Monetag puts the value into your postback URL without URL-encoding.

Examples:

• requestVar: 'level_end'
• requestVar: 'bonus_button'

timeout (number, optional) #

Sets a maximum wait time in seconds. When the time runs out, the Promise rejects with Timeout.

• 'preload' and 'start': limits the wait for the ad to load.
• 'end' (the default): the SDK preloads the ad with this timeout, then shows it. The timeout limits only the preload step. The time the ad is on screen is not limited.
• 'pop' and 'inApp': no effect.

Example usage:

show_XXX({ type: 'preload', timeout: 5 })
  .then(() => {
    // Ad successfully preloaded
  })
  .catch(() => {
    // Preload took too long — use fallback logic
  });

This is useful when you want to preload ads in the background, but avoid freezing your app if the ad cannot be loaded due to network issues, blocked domains, or slow response.

Example of usage you may check here

catchIfNoFeed (boolean, optional) #

This option has no effect. The SDK accepts it but does not read it.

When no ad is available, the Promise always rejects with Empty feed, with or without this option. Handle it in .catch():

show_XXX()
  .catch(() => {
    // no Monetag ad, use another network
  })

inAppSettings (object, required for "inApp" initialization) #

Used only with type: 'inApp' to enable automatic display of In-App Interstitials.

Example:

show_XXX({
  type: 'inApp',
  inAppSettings: {
    frequency: 3,
    capping: 2, // hours
    interval: 120,
    timeout: 10,
    everyPage: true
  }
});

Summary of Event Types #

Usage Examples #

Full flow with preload and end #

// preload ad in advance on app loading
show_123456({
  type: 'preload',
  ymid: 'uid-45',
  requestVar: 'bonus_button'
});

// show ad later on some trigger
show_123456({
  type: 'end',
  ymid: 'uid-45',
  requestVar: 'bonus_button'
}).then((result) => {
  if (result?.reward_event_type === 'valued') {
    giveReward();
  }
});

Preload and show reuse the ad only when requestVar and ymid are identical in both calls.

Ad with timeout handling #

let preloaded = false;

show_XXX({ type: 'preload', timeout: 5, ymid: 'user123' })
  .then(() => {
    preloaded = true;
  });

button.onclick = () => {
  if (preloaded) {
    show_XXX({ ymid: 'user123' });
  } else {
    alert('No ads available, try again later.');
  }
};

Popup on user click #

button.addEventListener('click', () => {
  show_123456({
    type: 'pop',
    ymid: 'popup-001',
    requestVar: 'shop_cta'
  });
});

Enable In-App Interstitial autoplay mode #

show_123456({
  type: 'inApp',
  inAppSettings: {
    frequency: 2,
    capping: 0.1,
    interval: 30,
    timeout: 5,
    everyPage: false
  }
});

Error Handling #

The Promise returned by show_123456() may reject with an Error object. You can access the reason using .message in the catch() block.

Example:

show_123456()
  .catch((error) => {
    console.log('Ad failed:', error.message);
  });

Possible .message values include:

• Empty feed
• Rejected
• Network error
• Empty zone id
• Timeout
• Ad is not ready
• Ad can only be opened directly in response to a user's click
• Failed to open pop
• Failed to verify the ad show
• Missing In-App settings, or Missing In-App <name> setting for a missing frequency, capping, interval or timeout
• Failed to render Telegram banner
• Unsupported event

These messages can be used for debugging, logging, or triggering fallback behavior in your app.

Best Practices #

• Always provide a unique ymid per call
• Set requestVar to identify UI context (e.g., “shop_button”)
• Wrap SDK calls in .then() / await and .catch()
• Never call pop outside of a direct user click
• Use preload for smooth UI and instant ad start