広告システムの概要

AdStage Web SDK は、Web アプリケーションで 3 種類の広告をサポートしています。

🎯 サポートする広告タイプ

画像ベースの広告で、最も一般的な形式です。

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

特徴: 画像ベース、自動サイズ調整、スライド対応

テキスト広告（Text Ads）

テキストベースのネイティブ広告で、コンテンツに自然に溶け込みます。

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

特徴: 高さの自動調整、行数制限、ネイティブスタイル

動画広告（Video Ads）

動画ベースの広告で、高いエンゲージメントを得られます。

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

特徴: HTML5 動画、自動再生/ミュート、モバイル最適化

🔄 基本的な利用の流れ

SDK の初期化 - AdStage.init() で設定
コンテナの準備 - HTML に広告の表示領域を作成
広告のリクエスト - ads.banner()、ads.text()、ads.video() を呼び出し
自動レンダリング - バックグラウンドで広告を読み込んで表示
イベントのトラッキング - インプレッション/クリックを自動収集

📚 次のステップ

広告タイプごとの詳しい使い方をご確認ください。

共通機能: すべての広告タイプに共通するオプションと機能
バナー広告: バナー広告の詳細設定と高度な機能
テキスト広告: テキスト広告のカスタマイズ方法
動画広告: 動画広告の制御と最適化

🎯 サポートする広告タイプ

画像ベースのバナー広告で、最も一般的な形式の Web 広告です。

// 基本的なバナー広告
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250
});
 
// クリックイベントの処理と高度なオプション
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250,
  onClick: (adData) => {
    console.log('バナー広告クリック:', adData);
  }
});

主な特徴:

動的なサイズ調整（画像サイズに基づいて自動で最適化）
バックグラウンド読み込みによる高速なレスポンス
自動スライドに対応（広告が複数ある場合）

テキスト広告（Text Ads）

テキストベースのネイティブ広告で、コンテンツと自然に調和します。

// 基本的なテキスト広告
AdStage.ads.text('text-container', {
  maxLines: 3
});
 
// クリックイベントの処理
AdStage.ads.text('text-container', {
  maxLines: 3,
  onClick: (adData) => {
    console.log('テキスト広告クリック:', adData);
  }
});

主な特徴:

コンテンツの高さに自動で合わせる（height: 'auto'）
サイトのデザインと自然に統合
最大行数の制限が可能

動画広告（Video Ads）

動画ベースの広告で、高いエンゲージメントを得られます。

// 基本的な動画広告（デフォルト: 自動再生、ミュート、コントロール非表示）
AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: true,  // デフォルト: true
  muted: true,     // デフォルト: true
  controls: false  // デフォルト: false
});
 
// ユーザーが操作できる動画広告
AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: false,
  muted: false,
  controls: true,
  onClick: (adData) => {
    console.log('動画広告クリック:', adData);
  }
});

主な特徴:

単一動画に最適化（maxAds: 1）
HTML5 動画プレーヤー
モバイルでのインライン再生に対応（playsinline: true）
ループ再生がデフォルトで有効（loop: true）

🔄 広告表示のプロセス

graph TD
    A[SDK の初期化] --> B[広告コンテナの検出]
    B --> C[広告のリクエスト]
    C --> D[広告レスポンスの受信]
    D --> E[広告のレンダリング]
    E --> F[インプレッションイベントの送信]
    F --> G[ユーザーインタラクションのトラッキング]

初期化: AdStage.init() で SDK を設定
コンテナの準備: HTML に広告を表示する要素を作成
広告のリクエスト: サーバーに広告コンテンツをリクエスト
レンダリング: 受け取った広告を指定のコンテナに表示
トラッキング: インプレッションとクリックのイベントを自動でトラッキング

⚙️ 設定オプション

共通オプション

すべての広告タイプで使用できるオプションです。

オプション	型	デフォルト値	説明
`onClick`	`function`	`undefined`	広告クリック時のコールバック関数
`adId`	`string`	`undefined`	特定の広告 ID を指定
`language`	`'ko' \| 'en' \| 'ja' \| 'zh'`	`undefined`	言語フィルター
`deviceType`	`'MOBILE' \| 'DESKTOP'`	`undefined`	デバイスタイプのフィルター
`country`	`'KR' \| 'US' \| 'JP' \| 'CN' \| 'DE'`	`undefined`	国フィルター

バナー広告専用のオプション

オプション	型	デフォルト値	説明
`width`	`string \| number`	`'100%'`	広告の幅
`height`	`number`	250	広告の高さ（バナーのデフォルトは 250px）
`autoSlide`	`boolean`	`false`	広告が複数ある場合に自動スライド
`slideInterval`	`number`	`5000`	スライドの間隔（ms）

テキスト広告専用のオプション

オプション	型	デフォルト値	説明
`maxLines`	`number`	`3`	最大行数
`style`	`string`	`'default'`	スタイルテーマ

参考: テキスト広告は、コンテンツに応じて高さが自動調整されます（height: 'auto'）。

動画広告専用のオプション

オプション	型	デフォルト値	説明
`width`	`number`	`640`	動画の幅
`height`	`number`	`360`	動画の高さ
`autoplay`	`boolean`	`true`	自動再生
`muted`	`boolean`	`true`	ミュート
`loop`	`boolean`	`true`	ループ再生
`controls`	`boolean`	`false`	コントロールの表示
`playsinline`	`boolean`	`true`	インライン再生（モバイル）
`hideControls`	`boolean`	`false`	すべてのコントロールを非表示
`customControls`	`object`	`undefined`	コントロールの詳細設定

動画のカスタムコントロールオプション

customControls: {
  hidePlayButton: boolean,      // 再生ボタンを非表示
  hideProgressBar: boolean,     // プログレスバーを非表示  
  hideCurrentTime: boolean,     // 現在の再生時間を非表示
  hideRemainingTime: boolean,   // 残り時間を非表示
  hideVolumeSlider: boolean,    // 音量スライダーを非表示
  hideMuteButton: boolean,      // ミュートボタンを非表示
  hideFullscreenButton: boolean // 全画面ボタンを非表示
}

例: 高度な設定

// 特定の広告 ID でバナー広告を表示
AdStage.ads.banner('my-banner', {
  width: '100%',
  height: 250,
  adId: 'specific-ad-123',
  language: 'ko',
  deviceType: 'DESKTOP',
  onClick: (adData) => {
    console.log('広告クリック:', adData);
    // 独自のトラッキングロジック
  }
});
 
// カスタムコントロール付きの動画広告
AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: false,
  muted: false,
  controls: true,
  customControls: {
    hideFullscreenButton: true,
    hideVolumeSlider: false,
    hideProgressBar: false
  }
});

📊 パフォーマンスの最適化

バックグラウンド読み込み

SDK は自動的にバックグラウンドで広告を読み込みます。

// スロット ID は即座に返され、広告はバックグラウンドで読み込まれる
const slotId = AdStage.ads.banner('banner-ad');
console.log('スロット作成完了:', slotId); // 即座に実行
 
// 実際の広告は非同期で読み込まれてレンダリングされる

自動クリーンアップ（Auto Cleanup）

DOM から削除された広告コンテナは自動的にクリーンアップされます。

// MutationObserver による自動検知とクリーンアップ
// 開発者が手動で destroy() を呼び出す必要はない
const slotId = AdStage.ads.banner('banner-ad');
 
// DOM からコンテナが削除されると、スロットも自動的にクリーンアップされる
document.getElementById('banner-ad').remove();

リトライロジック

コンテナが見つからない場合は自動でリトライします。

// コンテナがまだ存在しなくても段階的にリトライ
const slotId = AdStage.ads.banner('not-yet-exists', {
  width: '100%',
  height: 250
});
 
// 後から DOM にコンテナが追加されると、自動で広告を表示
setTimeout(() => {
  const div = document.createElement('div');
  div.id = 'not-yet-exists';
  document.body.appendChild(div);
}, 1000);

🎨 スタイリングガイド

CSS クラス

SDK が自動で追加する CSS クラスです。

/* 広告コンテナ */
.adstage-ad {
  position: relative;
  overflow: hidden;
}
 
/* 読み込み中の状態 */
.adstage-loading {
  opacity: 0.7;
}
 
/* 読み込み完了 */
.adstage-loaded {
  opacity: 1;
  transition: opacity 0.3s ease;
}
 
/* エラー状態 */
.adstage-error {
  border: 1px solid #ff0000;
}

レスポンシブデザイン

さまざまな画面サイズに合わせた広告の設定です。

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

実際の使用例

SDK は JavaScript、React、Next.js の環境で使用できます。実際の例を通じて実装方法を確認しましょう。

JavaScript（UMD 方式）

HTML ファイルで UMD 版を直接読み込んで使用する方法です。

<!DOCTYPE html>
<html>
<head>
  <title>AdStage SDK Example</title>
</head>
<body>
  <!-- 広告コンテナ -->
  <div id="banner-ad">バナー広告を読み込み中です...</div>
  <div id="text-ad">テキスト広告を読み込み中です...</div>
  <div id="video-ad">動画広告を読み込み中です...</div>
 
  <!-- SDK の読み込み -->
  <script src="https://unpkg.com/@adstage/web-sdk/dist/index.umd.js"></script>
  
  <script>
    // SDK の初期化
    AdStage.init({
      apiKey: 'your-api-key',
      debug: true
    });
    
    // 広告の作成
    const bannerSlotId = AdStage.ads.banner('banner-ad', {
      width: '100%',
      height: 250,
      onClick: (adData) => console.log('バナークリック:', adData)
    });
    
    const textSlotId = AdStage.ads.text('text-ad', {
      maxLines: 3,
      onClick: (adData) => console.log('テキストクリック:', adData)
    });
    
    const videoSlotId = AdStage.ads.video('video-ad', {
      width: 640,
      height: 360,
      autoplay: true,
      muted: true,
      controls: false,
      onClick: (adData) => console.log('動画クリック:', adData)
    });
  </script>
</body>
</html>

React（基本方式）

React で SDK を直接使用する方法です。

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(() => {
    // SDK の初期化
    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('バナークリック:', adData)
      });
    }
 
    if (textRef.current) {
      slotIdsRef.current.text = AdStage.ads.text(textRef.current, {
        maxLines: 3,
        onClick: (adData) => console.log('テキストクリック:', 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('動画クリック:', adData)
      });
    }
 
    // クリーンアップ関数
    return () => {
      Object.values(slotIdsRef.current).forEach(slotId => {
        if (slotId) AdStage.ads.destroy(slotId);
      });
    };
  }, []);
 
  return (
    <div>
      <h1>AdStage SDK - React の例</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'
          }}
        >
          バナー広告を読み込み中です...
        </div>
      </div>
 
      <div style={{ margin: '20px 0' }}>
        <h2>Text Advertisement</h2>
        <div ref={textRef}>
          テキスト広告を読み込み中です...
        </div>
      </div>
 
      <div style={{ margin: '20px 0' }}>
        <h2>Video Advertisement</h2>
        <div ref={videoRef}>
          動画広告を読み込み中です...
        </div>
      </div>
    </div>
  );
}
 
export default AdComponent;

Next.js（Provider 方式）

Next.js で AdStageProvider を使用する推奨の方法です。

1. _app.js で Provider を設定

// 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. ページで useAdStageInstance フックを使用

// 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('バナークリック:', adData)
      });
    }
    
    // テキスト広告
    if (textRef.current) {
      slotIdsRef.current.text = adstage.ads.text(textRef.current, {
        maxLines: 3,
        onClick: (adData) => console.log('テキストクリック:', 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('動画クリック:', adData)
      });
    }
  };
 
  return (
    <div style={{ fontFamily: 'Arial, sans-serif', margin: '20px' }}>
      <h1>AdStage SDK - Next.js 広告の例</h1>
      
      {/* バナー広告 */}
      <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'
          }}
        >
          バナー広告を読み込み中です...
        </div>
      </div>
      
      {/* テキスト広告 */}
      <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'
          }}
        >
          テキスト広告を読み込み中です...
        </div>
      </div>
      
      {/* 動画広告 */}
      <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'
          }}
        >
          動画広告を読み込み中です...
        </div>
      </div>
    </div>
  );
}

広告システムの概要

🎯 サポートする広告タイプ

バナー広告（Banner Ads）

テキスト広告（Text Ads）

動画広告（Video Ads）

🔄 基本的な利用の流れ

📚 次のステップ

🎯 サポートする広告タイプ

バナー広告（Banner Ads）

テキスト広告（Text Ads）

動画広告（Video Ads）

🔄 広告表示のプロセス

⚙️ 設定オプション

共通オプション

バナー広告専用のオプション

テキスト広告専用のオプション

動画広告専用のオプション

動画のカスタムコントロールオプション

例: 高度な設定

📊 パフォーマンスの最適化

バックグラウンド読み込み

自動クリーンアップ（Auto Cleanup）

リトライロジック

🎨 スタイリングガイド

CSS クラス

レスポンシブデザイン

実際の使用例

JavaScript（UMD 方式）

React（基本方式）

Next.js（Provider 方式）

1. _app.js で Provider を設定

2. ページで useAdStageInstance フックを使用

目次