구현 방법
배너 광고는 HTML 속성만으로 간단하게 구현할 수 있습니다. 별도의 함수 호출 없이 광고 지면이 렌더링될 때 자동으로 광고가 요청됩니다.
개발 환경에서는 테스트 유닛 ID를 사용하세요: PUBLIC_TEST_UNIT_ID_320_100
Data Attributes 방식
data-adrop-unit 속성만 추가하면 SDK가 자동으로 광고를 로드합니다.
<div
data-adrop-unit="YOUR_UNIT_ID"
data-adrop-context-id="YOUR_CONTEXT_ID"
data-adrop-theme="light"
data-adrop-custom-click="true">
</div>
Data Attributes
커스텀 클릭 처리 활성화 - true로 설정하면 SDK가 자동으로 목적지 URL로 이동하지 않고, adClicked 이벤트만 발생시킵니다. 개발자가 클릭 동작을 직접 구현할 수 있습니다.
백필 광고 렌더링 모드 (responsive 또는 fixed). 자세한 내용은 백필 렌더링 모드 가이드를 참고하세요. (SDK 1.2.3+) 광고 재요청
광고 지면 DOM을 새로 생성하여 기존 DOM을 교체하면 광고가 다시 요청됩니다.
const container = document.getElementById('ad-wrapper');
const newAd = document.createElement('div');
newAd.setAttribute('data-adrop-unit', 'YOUR_UNIT_ID');
Adrop.instance().clear(container);
container.appendChild(newAd);
renderAd 방식
광고 로드 타이밍을 직접 제어하고 싶을 때 사용합니다.
<div id="ad-container"></div>
<script>
const container = document.getElementById('ad-container');
const adrop = Adrop.instance();
adrop.renderAd(container, {
unit: 'YOUR_UNIT_ID',
contextId: 'YOUR_CONTEXT_ID',
theme: 'light',
useCustomClick: true // 커스텀 클릭 처리 활성화
});
</script>
renderAd 옵션
사용자 식별자 (SDK 설정 값을 개별 지면에서 오버라이드할 때 사용)
커스텀 클릭 처리 활성화 - true로 설정하면 SDK가 자동으로 목적지 URL로 이동하지 않고, adClicked 이벤트만 발생시킵니다. 개발자가 클릭 동작을 직접 구현할 수 있습니다.
backfillMode
'responsive' | 'fixed'
기본값:"responsive"
백필 광고 렌더링 모드. 자세한 내용은 백필 렌더링 모드 가이드를 참고하세요. (SDK 1.2.3+) 광고 재요청
renderAd()를 다시 호출하면 광고가 재요청됩니다.
const container = document.getElementById('ad-container');
Adrop.instance().renderAd(container, {
unit: 'YOUR_UNIT_ID'
});
광고 제거
clear()를 호출하여 컨테이너에서 광고를 제거할 수 있습니다.
const container = document.getElementById('ad-container');
Adrop.instance().clear(container);
광고 크기
컨테이너를 유닛에 등록한 사이즈에 맞춰 설정하세요.
<div
data-adrop-unit="YOUR_UNIT_ID"
style="width: 320px; height: 100px;">
</div>
| 구분 | 크기 설정 | 정렬 |
|---|
| 직광고 | 반응형 지원, 높이 필수 | 가로/세로 가운데 |
| 백필 광고 | 컨테이너 폭에 맞춰 자동 매칭 (responsive) 또는 컨테이너 높이에 맞춤 (fixed) | 가로 가운데 |
백필 광고의 컨테이너 크기 작성 패턴과 렌더링 모드 선택 기준은 백필 렌더링 모드 가이드를 참고하세요.
이벤트 처리
광고 상태 변화를 감지하여 적절한 UI 처리를 할 수 있습니다.
<script>
const adrop = Adrop.instance();
// 광고 수신 성공
function handleReceived(unit, adData) {
console.log('광고 수신:', unit);
}
// 송출 가능한 직광고 없음
function handleNoFill(unit) {
console.warn('광고 없음:', unit);
}
// 요청 실패
function handleFailed(unit) {
console.error('광고 실패:', unit);
}
// 노출
function handleImpression(unit, adData) {
console.log('광고 노출:', unit);
}
// 클릭
function handleClicked(unit, adData) {
console.log('광고 클릭:', unit);
}
// 백필 광고 없음
function handleBackfillNoFill(unit) {
console.warn('백필 광고 없음:', unit);
}
// 동영상 재생 시작
function handleVideoStart(unit, adData) {
console.log('동영상 시작:', unit);
}
// 동영상 재생 완료
function handleVideoEnd(unit, adData) {
console.log('동영상 완료:', unit);
}
// 특정 유닛만 필터링
const filter = { unit: 'YOUR_UNIT_ID' };
adrop.on(Adrop.Events.AD_RECEIVED, handleReceived, filter);
adrop.on(Adrop.Events.AD_NO_FILL, handleNoFill, filter);
adrop.on(Adrop.Events.AD_FAILED, handleFailed, filter);
adrop.on(Adrop.Events.AD_IMPRESSION, handleImpression, filter);
adrop.on(Adrop.Events.AD_CLICKED, handleClicked, filter);
adrop.on(Adrop.Events.AD_BACKFILL_NO_FILL, handleBackfillNoFill, filter);
adrop.on(Adrop.Events.AD_VIDEO_START, handleVideoStart, filter);
adrop.on(Adrop.Events.AD_VIDEO_END, handleVideoEnd, filter);
</script>
지원 이벤트
| 이벤트 | 상수 | 설명 |
|---|
| 광고 수신 | AD_RECEIVED | 광고 요청 성공 |
| 광고 없음 | AD_NO_FILL | 송출 가능한 직광고 없음 |
| 요청 실패 | AD_FAILED | 광고 요청 실패 |
| 노출 | AD_IMPRESSION | 광고 노출 기록됨 |
| 클릭 | AD_CLICKED | 사용자가 광고 클릭 |
| 백필 없음 | AD_BACKFILL_NO_FILL | 백필 광고 없음 |
| 동영상 시작 | AD_VIDEO_START | 동영상 광고 재생 시작 |
| 동영상 완료 | AD_VIDEO_END | 동영상 광고 재생 완료 |
이벤트 리스너 해제
더 이상 필요하지 않은 이벤트 리스너는 off()로 해제하세요.
adrop.off(Adrop.Events.AD_RECEIVED, handleReceived);
AdData
이벤트 핸들러에서 전달받는 광고 데이터입니다. 자세한 필드 정보는 레퍼런스 > AdData를 참고하세요.
커스텀 클릭 처리
useCustomClick이 활성화되면 SDK가 자동으로 목적지 URL로 이동하지 않습니다. 대신 클릭 이벤트를 처리하여 사용자 정의 동작을 구현할 수 있습니다.
<script>
const adrop = Adrop.instance();
// 커스텀 동작으로 광고 클릭 처리
function handleCustomClick(unit, adData) {
console.log('광고 클릭:', unit);
console.log('목적지 URL:', adData.destinationURL);
// 커스텀 클릭 동작 구현
// 예시: 확인 대화상자 표시, 분석 추적 등
const userConfirmed = confirm('광고주 페이지를 방문하시겠습니까?');
if (userConfirmed && adData.destinationURL) {
window.open(adData.destinationURL, '_blank');
}
}
// 클릭 핸들러 등록
adrop.on(Adrop.Events.AD_CLICKED, handleCustomClick);
// 커스텀 클릭 활성화하여 광고 렌더링
const container = document.getElementById('ad-container');
adrop.renderAd(container, {
unit: 'YOUR_UNIT_ID',
useCustomClick: true
});
</script>
커스텀 클릭 처리가 활성화되면 사용자가 광고를 클릭할 때 어떤 일이 일어날지 완전히 제어할 수 있습니다. destinationURL은 adClicked 이벤트 데이터에 포함되어 제공됩니다.
전체 예제
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>배너 광고 예제</title>
</head>
<body>
<header>
<!-- 헤더 배너 광고 -->
<div
data-adrop-unit="HEADER_BANNER_UNIT_ID"
style="width: 100%; height: 80px;">
</div>
</header>
<main>
<h1>콘텐츠</h1>
</main>
<footer>
<!-- 푸터 배너 광고 -->
<div
data-adrop-unit="FOOTER_BANNER_UNIT_ID"
data-adrop-theme="dark"
style="width: 320px; height: 100px;">
</div>
</footer>
<script src="https://cdn.jsdelivr.net/npm/@adrop/ads-web-sdk@latest/dist/adrop-ads.min.js"></script>
<script>
const adrop = Adrop.observe({
appId: 'YOUR_APP_ID',
debug: true
});
adrop.on(Adrop.Events.AD_CLICKED, function(unit, adData) {
console.log('광고 클릭:', unit);
});
</script>
</body>
</html>
