動画広告

動画広告は動画ベースの広告で、高いエンゲージメントと視覚的なインパクトを提供します。AdStage SDK は HTML5 動画プレーヤーを使用し、モバイル最適化とさまざまな再生オプションをサポートしています。

🎯 基本的な使い方

シンプルな動画広告

// HTML にコンテナを用意
// <div id="video-container"></div>
 
// SDK の初期化（1 回のみ）
AdStage.init({
  apiKey: process.env.NEXT_PUBLIC_ADSTAGE_API_KEY
});
 
// 基本的な動画広告を作成
AdStage.ads.video('video-container', {
  width: 640,
  height: 360
});

クリックイベントの処理

AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  onClick: (adData) => {
    console.log('動画広告がクリックされました:', adData);
    // 独自のロジックを追加可能
  }
});

⚙️ 設定オプション

基本オプション

オプション	型	デフォルト値	説明
`width`	`number`	`640`	動画の幅（px）
`height`	`number`	`360`	動画の高さ（px）
`autoplay`	`boolean`	`true`	自動再生の有無
`muted`	`boolean`	`true`	ミュートの有無
`controls`	`boolean`	`false`	標準コントロールの表示
`onClick`	`function`	`undefined`	クリック時に実行されるコールバック関数

高度なオプション

オプション	型	デフォルト値	説明
`loop`	`boolean`	`true`	ループ再生の有無
`playsinline`	`boolean`	`true`	インライン再生（モバイル）
`customControls`	`object`	`undefined`	コントロールの詳細設定

フィルタリングオプション

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

参考: 動画広告は単一動画に最適化するよう設計されています（maxAds: 1）。

💡 実際の実装例

最もシンプルな CDN 方式で、HTML からすぐに使用できます。

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>動画広告の例</title>
</head>
<body>
  <h1>マイ Web サイト</h1>
  
  <!-- 動画広告コンテナ -->
  <div id="video-container" style="width: 640px; height: 360px; margin: 20px auto; border: 1px solid #ddd; border-radius: 8px;">
    読み込み中...
  </div>
 
  <!-- AdStage SDK の読み込み -->
  <script src="https://unpkg.com/@adstage/web-sdk/dist/index.umd.js"></script>
  <script>
    // SDK の初期化
    AdStage.init({
      apiKey: 'your-api-key'
    });
 
    // 動画広告の作成
    AdStage.ads.video('video-container', {
      width: 640,
      height: 360,
      autoplay: true,
      muted: true
    });
  </script>
</body>
</html>

🚀 高度な機能

カスタムコントロール

動画プレーヤーの各コントロールを細かく設定できます。

AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  controls: true,
  customControls: {
    hidePlayButton: false,        // 再生ボタンを表示
    hideProgressBar: false,       // プログレスバーを表示
    hideVolumeSlider: false,      // 音量スライダーを表示
    hideFullscreenButton: true    // 全画面ボタンを非表示
  }
});

レスポンシブ動画

画面サイズに応じて動画のサイズを調整する方法です。

// メディアクエリを活用したレスポンシブ実装
const getResponsiveVideoSize = () => {
  if (window.innerWidth <= 768) {
    return { width: '100%', height: 200 };  // モバイル
  } else if (window.innerWidth <= 1024) {
    return { width: 640, height: 300 };     // タブレット
  } else {
    return { width: 640, height: 360 };     // デスクトップ
  }
};
 
const { width, height } = getResponsiveVideoSize();
 
AdStage.ads.video('video-container', {
  width,
  height,
  autoplay: true,
  muted: true,
  deviceType: window.innerWidth <= 768 ? 'MOBILE' : 'DESKTOP'
});
 
// ウィンドウのリサイズ時に再作成
window.addEventListener('resize', () => {
  // 既存の広告を削除してから新しく作成
  AdStage.ads.destroy(slotId);
  const newSize = getResponsiveVideoSize();
  slotId = AdStage.ads.video('video-container', {
    ...newSize,
    autoplay: true,
    muted: true
  });
});

特定の広告 ID を指定

特定の動画広告だけを表示したい場合に使用します。

AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  adId: 'video-ad-789'  // 特定の広告 ID
});

🔧 最適化のヒント

1. 動的なサイズ調整の活用

SDK が動画のサイズに合わせてコンテナを自動で最適化します。

// 16:9 の比率を自動で維持
AdStage.ads.video('video-container', {
  width: '100%',
  height: 'auto'  // 比率に合わせて自動調整
});

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

広告はバックグラウンドで読み込まれるため、スロット ID をすぐに受け取れます。

// スロット ID を即座に返す
const slotId = AdStage.ads.video('video-container');
console.log('スロット作成完了:', slotId);  // 即座に実行
 
// 実際の広告は非同期で読み込まれる

3. 自動クリーンアップの活用

DOM からコンテナが削除されると、広告も自動的にクリーンアップされます。

const slotId = AdStage.ads.video('video-container');
 
// DOM からコンテナを削除すると自動でクリーンアップされる
document.getElementById('video-container').remove();
// 手動で destroy() を呼び出す必要はない

🎨 スタイリング

CSS クラスの活用

SDK が自動で追加する CSS クラスを活用してスタイリングできます。

/* 広告コンテナの基本スタイル */
.adstage-video-ad {
  position: relative;
  overflow: hidden;
  border-radius: 8px;
  background: #000;
}
 
/* 読み込み中の状態 */
.adstage-loading {
  opacity: 0.7;
  background: linear-gradient(90deg, #000 25%, #333 50%, #000 75%);
  background-size: 200% 100%;
  animation: loading 1.5s infinite;
}
 
@keyframes loading {
  0% { background-position: 200% 0; }
  100% { background-position: -200% 0; }
}
 
/* 読み込み完了 */
.adstage-loaded {
  opacity: 1;
  transition: opacity 0.3s ease;
}
 
/* エラー状態 */
.adstage-error {
  border: 1px solid #ff6b6b;
  background-color: #ffe0e0;
}

スロットの状態確認

// すべてのスロットを確認
const allSlots = AdStage.ads.getAllSlots();
console.log('全広告スロット:', allSlots);
 
// 特定のスロットを確認
const slot = AdStage.ads.getSlotById(slotId);
console.log('スロット情報:', slot);

📚 関連ドキュメント

広告システムの概要: 広告システム全体の紹介
バナー広告: バナー広告ガイド
テキスト広告: テキスト広告ガイド
高度な設定: パフォーマンスの最適化と高度な機能

動画広告

目次