Skip to main content

Banner Ads

Banner ads are fixed-position advertisements that remain visible during gameplay. They're perfect for continuous monetization without interrupting the player experience.

Overview​

Use Cases:

  • Footer banners
  • Sidebar ads
  • Header ads
  • In-game UI integration

Characteristics:

  • Non-intrusive
  • Always visible
  • Auto-refresh support
  • Multiple size options

Basic Usage​

1. Create a Container​

Add a div element where you want the banner to appear:

<div id="banner-ad" style="width: 728px; height: 90px;"></div>

2. Initialize SDK​

const sdk = new GetJarAdsSDK();
await sdk.init({
  appId: 'your-game-id',
  publisher: 'your-publisher-id',
  environment: 'production'
});

3. Create Banner​

sdk.createBanner({
  containerId: 'banner-ad',
  placement: 'footer',
  size: '728x90'
});

Configuration Options​

BannerConfig Interface​

interface BannerConfig {
  /** ID of container div (required) */
  containerId: string;

  /** Placement identifier for reporting (required) */
  placement: string;

  /** Ad size (required) */
  size: BannerSize;

  /** Ad unit path (optional - uses default if not provided) */
  adUnitPath?: string;

  /** Custom targeting (optional) */
  targeting?: Record<string, string | string[]>;

  /** Callbacks */
  onLoad?: () => void;
  onError?: (error: Error) => void;
  onImpression?: () => void;
}
SizeWidthHeightUse Case
'728x90'728px90pxDesktop leaderboard
'970x90'970px90pxLarge leaderboard
'300x250'300px250pxMedium rectangle
'320x50'320px50pxMobile banner
'468x60'468px60pxBanner
'160x600'160px600pxWide skyscraper

Complete Example​

<!DOCTYPE html>
<html>
<head>
  <title>My Game with Banner Ads</title>
  <style>
    body {
      margin: 0;
      font-family: Arial, sans-serif;
    }

    #game-container {
      width: 800px;
      height: 600px;
      margin: 20px auto;
      background: #f0f0f0;
      position: relative;
    }

    #banner-footer {
      width: 728px;
      height: 90px;
      margin: 20px auto;
      background: #e0e0e0;
      display: flex;
      align-items: center;
      justify-content: center;
    }

    #banner-sidebar {
      width: 160px;
      height: 600px;
      position: absolute;
      right: -180px;
      top: 0;
      background: #e0e0e0;
    }
  </style>
</head>
<body>
  <!-- Game canvas -->
  <div id="game-container">
    <canvas id="game-canvas" width="800" height="600"></canvas>

    <!-- Sidebar banner (desktop only) -->
    <div id="banner-sidebar"></div>
  </div>

  <!-- Footer banner -->
  <div id="banner-footer"></div>

  <!-- Load SDK -->
  <script src="https://cdn.getjar.com/sdk/getjar-ads.js"></script>

  <script>
    async function initAds() {
      const sdk = new GetJarAdsSDK();

      // Initialize SDK
      await sdk.init({
        appId: 'my-awesome-game',
        publisher: 'famobi',
        environment: 'production',
        privacy: { gdpr: true, coppa: false }
      });

      // Footer banner (always visible)
      sdk.createBanner({
        containerId: 'banner-footer',
        placement: 'footer',
        size: '728x90',
        onLoad: () => console.log('Footer banner loaded'),
        onError: (error) => console.warn('Footer banner error:', error)
      });

      // Sidebar banner (desktop only)
      if (window.innerWidth > 1200) {
        sdk.createBanner({
          containerId: 'banner-sidebar',
          placement: 'sidebar_right',
          size: '160x600',
          onLoad: () => console.log('Sidebar banner loaded')
        });
      }
    }

    // Initialize ads when page loads
    window.addEventListener('DOMContentLoaded', initAds);
  </script>
</body>
</html>

Responsive Design​

Mobile-First Approach​

function createResponsiveBanner() {
  const isMobile = window.innerWidth < 768;

  sdk.createBanner({
    containerId: 'banner-ad',
    placement: isMobile ? 'mobile_footer' : 'desktop_footer',
    size: isMobile ? '320x50' : '728x90'
  });
}

// Handle window resize
window.addEventListener('resize', () => {
  // Destroy and recreate banner on orientation change
  sdk.destroyBanner('banner-ad');
  createResponsiveBanner();
});

CSS Media Queries​

<style>
  /* Desktop banner */
  #desktop-banner {
    display: block;
    width: 728px;
    height: 90px;
    margin: 0 auto;
  }

  /* Mobile banner */
  #mobile-banner {
    display: none;
  }

  @media (max-width: 768px) {
    #desktop-banner {
      display: none;
    }

    #mobile-banner {
      display: block;
      width: 320px;
      height: 50px;
      margin: 0 auto;
    }
  }
</style>

<div id="desktop-banner"></div>
<div id="mobile-banner"></div>

<script>
  const isMobile = window.innerWidth < 768;

  sdk.createBanner({
    containerId: isMobile ? 'mobile-banner' : 'desktop-banner',
    placement: 'footer',
    size: isMobile ? '320x50' : '728x90'
  });
</script>

Advanced Features​

Custom Targeting​

Add custom targeting parameters for better ad relevance:

sdk.createBanner({
  containerId: 'banner-ad',
  placement: 'footer',
  size: '728x90',
  targeting: {
    'game_category': 'puzzle',
    'player_level': '5',
    'premium_user': 'false'
  }
});

Multiple Banners​

Display multiple banners simultaneously:

// Footer banner
sdk.createBanner({
  containerId: 'footer-banner',
  placement: 'footer',
  size: '728x90'
});

// Sidebar banner
sdk.createBanner({
  containerId: 'sidebar-banner',
  placement: 'sidebar',
  size: '160x600'
});

// In-game banner
sdk.createBanner({
  containerId: 'ingame-banner',
  placement: 'ingame_top',
  size: '300x250'
});

Lazy Loading​

Load banners only when visible:

const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting && !entry.target.dataset.adLoaded) {
      sdk.createBanner({
        containerId: entry.target.id,
        placement: 'lazy_footer',
        size: '728x90'
      });
      entry.target.dataset.adLoaded = 'true';
    }
  });
});

observer.observe(document.getElementById('banner-ad'));

Best Practices​

1. Container Sizing​

Always size your container to match the ad size:

/* Good - exact size */
#banner-ad {
  width: 728px;
  height: 90px;
}

/* Bad - wrong size */
#banner-ad {
  width: 100%;  /* Too wide */
  height: auto; /* Height not specified */
}

2. Placement Names​

Use descriptive placement names for analytics:

// Good - descriptive
placement: 'footer_728x90'
placement: 'sidebar_right_160x600'
placement: 'level_select_300x250'

// Bad - generic
placement: 'ad1'
placement: 'banner'
placement: 'test'

3. Error Handling​

Always handle errors gracefully:

sdk.createBanner({
  containerId: 'banner-ad',
  placement: 'footer',
  size: '728x90',
  onError: (error) => {
    console.warn('Banner ad failed to load:', error);
    // Hide container if ad fails
    document.getElementById('banner-ad').style.display = 'none';
  }
});

4. Performance​

Minimize banner count to reduce performance impact:

// Good - 1-2 banners per page
sdk.createBanner({ containerId: 'footer', ... });
sdk.createBanner({ containerId: 'sidebar', ... });

// Bad - too many banners
sdk.createBanner({ containerId: 'banner1', ... });
sdk.createBanner({ containerId: 'banner2', ... });
sdk.createBanner({ containerId: 'banner3', ... });
sdk.createBanner({ containerId: 'banner4', ... });
sdk.createBanner({ containerId: 'banner5', ... });

Troubleshooting​

Problem: Container div exists but ad doesn't appear

Solutions:

  1. Check container has correct size:

    const container = document.getElementById('banner-ad');
    console.log(container.offsetWidth, container.offsetHeight);

  2. Verify SDK is initialized:

    if (sdk.isReady()) {
      sdk.createBanner(...);
    }

  3. Check browser console for errors

  4. Verify ad blocker is disabled

Wrong Size​

Problem: Ad appears but wrong dimensions

Solutions:

  1. Ensure container div matches ad size:

    <!-- For 728x90 banner -->
    <div id="banner-ad" style="width: 728px; height: 90px;"></div>

  2. Check CSS isn't overriding dimensions:

    #banner-ad {
      width: 728px !important;
      height: 90px !important;
    }

Ad Overlap​

Problem: Banner overlaps game content

Solutions:

  1. Use fixed positioning:

    #banner-footer {
      position: fixed;
      bottom: 0;
      left: 50%;
      transform: translateX(-50%);
      z-index: 1000;
    }

  2. Add padding to game container:

    #game-container {
      padding-bottom: 100px; /* Banner height + margin */
    }

Testing​

Development Mode​

Test banners in development:

await sdk.init({
  appId: 'test-game',
  publisher: 'test',
  environment: 'development' // Uses test ads
});

sdk.createBanner({
  containerId: 'banner-ad',
  placement: 'test_footer',
  size: '728x90'
});

Staging Environment​

Test with real ad network:

await sdk.init({
  appId: 'your-game-id',
  publisher: 'your-publisher-id',
  environment: 'staging' // Uses staging ad units
});

Production​

await sdk.init({
  appId: 'your-game-id',
  publisher: 'your-publisher-id',
  environment: 'production' // Uses production ad units
});

Analytics​

Track banner performance:

sdk.createBanner({
  containerId: 'banner-ad',
  placement: 'footer',
  size: '728x90',
  onLoad: () => {
    console.log('[Analytics] Banner loaded');
    // Track with your analytics
    analytics.track('banner_loaded', {
      placement: 'footer',
      size: '728x90'
    });
  },
  onImpression: () => {
    console.log('[Analytics] Banner impression');
    analytics.track('banner_impression', {
      placement: 'footer',
      size: '728x90'
    });
  }
});

Support​

Having issues with banner ads? Contact support: support@getjar.com