文字廣告

文字廣告是以文字為基礎的原生廣告，能與網站內容自然融合。它帶來較高的點擊率與使用者體驗，並會依內容自動調整高度。

🎯 基本用法

簡單的文字廣告

// 在 HTML 中準備容器
// <div id="text-container"></div>
 
// 初始化 SDK（只需一次）
AdStage.init({
  apiKey: process.env.NEXT_PUBLIC_ADSTAGE_API_KEY
});
 
// 建立基本文字廣告
AdStage.ads.text('text-container');

點擊事件處理

AdStage.ads.text('text-container', {
  onClick: (adData) => {
    console.log('文字廣告被點擊:', adData);
    // 可以加入自訂邏輯
  }
});

⚙️ 設定選項

基本選項

選項	類型	預設值	說明
`maxLines`	`number`	`3`	要顯示的最大行數
`style`	`string`	`'default'`	樣式主題
`onClick`	`function`	`undefined`	點擊時執行的回呼函式

篩選選項

選項	類型	預設值	說明
`adId`	`string`	`undefined`	指定特定的廣告 ID
`language`	`'ko' \| 'en' \| 'ja' \| 'zh'`	`undefined`	依語言篩選
`deviceType`	`'MOBILE' \| 'DESKTOP'`	`undefined`	依裝置篩選
`country`	`'KR' \| 'US' \| 'JP' \| 'CN' \| 'DE'`	`undefined`	依國家篩選

參考：文字廣告會依內容長度自動調整高度（height: 'auto'）。

💡 實際實作範例

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

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>文字廣告範例</title>
</head>
<body>
  <h1>我的網站</h1>
  
  <!-- 文字廣告容器 -->
  <div id="text-container" style="width: 100%; max-width: 600px; margin: 20px auto; padding: 16px; 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.text('text-container', {
      maxLines: 3
    });
  </script>
</body>
</html>

🚀 進階功能

行數限制

可以限制文字廣告顯示的行數。

// 限制為 1 行（單行文字廣告）
AdStage.ads.text('text-container', {
  maxLines: 1
});
 
// 允許最多 5 行
AdStage.ads.text('text-container', {
  maxLines: 5
});

響應式行數調整

依螢幕尺寸動態調整行數的方法。

// 運用媒體查詢實作的響應式方案
const getResponsiveMaxLines = () => {
  if (window.innerWidth <= 768) {
    return 2;  // 行動裝置: 2 行
  } else if (window.innerWidth <= 1024) {
    return 3;  // 平板: 3 行
  } else {
    return 4;  // 桌機: 4 行
  }
};
 
AdStage.ads.text('text-container', {
  maxLines: getResponsiveMaxLines(),
  deviceType: window.innerWidth <= 768 ? 'MOBILE' : 'DESKTOP'
});
 
// 視窗調整大小時重新建立
window.addEventListener('resize', () => {
  // 移除原有廣告後重新建立
  AdStage.ads.destroy(slotId);
  slotId = AdStage.ads.text('text-container', {
    maxLines: getResponsiveMaxLines(),
    deviceType: window.innerWidth <= 768 ? 'MOBILE' : 'DESKTOP'
  });
});

指定特定的廣告 ID

只想顯示特定文字廣告時使用。

AdStage.ads.text('text-container', {
  maxLines: 3,
  adId: 'text-ad-456'  // 特定廣告 ID
});

🔧 最佳化提示

1. 指定行數

以 maxLines 指定要顯示的最大行數（數字，預設值 3）。文字廣告的高度會依內容長度自動（height: 'auto'）調整。

// 最多顯示 3 行（預設值）
AdStage.ads.text('text-container', {
  maxLines: 3
});

2. 背景載入

廣告於背景載入，因此可以立即取得廣告版位 ID。

// 立即回傳廣告版位 ID
const slotId = AdStage.ads.text('text-container');
console.log('廣告版位已建立:', slotId);  // 立即執行
 
// 實際廣告為非同步載入

3. 運用自動清理

當容器自 DOM 中被移除時，廣告也會自動清理。

const slotId = AdStage.ads.text('text-container');
 
// 自 DOM 移除容器時會自動清理
document.getElementById('text-container').remove();
// 無需手動呼叫 destroy()

🎨 樣式設計

運用 CSS 類別

可以運用 SDK 自動加上的 CSS 類別進行樣式設計。

/* 廣告容器基本樣式 */
.adstage-text-ad {
  position: relative;
  overflow: hidden;
  font-family: inherit;
  line-height: 1.6;
}
 
/* 載入狀態 */
.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);

文字廣告

目錄