横幅广告

横幅广告是以图片为基础的广告，是网站上最常见的广告形式。AdStage SDK 支持横幅广告的自动尺寸调整、轮播功能与后台加载。

🎯 基本用法

简单的横幅广告

// 在 HTML 中准备容器
// <div id="banner-container"></div>
 
// 初始化 SDK（仅一次）
AdStage.init({
  apiKey: process.env.NEXT_PUBLIC_ADSTAGE_API_KEY
});
 
// 创建基本横幅广告
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250
});

处理点击事件

AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250,
  onClick: (adData) => {
    console.log('横幅广告被点击:', adData);
    // 可以添加自定义逻辑
  }
});

⚙️ 设置选项

基本选项

选项	类型	默认值	说明
`width`	`string \| number`	`'100%'`	横幅宽度（px 或 %）
`height`	`number`	`250`	横幅高度（px）
`onClick`	`function`	`undefined`	点击时执行的回调函数

高级选项

选项	类型	默认值	说明
`autoSlide`	`boolean`	`false`	有多个广告时自动轮播
`slideInterval`	`number`	`5000`	轮播间隔（毫秒）
`adId`	`string`	`undefined`	指定特定广告 ID

筛选选项

选项	类型	默认值	说明
`language`	`'ko' \| 'en' \| 'ja' \| 'zh'`	`undefined`	按语言筛选
`deviceType`	`'MOBILE' \| 'DESKTOP'`	`undefined`	按设备筛选
`country`	`'KR' \| 'US' \| 'JP' \| 'CN' \| 'DE'`	`undefined`	按国家筛选

💡 实际实现示例

以最简单的 CDN 方式，可以直接在 HTML 中使用。

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>横幅广告示例</title>
</head>
<body>
  <h1>我的网站</h1>
  
  <!-- 横幅广告容器 -->
  <div id="banner-container" style="width: 100%; height: 250px; border: 1px solid #ddd;">
    加载中...
  </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.banner('banner-container', {
      width: '100%',
      height: 250
    });
  </script>
</body>
</html>

🚀 高级功能

自动轮播

这是在有多个横幅广告时自动轮播的功能。

AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250,
  autoSlide: true,        // 启用自动轮播
  slideInterval: 3000     // 每 3 秒轮播
});

响应式横幅

这是根据屏幕尺寸调整横幅大小的方法。

// 利用媒体查询实现响应式
const getResponsiveHeight = () => {
  if (window.innerWidth <= 768) {
    return 100;  // 移动端: 高度 100px
  } else if (window.innerWidth <= 1024) {
    return 200;  // 平板: 高度 200px
  } else {
    return 250;  // 桌面端: 高度 250px
  }
};
 
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: getResponsiveHeight(),
  deviceType: window.innerWidth <= 768 ? 'MOBILE' : 'DESKTOP'
});
 
// 窗口尺寸变化时重新创建
window.addEventListener('resize', () => {
  // 移除现有广告后重新创建
  AdStage.ads.destroy(slotId);
  slotId = AdStage.ads.banner('banner-container', {
    width: '100%',
    height: getResponsiveHeight(),
    deviceType: window.innerWidth <= 768 ? 'MOBILE' : 'DESKTOP'
  });
});

指定特定广告 ID

想要只显示特定横幅广告时使用。

AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250,
  adId: 'banner-ad-123'  // 特定广告 ID
});

🔧 优化技巧

1. 运用动态尺寸调整

SDK 会自动按照图片尺寸优化容器。

// 按照图片尺寸自动调整
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 'auto'  // 按照图片比例自动调整
});

2. 后台加载

广告在后台加载，因此可以立即得到广告位 ID。

// 立即返回广告位 ID
const slotId = AdStage.ads.banner('banner-container');
console.log('广告位已创建:', slotId);  // 立即执行
 
// 实际广告是异步加载的

3. 运用自动清理

从 DOM 中移除容器时，广告也会自动清理。

const slotId = AdStage.ads.banner('banner-container');
 
// 从 DOM 中移除容器时会自动清理
document.getElementById('banner-container').remove();
// 不需要手动调用 destroy()

🎨 样式设置

运用 CSS 类

可以利用 SDK 自动添加的 CSS 类进行样式设置。

/* 广告容器基本样式 */
.adstage-ad {
  position: relative;
  overflow: hidden;
  border-radius: 8px;
}
 
/* 加载状态 */
.adstage-loading {
  opacity: 0.7;
  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 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);

横幅广告

目录