橫幅廣告

橫幅廣告是以圖片為基礎的廣告，是網站上最常見的廣告形式。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);

橫幅廣告

目錄