Advertising System Overview

AdStage Web SDK supports three types of ads in web applications.

🎯 Supported Ad Types

Image‑based ads; the most common format.

AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250
});

Features: Image based, auto sizing, slide support

Text Ads

Native text ads that blend naturally into surrounding content.

AdStage.ads.text('text-container');

Features: Auto height, line limit, native style

Video Ads

Video ads that drive higher engagement.

AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: true,
  muted: true
});

Features: HTML5 video, autoplay/mute, mobile optimized

🔄 Basic Flow

Initialize SDK – call AdStage.init()
Prepare container – create DOM element where the ad will render
Request ad – call ads.banner(), ads.text(), or ads.video()
Auto render – SDK loads and injects ad asynchronously
Event tracking – impressions/clicks automatically collected

📚 Next Steps

Check each ad type’s detailed guide:

Common Features: Shared options & behaviors
Banner Ads: Advanced banner configuration
Text Ads: Customizing native text ads
Video Ads: Playback control & optimization

🎯 Supported Ad Types (Detailed)

Image‑based banner ads, the most typical web format.

// Basic banner ad
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250
});
 
// With click handler & advanced options
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250,
  onClick: (adData) => {
    console.log('Banner ad click:', adData);
  }
});

Key Features:

Dynamic size optimization (based on image size)
Background loading for faster UX
Auto slide support (when multiple ads)

Text Ads

Native text ads that integrate naturally with page content.

// Basic text ad
AdStage.ads.text('text-container', {
  maxLines: 3
});
 
// With click handler
AdStage.ads.text('text-container', {
  maxLines: 3,
  onClick: (adData) => {
    console.log('Text ad click:', adData);
  }
});

Key Features:

Auto height (content-driven)
Seamless design blending
Optional max line limit

Video Ads

High‑engagement video ad format.

// Basic video ad (defaults: autoplay true, muted true, controls false)
AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: true,  // default
  muted: true,     // default
  controls: false  // default
});
 
// User‑controlled video ad
AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: false,
  muted: false,
  controls: true,
  onClick: (adData) => {
    console.log('Video ad click:', adData);
  }
});

Key Features:

Optimized for single video (maxAds: 1)
Native HTML5 player
Mobile inline playback (playsinline: true)
Loop enabled by default (loop: true)

🔄 Ad Display Process

graph TD
    A[SDK Initialization] --> B[Detect Ad Container]
    B --> C[Request Ad]
    C --> D[Receive Ad Response]
    D --> E[Render Ad]
    E --> F[Send Impression Event]
    F --> G[Track User Interactions]

Initialization: Configure SDK via AdStage.init()
Container prep: Ensure DOM node exists
Ad request: Server queried for ad content
Rendering: Ad injected into target container
Tracking: Impression & click events auto tracked

⚙️ Configuration Options

Common Options

Reusable across all ad types:

Option	Type	Default	Description
`onClick`	`function`	`undefined`	Callback fired on ad click
`adId`	`string`	`undefined`	Force a specific ad ID
`language`	`'ko'	'en'	'ja'
`deviceType`	`'MOBILE'	'DESKTOP'`	`undefined`
`country`	`'KR'	'US'	'JP'

Banner‑Only Options

Option	Type	Default	Description
`width`	`string	number`	`'100%'`
`height`	`number`	`250`	Ad height (default 250px)
`autoSlide`	`boolean`	`false`	Auto slide when multiple ads
`slideInterval`	`number`	`5000`	Interval between slides (ms)

Text‑Only Options

Option	Type	Default	Description
`maxLines`	`number`	`3`	Max visible lines
`style`	`string`	`'default'`	Theme style

Note: Text ads auto adjust height (height: 'auto').

Video‑Only Options

Option	Type	Default	Description
`width`	`number`	`640`	Video width
`height`	`number`	`360`	Video height
`autoplay`	`boolean`	`true`	Autoplay enabled
`muted`	`boolean`	`true`	Start muted
`loop`	`boolean`	`true`	Loop playback
`controls`	`boolean`	`false`	Show native controls
`playsinline`	`boolean`	`true`	Mobile inline playback
`hideControls`	`boolean`	`false`	Hide all controls
`customControls`	`object`	`undefined`	Fine‑grained control visibility

Custom Video Control Flags

customControls: {
  hidePlayButton: boolean,      // Hide play button
  hideProgressBar: boolean,     // Hide progress bar  
  hideCurrentTime: boolean,     // Hide current time
  hideRemainingTime: boolean,   // Hide remaining time
  hideVolumeSlider: boolean,    // Hide volume slider
  hideMuteButton: boolean,      // Hide mute button
  hideFullscreenButton: boolean // Hide fullscreen button
}

Example: Advanced Usage

// Display a banner with a specific ad ID
AdStage.ads.banner('my-banner', {
  width: '100%',
  height: 250,
  adId: 'specific-ad-123',
  language: 'ko',
  deviceType: 'DESKTOP',
  onClick: (adData) => {
    console.log('Ad click:', adData);
    // Custom tracking logic
  }
});
 
// Video ad with custom controls
AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: false,
  muted: false,
  controls: true,
  customControls: {
    hideFullscreenButton: true,
    hideVolumeSlider: false,
    hideProgressBar: false
  }
});

📊 Performance Optimization

Background Loading

Ads are requested asynchronously:

// Slot ID returns immediately while ad loads in background
const slotId = AdStage.ads.banner('banner-ad');
console.log('Slot created:', slotId); // Immediate
 
// Actual ad content rendered later

Auto Cleanup

Removed DOM containers are automatically detected & cleaned:

const slotId = AdStage.ads.banner('banner-ad');
document.getElementById('banner-ad').remove(); // Slot auto destroyed

Retry Logic

If container not yet present, SDK retries progressively:

const slotId = AdStage.ads.banner('not-yet-exists', {
  width: '100%',
  height: 250
});
 
setTimeout(() => {
  const div = document.createElement('div');
  div.id = 'not-yet-exists';
  document.body.appendChild(div); // Ad renders automatically later
}, 1000);

🎨 Styling Guide

CSS Classes

Classes automatically applied by the SDK:

/* Ad container */
.adstage-ad {
  position: relative;
  overflow: hidden;
}
 
/* Loading state */
.adstage-loading {
  opacity: 0.7;
}
 
/* Loaded */
.adstage-loaded {
  opacity: 1;
  transition: opacity 0.3s ease;
}
 
/* Error state */
.adstage-error {
  border: 1px solid #ff0000;
}

Responsive Design

Adjust banner size by viewport:

AdStage.ads.banner('responsive-banner', {
  width: '100%',
  height: window.innerWidth > 768 ? 250 : 100,
  responsive: true
});

Real Usage Examples

The SDK works with JavaScript, React, and Next.js. Below are real integration patterns.

JavaScript (UMD)

Load the UMD build directly in an HTML page.

<!DOCTYPE html>
<html>
<head>
  <title>AdStage SDK Example</title>
  </head>
  <body>
  <div id="banner-ad">Loading banner ad...</div>
  <div id="text-ad">Loading text ad...</div>
  <div id="video-ad">Loading video ad...</div>
 
  <script src="https://unpkg.com/@adstage/web-sdk/dist/index.umd.js"></script>
  <script>
    AdStage.init({
      apiKey: 'your-api-key',
      baseUrl: '',
      debug: true
    });
 
    const bannerSlotId = AdStage.ads.banner('banner-ad', {
      width: '100%',
      height: 250,
      onClick: (adData) => console.log('Banner click:', adData)
    });
 
    const textSlotId = AdStage.ads.text('text-ad', {
      maxLines: 3,
      onClick: (adData) => console.log('Text click:', adData)
    });
 
    const videoSlotId = AdStage.ads.video('video-ad', {
      width: 640,
      height: 360,
      autoplay: true,
      muted: true,
      controls: false,
      onClick: (adData) => console.log('Video click:', adData)
    });
  </script>
  </body>
</html>

React (Direct Usage)

import React, { useEffect, useRef } from 'react';
import { AdStage } from '@adstage/web-sdk';
 
function AdComponent() {
  const bannerRef = useRef(null);
  const textRef = useRef(null);
  const videoRef = useRef(null);
  const slotIdsRef = useRef({});
 
  useEffect(() => {
    AdStage.init({
      apiKey: 'your-api-key',
      debug: true
    });
 
    if (bannerRef.current) {
      slotIdsRef.current.banner = AdStage.ads.banner(bannerRef.current, {
        width: '100%',
        height: 250,
        onClick: (adData) => console.log('Banner click:', adData)
      });
    }
 
    if (textRef.current) {
      slotIdsRef.current.text = AdStage.ads.text(textRef.current, {
        maxLines: 3,
        onClick: (adData) => console.log('Text click:', adData)
      });
    }
 
    if (videoRef.current) {
      slotIdsRef.current.video = AdStage.ads.video(videoRef.current, {
        width: 640,
        height: 360,
        autoplay: true,
        muted: true,
        controls: false,
        onClick: (adData) => console.log('Video click:', adData)
      });
    }
 
    return () => {
      Object.values(slotIdsRef.current).forEach(slotId => {
        if (slotId) AdStage.ads.destroy(slotId);
      });
    };
  }, []);
 
  return (
    <div>
      <h1>AdStage SDK - React Example</h1>
 
      <div style={{ margin: '20px 0' }}>
        <h2>Banner Advertisement</h2>
        <div
          ref={bannerRef}
          style={{
            minHeight: '100px',
            border: '2px dashed #ccc',
            borderRadius: '4px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center'
          }}
        >
          Loading banner ad...
        </div>
      </div>
 
      <div style={{ margin: '20px 0' }}>
        <h2>Text Advertisement</h2>
        <div ref={textRef}>
          Loading text ad...
        </div>
      </div>
 
      <div style={{ margin: '20px 0' }}>
        <h2>Video Advertisement</h2>
        <div ref={videoRef}>
          Loading video ad...
        </div>
      </div>
    </div>
  );
}
 
export default AdComponent;

Next.js (Provider Pattern)

1. Configure Provider in `_app.js`

// pages/_app.js
import { AdStageProvider } from '@adstage/web-sdk';
 
export default function App({ Component, pageProps }) {
  return (
    <AdStageProvider
      config={{
        apiKey: 'your-api-key',
        debug: true
      }}
    >
      <Component {...pageProps} />
    </AdStageProvider>
  );
}

2. Use `useAdStageInstance` Hook

// pages/index.js
import { useEffect, useRef } from 'react';
import { useAdStageInstance } from '@adstage/web-sdk';
 
export default function Home() {
  const adstage = useAdStageInstance();
 
  const bannerRef = useRef(null);
  const textRef = useRef(null);
  const videoRef = useRef(null);
  const slotIdsRef = useRef({});
 
  useEffect(() => {
    if (adstage) {
      loadAds();
    }
    return () => {
      Object.values(slotIdsRef.current).forEach(slotId => {
        if (slotId) adstage?.ads?.destroy(slotId);
      });
    };
  }, [adstage]);
 
  const loadAds = () => {
    if (bannerRef.current) {
      slotIdsRef.current.banner = adstage.ads.banner(bannerRef.current, {
        width: '100%',
        height: 250,
        onClick: (adData) => console.log('Banner click:', adData)
      });
    }
    if (textRef.current) {
      slotIdsRef.current.text = adstage.ads.text(textRef.current, {
        maxLines: 3,
        onClick: (adData) => console.log('Text click:', adData)
      });
    }
    if (videoRef.current) {
      slotIdsRef.current.video = adstage.ads.video(videoRef.current, {
        width: 640,
        height: 360,
        autoplay: true,
        muted: true,
        controls: false,
        onClick: (adData) => console.log('Video click:', adData)
      });
    }
  };
 
  return (
    <div style={{ fontFamily: 'Arial, sans-serif', margin: '20px' }}>
      <h1>AdStage SDK - Next.js Ad Example</h1>
 
      {/* Banner Ad */}
      <div style={{ margin: '40px 0', padding: '20px', border: '1px solid #ddd' }}>
        <h2>Banner Advertisement</h2>
        <div
          ref={bannerRef}
          style={{
            minHeight: '100px',
            border: '2px dashed #ccc',
            borderRadius: '4px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center'
          }}
        >
          Loading banner ad...
        </div>
      </div>
 
      {/* Text Ad */}
      <div style={{ margin: '40px 0', padding: '20px', border: '1px solid #ddd' }}>
        <h2>Text Advertisement</h2>
        <div
          ref={textRef}
          style={{
            backgroundColor: 'rgba(34, 197, 94, 0.1)',
            borderRadius: '12px',
            border: '1px solid rgba(34, 197, 94, 0.2)',
            padding: '16px',
            minHeight: '80px'
          }}
        >
          Loading text ad...
        </div>
      </div>
 
      {/* Video Ad */}
      <div style={{ margin: '40px 0', padding: '20px', border: '1px solid #ddd' }}>
        <h2>Video Advertisement</h2>
        <div
          ref={videoRef}
          style={{
            minHeight: '100px',
            border: '2px dashed #ccc',
            borderRadius: '4px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center'
          }}
        >
          Loading video ad...
        </div>
      </div>
    </div>
  );
}

Advertising System Overview

Table of Contents