adstage
Web SDK廣告

影片廣告

影片廣告是以影片為基礎的廣告形式，具有較高的參與度與視覺衝擊力。AdStage SDK 使用 HTML5 影片播放器，支援行動裝置最佳化與多種播放選項。

🎯 基本用法

簡單的影片廣告

// 在 HTML 中準備容器
// <div id="video-container"></div>
 
// 初始化 SDK（只需一次）
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);
    // 可以加入自訂邏輯
  }
});

⚙️ 設定選項

基本選項

選項類型預設值說明
widthnumber640影片寬度（px）
heightnumber360影片高度（px）
autoplaybooleantrue是否自動播放
mutedbooleantrue是否靜音
controlsbooleanfalse顯示預設控制項
onClickfunctionundefined點擊時執行的回呼函式

進階選項

選項類型預設值說明
loopbooleantrue是否重複播放
playsinlinebooleantrue內嵌播放（行動裝置）
customControlsobjectundefined控制項的細部設定

篩選選項

選項類型預設值說明
adIdstringundefined指定特定的廣告 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>我的網站</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);

📚 相關文件

上一頁

文字廣告

下一頁

共用功能

目錄

🎯 基本用法簡單的影片廣告處理點擊事件⚙️ 設定選項基本選項進階選項篩選選項💡 實際實作範例🚀 進階功能自訂控制項響應式影片指定特定的廣告 ID🔧 最佳化訣竅1. 運用動態尺寸調整2. 背景載入3. 運用自動清理🎨 樣式設計運用 CSS 類別確認版位狀態📚 相關文件