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 类确认广告位状态📚 相关文档