Troubleshooting Guide

Solutions to common issues and errors when integrating BZZE Ads SDK.

Quick Tip: Enable debug mode to see detailed logs: RewardedAd.enableDebug()

Common Issues & Solutions

1. SDK Not Loading

Problem: SDK script fails to load

Symptoms:

RewardedAd is not defined error in console
Script 404 error
Nothing happens when calling SDK methods

Solutions:

✅ Solution 1: Check Script URL

HTML

<!-- ❌ Wrong -->
<script src="https://ads.bzze.com/rewarded.min.js"></script>

<!-- ✅ Correct -->
<script src="https://ads.bzze.com/sdk/rewarded.min.js"></script>

✅ Solution 2: Wait for Script to Load

JavaScript

// ❌ Wrong - SDK might not be loaded yet
RewardedAd.init({ ... });

// ✅ Correct - Wait for script load
window.addEventListener('load', function() {
    RewardedAd.init({ ... });
});

// Or use script onload
const script = document.createElement('script');
script.src = 'https://ads.bzze.com/sdk/rewarded.min.js';
script.onload = function() {
    RewardedAd.init({ ... });
};
document.head.appendChild(script);

✅ Solution 3: Check Network/CORS

Open browser DevTools → Network tab
Check if rewarded.min.js loads successfully (status 200)
If blocked, check CORS or firewall settings

2. Initialization Failed

Problem: `RewardedAd.init()` fails or returns error

Symptoms:

Invalid credentials error
401 Unauthorized in network tab
Init callback never fires

Solutions:

✅ Solution 1: Verify Credentials

JavaScript

// Check your Publisher Dashboard for correct credentials
RewardedAd.init({
    appId: "YOUR_APP_ID",      // Must match exactly
    apiKey: "YOUR_API_KEY",    // Must match exactly
    userId: "user_123"         // Any unique user ID
});

// Enable debug mode to see detailed errors
RewardedAd.enableDebug();
RewardedAd.init({ ... });

✅ Solution 2: Check App Status

Go to Publisher Dashboard
Verify your app is Active (not paused or suspended)
Ensure domain is whitelisted (if domain restrictions are enabled)

✅ Solution 3: Check API Key Expiration

API keys may expire or be regenerated
Get the latest API key from your dashboard
Update your code with the new key

3. No Ads Available (NO_FILL)

Problem: `isAdAvailable()` returns false or `onNoFill` fires

Symptoms:

"No ads available" message shows
onNoFill callback fires
480 error code in network requests

Solutions:

✅ Solution 1: Check Inventory

No fill is normal when there's genuinely no ad inventory
Fill rate typically 80-95% (some requests won't fill)
Try again in a few minutes

✅ Solution 2: Enable Auto-Preload

JavaScript

// Enable auto-preload for better fill rates
RewardedAd.init({
    appId: "YOUR_APP_ID",
    apiKey: "YOUR_API_KEY",
    userId: "user_123",
    autoPreload: true,      // ✅ Enable this
    preloadCount: 2         // ✅ Keep 2 ads ready
});

✅ Solution 3: Check Rate Limits

JavaScript

// Check if rate limited
const info = RewardedAd.getInfo();
console.log('Rate limits:', info.rateLimits);
// Output: { hourly: 10, daily: 50, maxPerHour: 10, maxPerDay: 50 }

// If limits reached, wait before requesting more ads

✅ Solution 4: Handle Gracefully

JavaScript

RewardedAd.init({
    // ...config
    onNoFill: function() {
        // Offer alternative ways to earn reward
        showAlternativeOptions([
            'Complete a quest',
            'Invite friends',
            'Watch later'
        ]);
    }
});

4. Ads Not Displaying

Problem: `showAd()` called but nothing happens

Symptoms:

showAd() returns false
Player doesn't appear on screen
No callbacks fire

Solutions:

✅ Solution 1: Check Availability First

JavaScript

// ❌ Wrong - showAd without checking
function showRewardedAd() {
    RewardedAd.showAd();
}

// ✅ Correct - check first
function showRewardedAd() {
    if (RewardedAd.isAdAvailable()) {
        RewardedAd.showAd();
    } else {
        console.log('No ad available');
        // Show message or retry
    }
}

✅ Solution 2: Check Cooldown

JavaScript

// Check if cooldown is active
const cooldown = RewardedAd.getCooldownRemaining();
if (cooldown > 0) {
    console.log(`Wait ${cooldown} seconds before next ad`);
    showCooldownMessage(cooldown);
} else if (RewardedAd.isAdAvailable()) {
    RewardedAd.showAd();
}

✅ Solution 3: Check Z-Index Conflicts

CSS

/* Ad player uses z-index: 999999 */
/* Make sure no game elements have higher z-index */

.game-ui {
    z-index: 100; /* ✅ Lower than ad player */
}

.modal {
    z-index: 500; /* ✅ Still lower than ad player */
}

5. Reward Not Granted

Problem: Ad completes but `onReward` doesn't fire

Symptoms:

User watches full ad
onReward callback never fires
Reward not given to user

Solutions:

✅ Solution 1: Check Callback Implementation

JavaScript

// ❌ Wrong - callback not defined
RewardedAd.init({
    appId: "YOUR_APP_ID",
    apiKey: "YOUR_API_KEY"
    // Missing onReward!
});

// ✅ Correct - callback defined
RewardedAd.init({
    appId: "YOUR_APP_ID",
    apiKey: "YOUR_API_KEY",
    userId: "user_123",
    onReward: function(reward) {
        console.log('Reward earned!', reward);
        grantReward(reward);  // Your function to give reward
    }
});

✅ Solution 2: Check for JavaScript Errors

JavaScript

// Add error handling to callback
RewardedAd.init({
    // ...config
    onReward: function(reward) {
        try {
            console.log('Reward callback fired', reward);
            grantReward(reward);
        } catch (error) {
            console.error('Error in reward callback:', error);
        }
    }
});

✅ Solution 3: Verify Ad Completion

Reward only fires when ad is completed (not skipped or closed early):

Watch the full ad duration
Don't close before completion
Skip button only appears after minimum duration

6. VAST Ads Not Playing

Problem: VAST/SSP ads fail to load or play

Symptoms:

VAST parsing errors in console
401-901 error codes
Video player shows black screen

Solutions:

✅ Solution 1: Test VAST Tag

JavaScript

// Test with known working VAST tag
// Google IMA sample tag (always works):
const testTag = 'https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=';

// If test tag works, issue is with your VAST tag

✅ Solution 2: Check VAST Error Codes

Error Code	Meaning	Solution
100-102	XML parsing error	Check VAST XML is valid
300-303	Wrapper error	VAST wrappers not supported yet
400-405	Video error	Video file format/codec issue
900-901	Timeout	VAST response too slow (>10s)

✅ Solution 3: Enable Debug Mode

JavaScript

// Enable debug mode to see VAST parsing details
RewardedAd.enableDebug();

// Watch console for VAST-related logs:
// - VAST request URL
// - VAST XML response
// - Parsed video URL
// - Error codes and messages

7. High Error Rate

Problem: Many ads fail to load or play (error rate >10%)

Solutions:

✅ Solution 1: Check Network Stability

Slow connections cause timeouts
Video files may be too large
VAST tags may be slow to respond

✅ Solution 2: Implement Error Handling

JavaScript

RewardedAd.init({
    // ...config
    onError: function(error) {
        console.error('Ad error:', error);
        
        // Log errors for debugging
        logAdError({
            code: error.code,
            message: error.message,
            timestamp: Date.now()
        });
        
        // Show user-friendly message
        if (error.code === 480) {
            showMessage('No ads available right now');
        } else {
            showMessage('Failed to load ad. Try again?');
        }
    }
});

✅ Solution 3: Monitor Analytics

JavaScript

// Check error analytics
const analytics = RewardedAd.getAnalytics();
console.log('Error breakdown:', analytics.errors);
// Output: { 480: 5, 401: 2, 900: 1 }

const errorRate = (analytics.errors.total / analytics.impressions) * 100;
console.log(`Error rate: ${errorRate}%`);
// Target: < 5% error rate

8. Analytics Not Tracking

Problem: Analytics shows 0 or incorrect data

Solutions:

✅ Solution 1: Wait for Data Processing

Analytics data processes every 5-15 minutes
Dashboard may not update instantly
Check again after 15 minutes

✅ Solution 2: Check SDK Analytics

JavaScript

// SDK tracks client-side analytics
const analytics = RewardedAd.getAnalytics();
console.log('Client-side stats:', analytics);

// Output:
// {
//   impressions: 5,
//   completions: 4,
//   clicks: 2,
//   errors: { 480: 1 },
//   viewableImpressions: 4
// }

✅ Solution 3: Verify Session ID

Make sure each user has a unique session to track properly:

JavaScript

// Use unique user ID for tracking
RewardedAd.init({
    appId: "YOUR_APP_ID",
    apiKey: "YOUR_API_KEY",
    userId: "user_" + Date.now(),  // ✅ Unique per session
    // ...rest of config
});

Debug Mode

Enabling Debug Mode

JavaScript

// Enable before init for full debug output
RewardedAd.enableDebug();

RewardedAd.init({
    appId: "YOUR_APP_ID",
    apiKey: "YOUR_API_KEY",
    userId: "user_123"
});

// Debug logs will show:
// ✓ Initialization details
// ✓ API request/response
// ✓ Ad availability checks
// ✓ VAST parsing details
// ✓ Player events
// ✓ Callback executions
// ✓ Error details

What Debug Mode Shows

Console Output Example

[BZZE Ads] Initializing SDK...
[BZZE Ads] Config: { appId: "app_123", autoPreload: true, ... }
[BZZE Ads] Auth successful
[BZZE Ads] Auto-preloading 2 ads...
[BZZE Ads] Ad request sent
[BZZE Ads] Ad response received: House Ad (Coca-Cola)
[BZZE Ads] Ad preloaded successfully
[BZZE Ads] showAd() called
[BZZE Ads] Playing ad: house_ad_001
[BZZE Ads] Player created
[BZZE Ads] Video started
[BZZE Ads] Progress: 25%
[BZZE Ads] Progress: 50%
[BZZE Ads] Progress: 75%
[BZZE Ads] Video completed
[BZZE Ads] onReward callback fired
[BZZE Ads] Player closed

Browser Compatibility Issues

Issue: SDK doesn't work in older browsers

Minimum Requirements:

Browser	Minimum Version	Notes
Chrome	60+	Recommended
Firefox	55+	Recommended
Safari	11+	iOS 11+ for mobile
Edge	79+ (Chromium)	Legacy Edge not supported
IE 11	Not Supported	Use polyfills or upgrade

Feature Detection:

JavaScript

// Check if browser is supported
function isBrowserSupported() {
    return !!(
        window.Promise &&
        window.fetch &&
        window.localStorage &&
        window.IntersectionObserver
    );
}

if (!isBrowserSupported()) {
    console.warn('Browser not fully supported');
    // Show upgrade message
}

Network & Firewall Issues

Issue: SDK can't connect to ad server

Required Domains (Whitelist These):

ads.bzze.com - Main API and SDK
*.doubleclick.net - VAST ads (optional)
*.googlevideo.com - Video content (optional)

Required Ports:

Port 80 (HTTP)
Port 443 (HTTPS)

Test Connectivity:

JavaScript

// Test API connectivity
fetch('https://ads.bzze.com/v1/health')
    .then(res => res.json())
    .then(data => console.log('API Status:', data))
    .catch(err => console.error('Cannot connect to API:', err));

Getting More Help

Before Contacting Support:

✅ Enable debug mode and check console logs
✅ Review this troubleshooting guide
✅ Check the FAQ
✅ Test with the Live Demo
✅ Check your Publisher Dashboard for errors

Contact Support:

📧 Email: support@bzze.com
📝 Include:

App ID and API Key (first 8 characters)
Error messages (full console logs)
Browser and OS version
Steps to reproduce the issue
Debug mode console output

⏱️ Response Time: Within 24-48 hours

Troubleshooting Guide

Common Issues & Solutions

1. SDK Not Loading

Problem: SDK script fails to load

Solutions:

✅ Solution 1: Check Script URL

✅ Solution 2: Wait for Script to Load

✅ Solution 3: Check Network/CORS

2. Initialization Failed

Problem: RewardedAd.init() fails or returns error

Solutions:

✅ Solution 1: Verify Credentials

✅ Solution 2: Check App Status

✅ Solution 3: Check API Key Expiration

3. No Ads Available (NO_FILL)

Problem: isAdAvailable() returns false or onNoFill fires

Solutions:

✅ Solution 1: Check Inventory

✅ Solution 2: Enable Auto-Preload

✅ Solution 3: Check Rate Limits

✅ Solution 4: Handle Gracefully

4. Ads Not Displaying

Problem: showAd() called but nothing happens

Solutions:

✅ Solution 1: Check Availability First

✅ Solution 2: Check Cooldown

✅ Solution 3: Check Z-Index Conflicts

5. Reward Not Granted

Problem: Ad completes but onReward doesn't fire

Solutions:

✅ Solution 1: Check Callback Implementation

✅ Solution 2: Check for JavaScript Errors

✅ Solution 3: Verify Ad Completion

6. VAST Ads Not Playing

Problem: VAST/SSP ads fail to load or play

Solutions:

✅ Solution 1: Test VAST Tag

✅ Solution 2: Check VAST Error Codes

✅ Solution 3: Enable Debug Mode

7. High Error Rate

Problem: Many ads fail to load or play (error rate >10%)

Solutions:

✅ Solution 1: Check Network Stability

✅ Solution 2: Implement Error Handling

✅ Solution 3: Monitor Analytics

8. Analytics Not Tracking

Problem: Analytics shows 0 or incorrect data

Solutions:

✅ Solution 1: Wait for Data Processing

✅ Solution 2: Check SDK Analytics

✅ Solution 3: Verify Session ID

Debug Mode

Enabling Debug Mode

What Debug Mode Shows

Browser Compatibility Issues

Issue: SDK doesn't work in older browsers

Minimum Requirements:

Feature Detection:

Network & Firewall Issues

Issue: SDK can't connect to ad server

Required Domains (Whitelist These):

Required Ports:

Test Connectivity:

Getting More Help

Before Contacting Support:

Contact Support:

Related Documentation

Problem: `RewardedAd.init()` fails or returns error

Problem: `isAdAvailable()` returns false or `onNoFill` fires

Problem: `showAd()` called but nothing happens

Problem: Ad completes but `onReward` doesn't fire