SDK Reference

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
  • If your zone requires those values, the Promise may reject

Use this only for testing or static setups.

Parameters (object or string): #

The Promise returned by show_123456() resolves with an object containing:

{
  reward_event_type: 'valued' | 'not_valued';
  estimated_price?: number; // Optional approximate revenue
  sub_zone_id?: number;
  zone_id?: number;
  request_var?: string;
  ymid?: string;
  telegram_id?: string;
  // Other optional fields depending on configuration
}

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 (ymid, telegram_id)
  • Handle revenue logic (estimated_price)
{
  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
  }
}

  • type (string, required): Defines what action the SDK will take. Must be one of:

    • 'end': Show rewarded interstitial and resolve promise after ad completion.
    • 'start': Resolve promise when the ad starts showing.
    • 'preload': Preload the ad for later use.
    • 'pop': Open Rewarded Popup in a new tab or Telegram browser.
    • 'inApp': Setup or trigger In-App Interstitial.

  • ymid (string, optional): Unique identifier of the event. Used to match front-end ad calls to backend postbacks.

  • requestVar (string, optional): Identifies the placement or context of the ad (e.g., “level_end_button”). Appears in analytics and helps disambiguate monetization sources.

  • timeout (number, optional): Time in seconds before the Promise will auto-reject if the ad has not completed or failed. Useful to avoid hanging logic on slow connections.

  • catchIfNoFeed (boolean, optional): If set to true, the SDK will resolve the Promise even when no ad feed is available. This is useful when you want to integrate fallback logic — for example, to show an ad from another ad network if Monetag does not return feed.

  • inAppSettings (object, required for type: 'inApp' when initializing automatic display):

    • frequency: Max number of ads shown.
    • capping: Time window (in hours) to apply frequency cap.
    • interval: Seconds between ads.
    • timeout: Delay before first ad is shown.
    • everyPage: If true, restarts timer on every navigation.

Event Types (type) #

"end" #

  • Triggers a Rewarded Interstitial
  • The Promise resolves after successful view and backend confirmation

"start" #

  • Also triggers an Interstitial
  • The Promise resolves at the moment the ad starts showing

"preload" #

  • Loads ad materials in background, without showing
  • Use to prepare ad for future call to "end"

"pop" #

  • Triggers a Rewarded Popup (external tab or Telegram browser)
  • Must be called directly inside user interaction (e.g., onclick handler)
  • Resolves after opening and confirming postback

"inApp" #

  • Can be used either to enable auto-display mode (with inAppSettings) or manually trigger an In-App Interstitial ad
  • Promise resolves immediately upon acceptance of settings or when ad is triggered manually

Usage Examples #

Full flow with preload and end #

// preload ad in advance on app loading
show_123456({
  type: 'preload',
  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();
  }
});

Ad with timeout handling #

show_123456({
  type: 'end',
  ymid: 'uid-99',
  requestVar: 'exit',
  timeout: 10
}).then(res => {
  rewardUser();
}).catch(() => {
  showError();
});

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 & Timeout 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({ type: 'end' })
  .catch((error) => {
    console.log('Ad failed:', error.message);
  });

Possible .message values include:

  • Ad feed is empty
  • Zone misconfigured
  • Network error
  • Timeout exceeded
  • pop not triggered from user action

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