ภาพรวมระบบโฆษณา

AdStage Web SDK รองรับโฆษณา 3 ประเภทในเว็บแอปพลิเคชัน

🎯 ประเภทโฆษณาที่รองรับ

โฆษณาที่ใช้รูปภาพเป็นหลัก ซึ่งเป็นรูปแบบที่พบได้บ่อยที่สุด

AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250
});

คุณสมบัติ: ใช้รูปภาพเป็นหลัก, ปรับขนาดอัตโนมัติ, รองรับสไลด์

โฆษณาข้อความ (Text Ads)

โฆษณาเนทีฟที่ใช้ข้อความเป็นหลัก ผสานเข้ากับเนื้อหาได้อย่างเป็นธรรมชาติ

AdStage.ads.text('text-container');

คุณสมบัติ: ปรับความสูงอัตโนมัติ, จำกัดจำนวนบรรทัด, สไตล์เนทีฟ

โฆษณาวิดีโอ (Video Ads)

โฆษณาที่ใช้วิดีโอเป็นหลัก ให้ระดับการมีส่วนร่วมที่สูง

AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: true,
  muted: true
});

คุณสมบัติ: วิดีโอ HTML5, เล่นอัตโนมัติ/ปิดเสียง, ปรับให้เหมาะกับมือถือ

🔄 ขั้นตอนการใช้งานเบื้องต้น

เริ่มต้นใช้งาน SDK - ตั้งค่าด้วย AdStage.init()
เตรียมคอนเทนเนอร์ - สร้างพื้นที่แสดงโฆษณาใน HTML
เรียกขอโฆษณา - เรียกใช้ ads.banner(), ads.text(), ads.video()
เรนเดอร์อัตโนมัติ - โหลดและแสดงโฆษณาในเบื้องหลัง
ติดตามอีเวนต์ - เก็บข้อมูลการแสดงผล/การคลิกโดยอัตโนมัติ

📚 ขั้นตอนถัดไป

ดูวิธีใช้งานโดยละเอียดของโฆษณาแต่ละประเภทได้เลย:

ฟีเจอร์ทั่วไป: ตัวเลือกและฟีเจอร์ที่ใช้ร่วมกันของโฆษณาทุกประเภท
โฆษณาแบนเนอร์: การตั้งค่าโดยละเอียดและฟีเจอร์ขั้นสูงของโฆษณาแบนเนอร์
โฆษณาข้อความ: วิธีปรับแต่งโฆษณาข้อความ
โฆษณาวิดีโอ: การควบคุมและการปรับแต่งโฆษณาวิดีโอ

🎯 ประเภทโฆษณาที่รองรับ

โฆษณาแบนเนอร์ที่ใช้รูปภาพเป็นหลัก ซึ่งเป็นรูปแบบโฆษณาเว็บที่พบได้บ่อยที่สุด

// 기본 배너 광고
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250
});
 
// 클릭 이벤트 처리 및 고급 옵션
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250,
  onClick: (adData) => {
    console.log('배너 광고 클릭:', adData);
  }
});

คุณสมบัติหลัก:

ปรับขนาดแบบไดนามิก (ปรับให้เหมาะสมอัตโนมัติตามขนาดรูปภาพ)
ตอบสนองรวดเร็วด้วยการโหลดในเบื้องหลัง
รองรับสไลด์อัตโนมัติ (เมื่อมีโฆษณาหลายรายการ)

โฆษณาข้อความ (Text Ads)

โฆษณาเนทีฟที่ใช้ข้อความเป็นหลัก กลมกลืนกับเนื้อหาได้อย่างเป็นธรรมชาติ

// 기본 텍스트 광고
AdStage.ads.text('text-container', {
  maxLines: 3
});
 
// 클릭 이벤트 처리
AdStage.ads.text('text-container', {
  maxLines: 3,
  onClick: (adData) => {
    console.log('텍스트 광고 클릭:', adData);
  }
});

คุณสมบัติหลัก:

ปรับให้พอดีกับความสูงของเนื้อหาโดยอัตโนมัติ (height: 'auto')
ผสานเข้ากับดีไซน์ของเว็บไซต์ได้อย่างเป็นธรรมชาติ
สามารถจำกัดจำนวนบรรทัดสูงสุดได้

โฆษณาวิดีโอ (Video Ads)

โฆษณาที่ใช้วิดีโอเป็นหลัก ให้ระดับการมีส่วนร่วมที่สูง

// 기본 비디오 광고 (기본값: 자동재생, 음소거, 컨트롤 숨김)
AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: true,  // 기본값: true
  muted: true,     // 기본값: true
  controls: false  // 기본값: false
});
 
// 사용자 제어 가능한 비디오 광고
AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: false,
  muted: false,
  controls: true,
  onClick: (adData) => {
    console.log('비디오 광고 클릭:', adData);
  }
});

คุณสมบัติหลัก:

ปรับให้เหมาะกับวิดีโอเดี่ยว (maxAds: 1)
เครื่องเล่นวิดีโอ HTML5
รองรับการเล่นแบบอินไลน์บนมือถือ (playsinline: true)
เปิดใช้การเล่นวนซ้ำเป็นค่าเริ่มต้น (loop: true)

🔄 กระบวนการแสดงโฆษณา

graph TD
    A[SDK 초기화] --> B[광고 컨테이너 탐지]
    B --> C[광고 요청]
    C --> D[광고 응답 수신]
    D --> E[광고 렌더링]
    E --> F[노출 이벤트 전송]
    F --> G[사용자 상호작용 추적]

เริ่มต้นใช้งาน: ตั้งค่า SDK ด้วย AdStage.init()
เตรียมคอนเทนเนอร์: สร้างเอลิเมนต์ที่จะแสดงโฆษณาใน HTML
เรียกขอโฆษณา: ขอเนื้อหาโฆษณาจากเซิร์ฟเวอร์
เรนเดอร์: แสดงโฆษณาที่ได้รับในคอนเทนเนอร์ที่กำหนด
ติดตาม: ติดตามอีเวนต์การแสดงผลและการคลิกโดยอัตโนมัติ

⚙️ ตัวเลือกการตั้งค่า

ตัวเลือกทั่วไป

ตัวเลือกที่ใช้ได้กับโฆษณาทุกประเภท:

ตัวเลือก	ประเภท	ค่าเริ่มต้น	คำอธิบาย
`onClick`	`function`	`undefined`	ฟังก์ชัน callback เมื่อคลิกโฆษณา
`adId`	`string`	`undefined`	ระบุ ID โฆษณาเฉพาะ
`language`	`'ko' \| 'en' \| 'ja' \| 'zh'`	`undefined`	ตัวกรองภาษา
`deviceType`	`'MOBILE' \| 'DESKTOP'`	`undefined`	ตัวกรองประเภทอุปกรณ์
`country`	`'KR' \| 'US' \| 'JP' \| 'CN' \| 'DE'`	`undefined`	ตัวกรองประเทศ

ตัวเลือกเฉพาะของโฆษณาแบนเนอร์

ตัวเลือก	ประเภท	ค่าเริ่มต้น	คำอธิบาย
`width`	`string \| number`	`'100%'`	ความกว้างของโฆษณา
`height`	`number`	250	ความสูงของโฆษณา (แบนเนอร์มีค่าเริ่มต้น 250px)
`autoSlide`	`boolean`	`false`	สไลด์อัตโนมัติเมื่อมีโฆษณาหลายรายการ
`slideInterval`	`number`	`5000`	ช่วงเวลาของสไลด์ (ms)

ตัวเลือกเฉพาะของโฆษณาข้อความ

ตัวเลือก	ประเภท	ค่าเริ่มต้น	คำอธิบาย
`maxLines`	`number`	`3`	จำนวนบรรทัดสูงสุด
`style`	`string`	`'default'`	ธีมสไตล์

หมายเหตุ: ความสูงของโฆษณาข้อความจะปรับโดยอัตโนมัติตามเนื้อหา (height: 'auto')

ตัวเลือกเฉพาะของโฆษณาวิดีโอ

ตัวเลือก	ประเภท	ค่าเริ่มต้น	คำอธิบาย
`width`	`number`	`640`	ความกว้างของวิดีโอ
`height`	`number`	`360`	ความสูงของวิดีโอ
`autoplay`	`boolean`	`true`	เล่นอัตโนมัติ
`muted`	`boolean`	`true`	ปิดเสียง
`loop`	`boolean`	`true`	เล่นวนซ้ำ
`controls`	`boolean`	`false`	แสดงตัวควบคุม
`playsinline`	`boolean`	`true`	เล่นแบบอินไลน์ (มือถือ)
`hideControls`	`boolean`	`false`	ซ่อนตัวควบคุมทั้งหมด
`customControls`	`object`	`undefined`	การตั้งค่าตัวควบคุมโดยละเอียด

ตัวเลือกตัวควบคุมแบบกำหนดเองของวิดีโอ

customControls: {
  hidePlayButton: boolean,      // 재생 버튼 숨기기
  hideProgressBar: boolean,     // 진행바 숨기기  
  hideCurrentTime: boolean,     // 현재 시간 숨기기
  hideRemainingTime: boolean,   // 남은 시간 숨기기
  hideVolumeSlider: boolean,    // 볼륨 슬라이더 숨기기
  hideMuteButton: boolean,      // 음소거 버튼 숨기기
  hideFullscreenButton: boolean // 전체화면 버튼 숨기기
}

ตัวอย่าง: การตั้งค่าขั้นสูง

// 특정 광고 ID로 배너 광고 표시
AdStage.ads.banner('my-banner', {
  width: '100%',
  height: 250,
  adId: 'specific-ad-123',
  language: 'ko',
  deviceType: 'DESKTOP',
  onClick: (adData) => {
    console.log('광고 클릭:', adData);
    // 사용자 정의 추적 로직
  }
});
 
// 커스텀 컨트롤이 있는 비디오 광고
AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: false,
  muted: false,
  controls: true,
  customControls: {
    hideFullscreenButton: true,
    hideVolumeSlider: false,
    hideProgressBar: false
  }
});

📊 การปรับประสิทธิภาพ

การโหลดในเบื้องหลัง

SDK จะโหลดโฆษณาในเบื้องหลังโดยอัตโนมัติ:

// 슬롯 ID는 즉시 반환, 광고는 백그라운드에서 로드
const slotId = AdStage.ads.banner('banner-ad');
console.log('슬롯 생성됨:', slotId); // 즉시 실행
 
// 실제 광고는 비동기로 로드되어 렌더링됨

การล้างข้อมูลอัตโนมัติ (Auto Cleanup)

คอนเทนเนอร์โฆษณาที่ถูกลบออกจาก DOM จะถูกล้างข้อมูลโดยอัตโนมัติ:

// MutationObserver를 통한 자동 감지 및 정리
// 개발자가 수동으로 destroy()를 호출할 필요 없음
const slotId = AdStage.ads.banner('banner-ad');
 
// DOM에서 컨테이너가 제거되면 자동으로 슬롯도 정리됨
document.getElementById('banner-ad').remove();

ตรรกะการลองใหม่

ลองใหม่โดยอัตโนมัติเมื่อหาคอนเทนเนอร์ไม่พบ:

// 컨테이너가 아직 존재하지 않아도 점진적으로 재시도
const slotId = AdStage.ads.banner('not-yet-exists', {
  width: '100%',
  height: 250
});
 
// 나중에 DOM에 컨테이너가 추가되면 자동으로 광고 표시
setTimeout(() => {
  const div = document.createElement('div');
  div.id = 'not-yet-exists';
  document.body.appendChild(div);
}, 1000);

🎨 คู่มือการจัดสไตล์

คลาส CSS

คลาส CSS ที่ SDK เพิ่มให้โดยอัตโนมัติ:

/* 광고 컨테이너 */
.adstage-ad {
  position: relative;
  overflow: hidden;
}
 
/* 로딩 상태 */
.adstage-loading {
  opacity: 0.7;
}
 
/* 로딩 완료 */
.adstage-loaded {
  opacity: 1;
  transition: opacity 0.3s ease;
}
 
/* 오류 상태 */
.adstage-error {
  border: 1px solid #ff0000;
}

การออกแบบแบบ Responsive

การตั้งค่าโฆษณาให้เหมาะกับขนาดหน้าจอที่หลากหลาย:

AdStage.ads.banner('responsive-banner', {
  width: '100%',
  height: window.innerWidth > 768 ? 250 : 100
});

ตัวอย่างการใช้งานจริง

SDK สามารถใช้งานได้ในสภาพแวดล้อม JavaScript, React และ Next.js เรียนรู้วิธีการนำไปใช้ผ่านตัวอย่างจริง

JavaScript (วิธี UMD)

วิธีโหลดเวอร์ชัน UMD โดยตรงในไฟล์ HTML แล้วนำมาใช้งาน

<!DOCTYPE html>
<html>
<head>
  <title>AdStage SDK Example</title>
</head>
<body>
  <!-- 광고 컨테이너 -->
  <div id="banner-ad">배너 광고가 로드 중입니다...</div>
  <div id="text-ad">텍스트 광고가 로드 중입니다...</div>
  <div id="video-ad">비디오 광고가 로드 중입니다...</div>
 
  <!-- SDK 로드 -->
  <script src="https://unpkg.com/@adstage/web-sdk/dist/index.umd.js"></script>
  
  <script>
    // SDK 초기화
    AdStage.init({
      apiKey: 'your-api-key',
      debug: true
    });
    
    // 광고 생성
    const bannerSlotId = AdStage.ads.banner('banner-ad', {
      width: '100%',
      height: 250,
      onClick: (adData) => console.log('배너 클릭:', adData)
    });
    
    const textSlotId = AdStage.ads.text('text-ad', {
      maxLines: 3,
      onClick: (adData) => console.log('텍스트 클릭:', adData)
    });
    
    const videoSlotId = AdStage.ads.video('video-ad', {
      width: 640,
      height: 360,
      autoplay: true,
      muted: true,
      controls: false,
      onClick: (adData) => console.log('비디오 클릭:', adData)
    });
  </script>
</body>
</html>

React (วิธีพื้นฐาน)

วิธีใช้ SDK โดยตรงใน React

import React, { useEffect, useRef } from 'react';
import { AdStage } from '@adstage/web-sdk';
 
function AdComponent() {
  const bannerRef = useRef(null);
  const textRef = useRef(null);
  const videoRef = useRef(null);
  const slotIdsRef = useRef({});
 
  useEffect(() => {
    // SDK 초기화
    AdStage.init({
      apiKey: 'your-api-key',
      debug: true
    });
 
    // 광고 생성
    if (bannerRef.current) {
      slotIdsRef.current.banner = AdStage.ads.banner(bannerRef.current, {
        width: '100%',
        height: 250,
        onClick: (adData) => console.log('배너 클릭:', adData)
      });
    }
 
    if (textRef.current) {
      slotIdsRef.current.text = AdStage.ads.text(textRef.current, {
        maxLines: 3,
        onClick: (adData) => console.log('텍스트 클릭:', adData)
      });
    }
 
    if (videoRef.current) {
      slotIdsRef.current.video = AdStage.ads.video(videoRef.current, {
        width: 640,
        height: 360,
        autoplay: true,
        muted: true,
        controls: false,
        onClick: (adData) => console.log('비디오 클릭:', adData)
      });
    }
 
    // 정리 함수
    return () => {
      Object.values(slotIdsRef.current).forEach(slotId => {
        if (slotId) AdStage.ads.destroy(slotId);
      });
    };
  }, []);
 
  return (
    <div>
      <h1>AdStage SDK - React 예제</h1>
      
      <div style={{ margin: '20px 0' }}>
        <h2>Banner Advertisement</h2>
        <div 
          ref={bannerRef}
          style={{ 
            minHeight: '100px',
            border: '2px dashed #ccc',
            borderRadius: '4px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center'
          }}
        >
          배너 광고가 로드 중입니다...
        </div>
      </div>
 
      <div style={{ margin: '20px 0' }}>
        <h2>Text Advertisement</h2>
        <div ref={textRef}>
          텍스트 광고가 로드 중입니다...
        </div>
      </div>
 
      <div style={{ margin: '20px 0' }}>
        <h2>Video Advertisement</h2>
        <div ref={videoRef}>
          비디오 광고가 로드 중입니다...
        </div>
      </div>
    </div>
  );
}
 
export default AdComponent;

Next.js (วิธี Provider)

วิธีที่แนะนำโดยใช้ AdStageProvider ใน Next.js

1. ตั้งค่า Provider ใน _app.js

// pages/_app.js
import { AdStageProvider } from '@adstage/web-sdk';
 
export default function App({ Component, pageProps }) {
  return (
    <AdStageProvider
      config={{
        apiKey: 'your-api-key',
        debug: true
      }}
    >
      <Component {...pageProps} />
    </AdStageProvider>
  );
}

2. ใช้ฮุก useAdStageInstance ในหน้าเพจ

// pages/index.js
import { useEffect, useRef } from 'react';
import { useAdStageInstance } from '@adstage/web-sdk';
 
export default function Home() {
  const adstage = useAdStageInstance();
  
  const bannerRef = useRef(null);
  const textRef = useRef(null);
  const videoRef = useRef(null);
  const slotIdsRef = useRef({});
 
  useEffect(() => {
    if (adstage) {
      loadAds();
    }
    
    return () => {
      // 컴포넌트 언마운트 시 정리
      Object.values(slotIdsRef.current).forEach(slotId => {
        if (slotId) adstage?.ads?.destroy(slotId);
      });
    };
  }, [adstage]);
 
  const loadAds = () => {
    // 배너 광고
    if (bannerRef.current) {
      slotIdsRef.current.banner = adstage.ads.banner(bannerRef.current, {
        width: '100%',
        height: 250,
        onClick: (adData) => console.log('배너 클릭:', adData)
      });
    }
    
    // 텍스트 광고
    if (textRef.current) {
      slotIdsRef.current.text = adstage.ads.text(textRef.current, {
        maxLines: 3,
        onClick: (adData) => console.log('텍스트 클릭:', adData)
      });
    }
    
    // 비디오 광고
    if (videoRef.current) {
      slotIdsRef.current.video = adstage.ads.video(videoRef.current, {
        width: 640,
        height: 360,
        autoplay: true,
        muted: true,
        controls: false,
        onClick: (adData) => console.log('비디오 클릭:', adData)
      });
    }
  };
 
  return (
    <div style={{ fontFamily: 'Arial, sans-serif', margin: '20px' }}>
      <h1>AdStage SDK - Next.js 광고 예제</h1>
      
      {/* 배너 광고 */}
      <div style={{ margin: '40px 0', padding: '20px', border: '1px solid #ddd' }}>
        <h2>Banner Advertisement</h2>
        <div 
          ref={bannerRef}
          style={{ 
            minHeight: '100px',
            border: '2px dashed #ccc',
            borderRadius: '4px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center'
          }}
        >
          배너 광고가 로드 중입니다...
        </div>
      </div>
      
      {/* 텍스트 광고 */}
      <div style={{ margin: '40px 0', padding: '20px', border: '1px solid #ddd' }}>
        <h2>Text Advertisement</h2>
        <div 
          ref={textRef}
          style={{ 
            backgroundColor: 'rgba(34, 197, 94, 0.1)',
            borderRadius: '12px',
            border: '1px solid rgba(34, 197, 94, 0.2)',
            padding: '16px',
            minHeight: '80px'
          }}
        >
          텍스트 광고가 로드 중입니다...
        </div>
      </div>
      
      {/* 비디오 광고 */}
      <div style={{ margin: '40px 0', padding: '20px', border: '1px solid #ddd' }}>
        <h2>Video Advertisement</h2>
        <div 
          ref={videoRef}
          style={{ 
            minHeight: '100px',
            border: '2px dashed #ccc',
            borderRadius: '4px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center'
          }}
        >
          비디오 광고가 로드 중입니다...
        </div>
      </div>
    </div>
  );
}

ภาพรวมระบบโฆษณา

🎯 ประเภทโฆษณาที่รองรับ

โฆษณาแบนเนอร์ (Banner Ads)

โฆษณาข้อความ (Text Ads)

โฆษณาวิดีโอ (Video Ads)

🔄 ขั้นตอนการใช้งานเบื้องต้น

📚 ขั้นตอนถัดไป

🎯 ประเภทโฆษณาที่รองรับ

โฆษณาแบนเนอร์ (Banner Ads)

โฆษณาข้อความ (Text Ads)

โฆษณาวิดีโอ (Video Ads)

🔄 กระบวนการแสดงโฆษณา

⚙️ ตัวเลือกการตั้งค่า

ตัวเลือกทั่วไป

ตัวเลือกเฉพาะของโฆษณาแบนเนอร์

ตัวเลือกเฉพาะของโฆษณาข้อความ

ตัวเลือกเฉพาะของโฆษณาวิดีโอ

ตัวเลือกตัวควบคุมแบบกำหนดเองของวิดีโอ

ตัวอย่าง: การตั้งค่าขั้นสูง

📊 การปรับประสิทธิภาพ

การโหลดในเบื้องหลัง

การล้างข้อมูลอัตโนมัติ (Auto Cleanup)

ตรรกะการลองใหม่

🎨 คู่มือการจัดสไตล์

คลาส CSS

การออกแบบแบบ Responsive

ตัวอย่างการใช้งานจริง

JavaScript (วิธี UMD)

React (วิธีพื้นฐาน)

Next.js (วิธี Provider)

1. ตั้งค่า Provider ใน _app.js

2. ใช้ฮุก useAdStageInstance ในหน้าเพจ

สารบัญ