Home / API Reference / RewardedAd.showAd()

RewardedAd.showAd()

Display a rewarded video ad to the user. This is the main method you'll call when users want to watch an ad for a reward.

Syntax

JavaScript
RewardedAd.showAd(options)

Parameters

options (Optional)

An object containing display options:

Property Type Default Description
rewardPreview string '' Reward description shown to user (e.g., "100 coins")
placement string 'default' Ad placement ID for analytics

Return Value

Promise<void> - Returns a promise that resolves when the ad flow completes (reward granted, user closed, error, or no fill).

Examples

Basic Usage

JavaScript
// Simple - no options
RewardedAd.showAd();

// With reward preview
RewardedAd.showAd({
    rewardPreview: "100 coins"
});

With Placement Tracking

JavaScript
// Track which button/location showed the ad
RewardedAd.showAd({
    rewardPreview: "1 extra life",
    placement: "game_over_screen"
});

// Different placements for analytics
function showShopAd() {
    RewardedAd.showAd({
        rewardPreview: "50% discount",
        placement: "shop_discount_button"
    });
}

function showDailyBonusAd() {
    RewardedAd.showAd({
        rewardPreview: "double reward",
        placement: "daily_bonus_screen"
    });
}

With Error Handling

JavaScript
async function watchAdForCoins() {
    try {
        await RewardedAd.showAd({
            rewardPreview: "100 coins"
        });
        // Ad flow complete (check onReward callback for actual reward)
    } catch (error) {
        console.error('Failed to show ad:', error);
        showErrorMessage('Could not load ad');
    }
}

Check Availability First

JavaScript - Recommended Pattern
function watchAdButton() {
    // Check if ad is ready
    if (!RewardedAd.isAdAvailable()) {
        alert('No ads available right now. Try again in a moment!');
        return;
    }
    
    // Show the ad
    RewardedAd.showAd({
        rewardPreview: "100 coins"
    });
}

Behavior

When you call showAd(), the following happens:

  1. Availability Check: SDK checks if a preloaded ad is available
  2. Rate Limit Check: Verifies user hasn't exceeded frequency caps
  3. Video Player Opens: Fullscreen overlay with video ad
  4. User Watches: Must watch at least 80% to earn reward
  5. Completion: One of these callbacks fires:
    • onReward - User completed ad (GRANT REWARD HERE)
    • onClose - User closed early (no reward)
    • onNoFill - No ads available
    • onError - Something went wrong

Important Notes

⚠️ Critical: Only grant rewards in the onReward callback, not after showAd() returns. Users can close ads early!
  • Must initialize first: Call RewardedAd.init() before showAd()
  • Async operation: Returns immediately, callbacks fire later
  • User can close: Don't assume completion
  • Frequency caps apply: SDK enforces limits automatically
  • No fill possible: Always handle onNoFill

Common Mistakes

❌ WRONG: Granting reward immediately

JavaScript - DON'T DO THIS
function watchAd() {
    RewardedAd.showAd({
        rewardPreview: "100 coins"
    });
    
    // ❌ WRONG! User might close ad early
    grantCoins(100);
}

✅ CORRECT: Grant in callback

JavaScript - DO THIS
// In init()
RewardedAd.init({
    // ...
    onReward: function(reward) {
        // ✅ CORRECT! Only grant when user completes ad
        grantCoins(100);
    }
});

// Show ad
function watchAd() {
    RewardedAd.showAd({
        rewardPreview: "100 coins"
    });
}

Error Codes

The SDK may return these errors via onError:

Code Meaning Action
RATE_LIMIT_EXCEEDED User hit frequency cap Show cooldown message
NO_FILL No ads available Try again later
NOT_INITIALIZED Forgot to call init() Call init() first
NETWORK_ERROR Connection issue Check internet connection

Best Practices

  • ✅ Always set rewardPreview to show users what they'll earn
  • ✅ Use placement to track which buttons perform best
  • ✅ Check isAdAvailable() before calling
  • ✅ Handle all callbacks (especially onClose and onNoFill)
  • ✅ Only grant rewards in onReward
  • ❌ Don't call showAd() in a loop
  • ❌ Don't spam - respect frequency caps
  • ❌ Don't grant rewards outside onReward

See Also