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ฟังก์ชัน callback ที่จะทำงานเมื่อคลิก

ตัวเลือกขั้นสูง

ตัวเลือกชนิดค่าเริ่มต้นคำอธิบาย
loopbooleantrueจะเล่นซ้ำหรือไม่
playsinlinebooleantrueเล่นแบบ inline (มือถือ)
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    // 전체화면 버튼 숨김
  }
});

วิดีโอแบบ Responsive

วิธีการปรับขนาดวิดีโอตามขนาดหน้าจอ

// 미디어 쿼리를 활용한 반응형 구현
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. การโหลดเบื้องหลัง

โฆษณาจะถูกโหลดในเบื้องหลัง ดังนั้นคุณจึงรับ slot 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

คุณสามารถจัดสไตล์ได้โดยใช้คลาส CSS ที่ SDK เพิ่มให้โดยอัตโนมัติ

/* 광고 컨테이너 기본 스타일 */
.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;
}

การตรวจสอบสถานะ slot

// 모든 슬롯 확인
const allSlots = AdStage.ads.getAllSlots();
console.log('전체 광고 슬롯:', allSlots);
 
// 특정 슬롯 확인
const slot = AdStage.ads.getSlotById(slotId);
console.log('슬롯 정보:', slot);

📚 เอกสารที่เกี่ยวข้อง

สารบัญ