Cordova / Capacitor Integration

Learn how to wrap your HTML5 game with BZZE Ads in a native mobile app using Cordova or Capacitor.

What's the difference?
Cordova: The original hybrid app framework (mature, large plugin ecosystem)
Capacitor: Modern alternative by Ionic team (better developer experience, recommended for new projects)

Option 1: Capacitor (Recommended)

Capacitor is the modern successor to Cordova, offering better performance and developer experience.

Step 1: Install Capacitor

Bash

# Navigate to your game directory
cd your-game-folder

# Initialize npm project (if not already done)
npm init -y

# Install Capacitor
npm install @capacitor/core @capacitor/cli

Step 2: Initialize Capacitor

Bash

# Initialize Capacitor
npx cap init

# You'll be prompted for:
# - App name: "My Awesome Game"
# - App ID: "com.yourcompany.gamename" (reverse domain format)
# - Web directory: "www" or "dist" (where your built game is)

Step 3: Add Platforms

Bash

# Add Android
npm install @capacitor/android
npx cap add android

# Add iOS (requires macOS with Xcode)
npm install @capacitor/ios
npx cap add ios

Step 4: Configure BZZE Ads in Your Game

Your existing BZZE Ads integration works as-is! Just ensure your HTML includes the SDK:

HTML

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
    <title>My Game</title>
    
    <!-- BZZE Ads SDK -->
    <script src="https://ads.bzze.com/sdk/rewarded.min.js"></script>
</head>
<body>
    <!-- Your game canvas/content -->
    
    <script>
    // Initialize BZZE Ads when Capacitor is ready
    document.addEventListener('DOMContentLoaded', function() {
        RewardedAd.init({
            appId: "YOUR_APP_ID",
            apiKey: "YOUR_API_KEY",
            userId: "user_" + Date.now(),
            onReward: function(reward) {
                console.log('User earned reward!');
                // Grant your game currency here
            },
            onNoFill: function() {
                console.log('No ads available');
            },
            onError: function(error) {
                console.error('Ad error:', error);
            }
        });
    });
    
    function showRewardedAd() {
        RewardedAd.showAd();
    }
    </script>
</body>
</html>

Step 5: Configure Permissions

Android (android/app/src/main/AndroidManifest.xml)

XML

<manifest>
    <!-- Add internet permission -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    
    <application
        android:usesCleartextTraffic="true">
        <!-- Your activity config -->
    </application>
</manifest>

iOS (ios/App/App/Info.plist)

XML

<dict>
    <!-- Allow HTTP/HTTPS connections -->
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
    </dict>
    
    <!-- Optional: Track ads for analytics (if needed) -->
    <key>NSUserTrackingUsageDescription</key>
    <string>We use ads to support free games</string>
</dict>

Step 6: Build and Run

Bash

# Sync your web code to native projects
npx cap sync

# Open in Android Studio
npx cap open android

# Open in Xcode (macOS only)
npx cap open ios

# Then build and run from Android Studio / Xcode

That's it! Your BZZE Ads integration will work exactly as it does on the web. No native code modifications needed!

Option 2: Cordova (Classic)

If you prefer Cordova or have an existing Cordova project:

Step 1: Install Cordova

Bash

# Install Cordova CLI globally
npm install -g cordova

# Create new Cordova project
cordova create myGame com.yourcompany.gamename MyGame
cd myGame

Step 2: Add Platforms

Bash

# Add Android
cordova platform add android

# Add iOS (requires macOS)
cordova platform add ios

Step 3: Add Your Game Files

Copy your game files to the www/ directory and ensure BZZE Ads SDK is included:

Bash

# Your game structure
myGame/
├── www/
│   ├── index.html          # Your game HTML
│   ├── js/
│   │   └── game.js         # Your game logic
│   ├── css/
│   │   └── style.css
│   └── assets/             # Game assets

Step 4: Configure Permissions

Edit config.xml in your project root:

XML

<widget id="com.yourcompany.gamename" version="1.0.0">
    <name>My Game</name>
    <description>An awesome game with BZZE Ads</description>
    
    <!-- Allow external content (for ads) -->
    <access origin="*" />
    <allow-navigation href="https://ads.bzze.com/*" />
    
    <!-- Android permissions -->
    <platform name="android">
        <config-file target="AndroidManifest.xml" parent="/manifest">
            <uses-permission android:name="android.permission.INTERNET" />
        </config-file>
    </platform>
    
    <!-- iOS configuration -->
    <platform name="ios">
        <preference name="WKWebViewOnly" value="true" />
    </platform>
</widget>

Step 5: Build and Run

Bash

# Build for Android
cordova build android

# Run on connected Android device
cordova run android

# Build for iOS (macOS only)
cordova build ios

# Open Xcode project
open platforms/ios/MyGame.xcworkspace

Testing Your App

Test on Emulator

Bash

# Capacitor - Android
npx cap run android

# Cordova - Android
cordova emulate android

# iOS (requires macOS and Xcode)
cordova emulate ios

Test on Real Device

Bash

# Connect device via USB
# Enable USB Debugging (Android) or Developer Mode (iOS)

# Capacitor
npx cap run android --target YOUR_DEVICE_ID

# Cordova
cordova run android --device

Enable Remote Debugging

Android:

Connect device via USB
Open chrome://inspect in Chrome
Click "inspect" next to your app
Use console to check BZZE Ads logs

iOS:

Connect device via USB
Open Safari > Develop > [Your Device] > [Your App]
Use Web Inspector to debug

Common Issues & Solutions

"No ads available" Always Shows

Cause: No internet connection or blocked by CORS

Solution:

XML

<!-- Add to config.xml (Cordova) -->
<access origin="*" />
<allow-navigation href="https://ads.bzze.com/*" />

<!-- Or add to capacitor.config.json (Capacitor) -->
{
  "server": {
    "allowNavigation": ["https://ads.bzze.com"]
  }
}

Ads Show but Don't Track in Dashboard

Cause: localStorage not persisting

Solution:

JavaScript

// Test localStorage in your app
console.log('localStorage works:', typeof localStorage !== 'undefined');

// Ensure you're using WKWebView on iOS (not UIWebView)

Black Screen on App Launch

Cause: Files not found or wrong directory

Solution:

Bash

# Capacitor: Check capacitor.config.json
{
  "webDir": "www"  // ← Must match your build output
}

# Cordova: Ensure files are in www/ directory

iOS App Rejected by App Store

Cause: Missing ad disclosure or inappropriate ads

Solution:

Add "Contains Ads" in App Store listing
Set appropriate age rating for your ads
Implement COPPA compliance if targeting kids (see COPPA guide)

Best Practices

Use Capacitor for New Projects

Better performance, modern tooling, and active development make Capacitor the better choice.

Test on Real Devices

Emulators are great for development, but always test on real devices before releasing.

Handle Permissions Properly

Request only the permissions you need and explain why in permission dialogs.

Enable Debug Mode

Use debug: true in RewardedAd.init() during development to see detailed logs.

Preload Ads Early

Call RewardedAd.init() as soon as your app loads to ensure ads are ready quickly.

Monitor Analytics

Check your Publisher Dashboard regularly to track fill rate, completion rate, and revenue.

Example: Complete Capacitor Setup

Here's a complete working example of a Capacitor app with BZZE Ads:

Bash

# 1. Create your game (e.g., with Phaser, Construct, or plain HTML)
# 2. Install Capacitor
npm init -y
npm install @capacitor/core @capacitor/cli @capacitor/android @capacitor/ios

# 3. Initialize
npx cap init "My Game" "com.example.mygame" --web-dir=www

# 4. Add your game files to www/
# 5. Ensure www/index.html includes BZZE Ads SDK

# 6. Add platforms
npx cap add android
npx cap add ios

# 7. Configure AndroidManifest.xml and Info.plist (see above)

# 8. Build and test
npx cap sync
npx cap open android  # Opens Android Studio

Next Steps

Mobile Best Practices

Optimize your game for mobile devices

Testing Checklist

Ensure your integration works perfectly

FAQ

Find answers to common questions

Need Help?

Stuck with your Cordova/Capacitor integration? We're here to help!

View FAQ Contact Support