메인 콘텐츠로 건너뛰기

​
구현 방법

배너 광고는 두 가지 방식으로 구현할 수 있습니다.
방식설명추천
Data AttributesHTML 속성만으로 간단하게 구현빠른 구현
renderAd광고 로드 타이밍을 직접 제어세밀한 제어 필요 시
개발 환경에서는 테스트 유닛 ID를 사용하세요: PUBLIC_TEST_UNIT_ID_320_100

​
1. Data Attributes 방식

가장 간단한 방식으로, data-adrop-unit 속성만 추가하면 SDK가 자동으로 광고를 로드합니다. 
function BannerAd() {
  return (
    <div
      data-adrop-unit="YOUR_UNIT_ID"
      data-adrop-context-id="YOUR_CONTEXT_ID"
      data-adrop-theme="light"
    />
  );
}

​
Data Attributes

​
data-adrop-unit
string
required
애드컨트롤 콘솔에서 생성한 유닛 ID
​
data-adrop-context-id
string
문맥 타겟팅용 Context ID
​
data-adrop-theme
string
default:"light"
테마 설정 (light 또는 dark) - 다크모드 설정 참고

​
광고 재요청

React의 key를 변경하여 컴포넌트를 리마운트하면 광고가 다시 요청됩니다. 
function App() {
  const [adKey, setAdKey] = useState(0);

  const reloadAd = () => {
    setAdKey(prev => prev + 1);
  };

  return (
    <>
      <div key={adKey} data-adrop-unit="YOUR_UNIT_ID" />
      <button onClick={reloadAd}>광고 새로고침</button>
    </>
  );
}

​
2. renderAd 방식

광고 로드 타이밍을 직접 제어하고 싶을 때 사용합니다. 
import { useEffect, useRef } from 'react';
import Adrop from '@adrop/ads-web-sdk';

function BannerAd() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const adrop = Adrop.instance();

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: 'YOUR_UNIT_ID',
        contextId: 'YOUR_CONTEXT_ID',
        theme: 'light'
      });
    }

  }, []);

  return <div ref={containerRef} />;
}

​
renderAd 옵션

​
unit
string
required
애드컨트롤 콘솔에서 생성한 유닛 ID
​
uid
string
사용자 식별자 (SDK 설정 값을 개별 지면에서 오버라이드할 때 사용)
​
contextId
string
문맥 타겟팅용 Context ID
​
theme
string
default:"light"
테마 설정 (light 또는 dark) - 다크모드 설정 참고

​
광고 재요청

renderAd()를 다시 호출하면 광고가 재요청됩니다. Data Attributes로 생성한 지면에도 사용할 수 있습니다. 
function BannerAd() {
  const containerRef = useRef<HTMLDivElement>(null);

  const reloadAd = () => {
    const adrop = Adrop.instance();
    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: 'YOUR_UNIT_ID'
      });
    }
  };

  return (
    <>
      <div ref={containerRef} />
      <button onClick={reloadAd}>광고 새로고침</button>
    </>
  );
}
Data Attributes로 생성한 지면에 renderAd()를 호출할 경우, data attributes에 존재하지 않는 항목이나 수정하고 싶은 항목만 전달하면 됩니다.

​
광고 제거

clear()를 호출하여 컨테이너에서 광고를 제거할 수 있습니다. 
const adrop = Adrop.instance();
adrop.clear(containerRef.current);

​
광고 크기

컨테이너를 유닛에 등록한 사이즈에 맞춰 설정하세요. 
<div
  data-adrop-unit="YOUR_UNIT_ID"
  style={{ width: 320, height: 100 }}
/>
구분크기 설정정렬
직광고반응형 지원, 높이 필수가로/세로 가운데
백필 광고초기 너비 맞춤, 높이 필수가로 가운데

​
이벤트 처리

광고 상태 변화를 감지하여 적절한 UI 처리를 할 수 있습니다. 
import { useEffect, useRef } from 'react';
import Adrop from '@adrop/ads-web-sdk';

function BannerAd({ unitId }: { unitId: string }) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const adrop = Adrop.instance();

    // 광고 수신 성공
    const handleReceived = (unit: string, adData: any) => {
      console.log('광고 수신:', unit);
    };

    // 송출 가능한 직광고 없음
    const handleNoFill = (unit: string) => {
      console.warn('광고 없음:', unit);
    };

    // 요청 실패
    const handleFailed = (unit: string) => {
      console.error('광고 실패:', unit);
    };

    // 노출
    const handleImpression = (unit: string) => {
      console.log('광고 노출:', unit);
    };

    // 클릭
    const handleClicked = (unit: string) => {
      console.log('광고 클릭:', unit);
    };

    // 백필 광고 없음
    const handleBackfillNoFill = (unit: string) => {
      console.warn('백필 광고 없음:', unit);
    };

    // 특정 유닛만 필터링
    const filter = { unit: unitId };

    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);

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, { unit: unitId });
    }

    return () => {
      adrop.off(Adrop.Events.AD_RECEIVED, handleReceived);
      adrop.off(Adrop.Events.AD_NO_FILL, handleNoFill);
      adrop.off(Adrop.Events.AD_FAILED, handleFailed);
      adrop.off(Adrop.Events.AD_IMPRESSION, handleImpression);
      adrop.off(Adrop.Events.AD_CLICKED, handleClicked);
      adrop.off(Adrop.Events.AD_BACKFILL_NO_FILL, handleBackfillNoFill);
    };
  }, [unitId]);

  return <div ref={containerRef} />;
}

​
지원 이벤트

이벤트상수설명
광고 수신AD_RECEIVED광고 요청 성공
광고 없음AD_NO_FILL송출 가능한 직광고 없음
요청 실패AD_FAILED광고 요청 실패
노출AD_IMPRESSION광고 노출 기록됨
클릭AD_CLICKED사용자가 광고 클릭
백필 없음AD_BACKFILL_NO_FILL백필 광고 없음
컴포넌트 언마운트 시 반드시 off()로 이벤트 리스너를 해제하세요.

​
AdData

이벤트 핸들러에서 전달받는 광고 데이터입니다. 자세한 필드 정보는 레퍼런스 > AdData를 참고하세요.

​
전체 예제

​
BannerAd.tsx

import { useEffect, useRef } from 'react';
import Adrop from '@adrop/ads-web-sdk';

interface BannerAdProps {
  unitId: string;
  contextId?: string;
  theme?: 'light' | 'dark';
  onReceived?: (adData: any) => void;
  onFailed?: () => void;
  onClicked?: () => void;
}

function BannerAd({
  unitId,
  contextId,
  theme = 'light',
  onReceived,
  onFailed,
  onClicked
}: BannerAdProps) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const adrop = Adrop.instance();
    const filter = { unit: unitId };

    const handleReceived = (_: string, adData: any) => onReceived?.(adData);
    const handleFailed = () => onFailed?.();
    const handleClicked = () => onClicked?.();

    adrop.on(Adrop.Events.AD_RECEIVED, handleReceived, filter);
    adrop.on(Adrop.Events.AD_FAILED, handleFailed, filter);
    adrop.on(Adrop.Events.AD_CLICKED, handleClicked, filter);

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: unitId,
        contextId,
        theme
      });
    }

    return () => {
      adrop.off(Adrop.Events.AD_RECEIVED, handleReceived);
      adrop.off(Adrop.Events.AD_FAILED, handleFailed);
      adrop.off(Adrop.Events.AD_CLICKED, handleClicked);
    };
  }, [unitId, contextId, theme]);

  return <div ref={containerRef} className="banner-ad-container" />;
}

export default BannerAd;

​
사용 예시

import BannerAd from './components/BannerAd';

function App() {
  return (
    <div>
      <header>
        <BannerAd
          unitId="HEADER_BANNER_UNIT_ID"
          onClicked={() => console.log('헤더 배너 클릭')}
        />
      </header>

      <main>
        <h1>콘텐츠</h1>
      </main>

      <footer>
        <BannerAd
          unitId="FOOTER_BANNER_UNIT_ID"
          theme="dark"
        />
      </footer>
    </div>
  );
}