Callbacks & Events

Complete reference for all SDK callbacks and event handling.

ℹ️ Event-Driven SDK: BZZE Ads SDK uses callbacks to notify your app about ad lifecycle events. All callbacks are optional but recommended for a complete integration.

Quick Reference

Callback	When It Fires	Use Case
`onReward`	Ad completed successfully	Grant reward to user
`onAdLoaded`	Ad preloaded successfully	Update UI, enable buttons
`onAdShown`	Ad starts playing	Pause game, track impressions
`onAdClicked`	User clicks CTA button	Track engagement
`onNoFill`	No ads available	Show fallback message
`onClose`	Ad player closed	Resume game, refresh UI
`onError`	Error occurred	Log errors, show fallback

Callback Definitions

onReward

Called when the user successfully completes watching an ad and earns a reward.

Signature

JavaScript

onReward: function(reward) {
    // reward object:
    {
        sessionId: string,       // Unique session ID
        timestamp: number,       // Unix timestamp
        message: string          // e.g., "Reward earned!"
    }
}

Example

JavaScript

RewardedAd.init({
    appId: "YOUR_APP_ID",
    apiKey: "YOUR_API_KEY",
    userId: "user_123",
    onReward: function(reward) {
        console.log('✅ Reward earned!', reward);
        
        // Grant reward to user (YOUR logic)
        grantCoins(100);
        showRewardAnimation();
        
        // Optional: Send to your backend
        fetch('/api/rewards', {
            method: 'POST',
            body: JSON.stringify({
                userId: 'user_123',
                sessionId: reward.sessionId,
                amount: 100
            })
        });
    }
});

onAdLoaded

Called when an ad has been successfully preloaded and is ready to display.

Signature

JavaScript

onAdLoaded: function(data) {
    // data object:
    {
        sessionId: string,       // Session ID of preloaded ad
        timestamp: number        // When ad was loaded
    }
}

Example

JavaScript

onAdLoaded: function(data) {
    console.log('✅ Ad preloaded!', data.sessionId);
    
    const count = RewardedAd.getPreloadedAdCount();
    console.log(`Total preloaded: ${count}`);
    
    // Update UI
    document.getElementById('adButton').disabled = false;
    document.getElementById('adBadge').textContent = count;
}

onAdShown

Called when an ad starts playing (after the user clicks to watch).

Signature

JavaScript

onAdShown: function(data) {
    // data object:
    {
        sessionId: string,       // Current ad session ID
        timestamp: number        // When ad started
    }
}

Example

JavaScript

onAdShown: function(data) {
    console.log('▶️ Ad started playing', data.sessionId);
    
    // Pause game
    pauseGame();
    
    // Mute game audio
    muteGameAudio();
    
    // Track impression in your analytics
    trackEvent('ad_impression', {
        sessionId: data.sessionId,
        timestamp: data.timestamp
    });
}

onAdClicked

Called when the user clicks on the ad's CTA button.

Signature

JavaScript

onAdClicked: function(data) {
    // data object:
    {
        sessionId: string,       // Current ad session ID
        clickUrl: string,        // URL that was opened
        timestamp: number        // When click occurred
    }
}

Example

JavaScript

onAdClicked: function(data) {
    console.log('🖱️ Ad clicked!', data.clickUrl);
    
    // Track click engagement
    trackEvent('ad_click', {
        sessionId: data.sessionId,
        url: data.clickUrl
    });
    
    // Optional: Show "Continue watching" message
    showNotification('Opening advertiser page...');
}

onNoFill

Called when no ads are available to show.

Signature

JavaScript

onNoFill: function(data) {
    // data object:
    {
        reason: string,          // e.g., "NO_FILL", "RATE_LIMIT"
        timestamp: number
    }
}

Example

JavaScript

onNoFill: function(data) {
    console.log('⚠️ No ads available:', data.reason);
    
    // Show user-friendly message
    if (data.reason === 'RATE_LIMIT') {
        showMessage('You\'ve watched the maximum ads for now. Try again later!');
    } else {
        showMessage('No ads available right now. Please try again in a moment!');
    }
    
    // Optional: Offer alternative reward method
    showAlternativeRewardOptions();
}

onClose

Called when the ad player closes (whether completed or skipped).

Signature

JavaScript

onClose: function(data) {
    // data object:
    {
        sessionId: string,       // Session ID that closed
        completed: boolean,      // true if watched fully, false if skipped
        timestamp: number
    }
}

Example

JavaScript

onClose: function(data) {
    console.log('❌ Ad closed', data);
    
    // Resume game
    resumeGame();
    
    // Unmute game audio
    unmuteGameAudio();
    
    // Refresh UI
    updateAdButton();
    
    // Track in analytics
    trackEvent('ad_close', {
        sessionId: data.sessionId,
        completed: data.completed
    });
}

onError

Called when an error occurs during ad loading or playback.

Signature

JavaScript

onError: function(error) {
    // error object:
    {
        code: string,            // Error code (e.g., "NETWORK_ERROR")
        message: string,         // Human-readable error message
        details: object,         // Additional error details
        timestamp: number
    }
}

Example

JavaScript

onError: function(error) {
    console.error('❌ Ad error:', error.message);
    
    // Log to your error tracking service
    logError('BZZE_AD_ERROR', {
        code: error.code,
        message: error.message,
        details: error.details
    });
    
    // Show user-friendly message
    if (error.code === 'NETWORK_ERROR') {
        showMessage('Connection error. Please check your internet.');
    } else {
        showMessage('Something went wrong. Please try again later.');
    }
    
    // Resume game if error happened during playback
    resumeGame();
}

Complete Integration Example

JavaScript

RewardedAd.init({
    appId: "YOUR_APP_ID",
    apiKey: "YOUR_API_KEY",
    userId: "user_123",
    autoPreload: true,
    preloadCount: 2,
    
    // ✅ Reward granted
    onReward: function(reward) {
        console.log('💰 Reward earned!');
        grantCoins(100);
        showRewardAnimation();
    },
    
    // 📥 Ad preloaded
    onAdLoaded: function(data) {
        console.log('✅ Ad ready!');
        enableAdButton();
    },
    
    // ▶️ Ad started
    onAdShown: function(data) {
        console.log('🎬 Ad playing');
        pauseGame();
        muteGameAudio();
    },
    
    // 🖱️ Ad clicked
    onAdClicked: function(data) {
        console.log('🖱️ User clicked ad');
        trackClick(data.sessionId);
    },
    
    // ⚠️ No ads available
    onNoFill: function(data) {
        console.log('⚠️ No ads:', data.reason);
        showMessage('No ads available right now');
    },
    
    // ❌ Ad closed
    onClose: function(data) {
        console.log('❌ Ad closed');
        resumeGame();
        unmuteGameAudio();
        updateUI();
    },
    
    // 🚨 Error occurred
    onError: function(error) {
        console.error('🚨 Error:', error.message);
        logError(error);
        showErrorMessage();
        resumeGame();
    }
});

Event Flow Diagram

Flow

// Successful Ad Flow:
1. init()
   ↓
2. onAdLoaded (preload complete)
   ↓
3. showAd() (user clicks button)
   ↓
4. onAdShown (ad starts playing)
   ↓
5. onAdClicked (if user clicks CTA) [optional]
   ↓
6. onReward (ad completed)
   ↓
7. onClose (player closes)

// No Fill Flow:
1. showAd()
   ↓
2. onNoFill (no ads available)

// Error Flow:
1. showAd() or preload
   ↓
2. onError (something failed)
   ↓
3. onClose (player closes)

Best Practices

✅ DO:

Implement all callbacks for complete integration
Always pause game in onAdShown
Always resume game in onClose
Grant rewards only in onReward callback
Handle onNoFill gracefully with fallback options
Log errors from onError to your monitoring service
Track events for analytics

⚠️ DON'T:

Grant rewards outside of onReward callback
Assume ads will always show (handle onNoFill)
Forget to resume game in onClose or onError
Show technical error messages to users
Block your app if callbacks don't fire

Common Patterns

Pattern 1: Game State Management

JavaScript

let gameState = {
    isPaused: false,
    wasPlayingMusic: false
};

function pauseGame() {
    gameState.isPaused = true;
    gameState.wasPlayingMusic = isMusicPlaying();
    stopGameLoop();
    if (gameState.wasPlayingMusic) pauseMusic();
}

function resumeGame() {
    gameState.isPaused = false;
    startGameLoop();
    if (gameState.wasPlayingMusic) resumeMusic();
}

RewardedAd.init({
    // ...config
    onAdShown: pauseGame,
    onClose: resumeGame,
    onError: resumeGame
});

Pattern 2: Reward Verification

JavaScript

onReward: async function(reward) {
    try {
        // Verify with your backend (recommended for high-value rewards)
        const response = await fetch('/api/verify-reward', {
            method: 'POST',
            body: JSON.stringify({
                userId: 'user_123',
                sessionId: reward.sessionId,
                timestamp: reward.timestamp
            })
        });
        
        const result = await response.json();
        
        if (result.verified) {
            grantCoins(100);
            showRewardAnimation();
        } else {
            console.error('Reward verification failed');
        }
    } catch (error) {
        console.error('Verification error:', error);
    }
}

Pattern 3: Analytics Tracking

JavaScript

const analytics = {
    onAdShown: (data) => trackEvent('ad_started', data),
    onAdClicked: (data) => trackEvent('ad_clicked', data),
    onReward: (data) => trackEvent('ad_completed', data),
    onNoFill: (data) => trackEvent('ad_no_fill', data),
    onError: (error) => trackEvent('ad_error', { code: error.code })
};

RewardedAd.init({
    // ...config
    ...analytics
});

Related Methods

init() - Initialize with callbacks
showAd() - Trigger ad display
getAnalytics() - Get session analytics

Callbacks & Events

Quick Reference

Callback Definitions

onReward

Signature

Example

onAdLoaded

Signature

Example

onAdShown

Signature

Example

onAdClicked

Signature

Example

onNoFill

Signature

Example

onClose

Signature

Example

onError

Signature

Example

Complete Integration Example

Event Flow Diagram

Best Practices

Common Patterns

Pattern 1: Game State Management

Pattern 2: Reward Verification

Pattern 3: Analytics Tracking

Related Methods

See Also