네이티브 광고 - Ad Control Help Center

구현 방법

네이티브 광고는 사이트의 디자인에 맞게 커스텀 UI로 광고를 표시할 수 있습니다.

방식	설명	추천
기본 템플릿	SDK 제공 템플릿 사용	빠른 구현
커스텀 UI	직접 UI 구성	디자인 맞춤 필요 시

개발 환경에서는 테스트 유닛 ID를 사용하세요: PUBLIC_TEST_UNIT_ID_NATIVE

기본 템플릿

배너 광고와 동일한 방식으로 기본 템플릿을 사용할 수 있습니다. SDK가 제공하는 템플릿에 이미지, 텍스트가 자동으로 렌더링됩니다.

function NativeAd() {
  return <div data-adrop-unit="YOUR_NATIVE_UNIT_ID" />;
}

기본 템플릿은 광고주 프로필 섹션을 지원하지 않습니다. 광고주 프로필을 표시하려면 커스텀 UI를 사용하세요.

커스텀 UI

1. Data Attributes 방식

data-adrop-render="custom" 속성을 추가하고, 내부 요소에 data-adrop-native 속성으로 필드를 바인딩합니다.

function CustomNativeAd() {
  return (
    <div
      data-adrop-unit="YOUR_NATIVE_UNIT_ID"
      data-adrop-render="custom"
      data-adrop-entire-click="true"
      data-adrop-custom-click="true"  // 커스텀 클릭 처리 활성화
      className="native-ad"
    >
      {/* 광고주 프로필 */}
      <div className="ad-profile">
        <img data-adrop-native="profile.displayLogo" alt="광고주" />
        <span data-adrop-native="profile.displayName"></span>
      </div>

      {/* 광고 콘텐츠 */}
      <h3 data-adrop-native="headline"></h3>
      <img data-adrop-native="asset" alt="광고" />
      <p data-adrop-native="body"></p>

      {/* 추가 텍스트 항목 */}
      <span data-adrop-native="extra.price"></span>

      {/* CTA 버튼 */}
      <button data-adrop-native="callToAction"></button>
    </div>
  );
}

Data Attributes

data-adrop-unit

string

필수

애드컨트롤 콘솔에서 생성한 유닛 ID

data-adrop-render

string

필수

커스텀 UI 사용 시 custom으로 설정

data-adrop-context-id

string

문맥 타겟팅용 Context ID

data-adrop-theme

string

기본값:"light"

테마 설정 (light 또는 dark)

data-adrop-entire-click

boolean

기본값:false

전체 영역 클릭 활성화

false: 텍스트/이미지만 클릭 가능, 광고주 프로필 클릭 시 프로필 링크로 이동
true: 컨테이너 전체 클릭 가능, 모든 클릭이 광고 목적지로 이동

data-adrop-custom-click

boolean

기본값:false

커스텀 클릭 처리 활성화 - true로 설정하면 SDK가 자동으로 목적지 URL로 이동하지 않고, adClicked 이벤트만 발생시킵니다. 개발자가 클릭 동작을 직접 구현할 수 있습니다.

data-adrop-ad-id

string

광고 식별자 — 내 기기에서 보기 기능으로 등록한 테스트 기기에서 소재를 미리 확인할 때 필수입니다. 운영 환경에 하드코딩하지 마세요.

2. renderAd 방식

광고 로드 타이밍을 직접 제어하고 싶을 때 사용합니다.

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

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

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

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: 'YOUR_NATIVE_UNIT_ID',
        contextId: 'YOUR_CONTEXT_ID',
        theme: 'light',
        trackMode: 1,        // 커스텀 UI 사용 시 필수
        isEntireClick: true, // 전체 영역 클릭 활성화
        useCustomClick: true // 커스텀 클릭 처리 활성화
      });
    }

  }, []);

  return (
    <div ref={containerRef} className="native-ad">
      <div className="ad-profile">
        <img data-adrop-native="profile.displayLogo" alt="광고주" />
        <span data-adrop-native="profile.displayName"></span>
      </div>
      <h3 data-adrop-native="headline"></h3>
      <img data-adrop-native="asset" alt="광고" />
      <p data-adrop-native="body"></p>
      <button data-adrop-native="callToAction"></button>
    </div>
  );
}

renderAd 옵션

unit

string

필수

애드컨트롤 콘솔에서 생성한 유닛 ID

uid

string

사용자 식별자 (SDK 설정 값을 개별 지면에서 오버라이드할 때 사용)

contextId

string

문맥 타겟팅용 Context ID

trackMode

number

필수

커스텀 UI 사용 시 1로 설정

isEntireClick

boolean

기본값:false

전체 영역 클릭 활성화

theme

string

기본값:"light"

테마 설정 (light 또는 dark)

useCustomClick

boolean

기본값:false

adId

string

광고 식별자 — 내 기기에서 보기 기능으로 등록한 테스트 기기에서 소재를 미리 확인할 때 필수입니다. 운영 환경에 하드코딩하지 마세요.

필드 바인딩

data-adrop-native 속성으로 광고 데이터를 UI 요소에 바인딩합니다.

필드	설명	요소 타입
`profile.displayLogo`	광고주 로고 URL	`<img>`
`profile.displayName`	광고주 이름	텍스트
`headline`	광고 제목	텍스트
`body`	광고 설명	텍스트
`asset`	메인 이미지 URL	`<img>`
`callToAction`	CTA 버튼 텍스트	텍스트
`extra.{key}`	추가 텍스트 항목	텍스트

extra.{key}는 애드컨트롤 콘솔에서 설정한 추가 텍스트 항목의 ID입니다. 필수로 설정하지 않았다면 비어있을 수 있습니다.

광고주 프로필(profile.displayLogo, profile.displayName)을 표시하려면 애드컨트롤 콘솔에서 해당 광고 유닛의 광고주 프로필 표시를 활성화해야 합니다.

광고 크기

커스텀 UI의 크기는 자유롭게 설정할 수 있습니다.

구분	크기 설정	정렬
직광고	반응형 지원	가로/세로 가운데
백필 광고	초기 너비 맞춤, 높이 필수	가로 가운데

백필 광고는 컨테이너 크기에 맞는 소재를 요청합니다. 적절한 크기를 지정하세요.

requestAd로 데이터만 가져오기

UI를 완전히 직접 제어하고 싶다면 requestAd로 광고 데이터만 가져올 수 있습니다.

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

function NativeAd() {
  const [adData, setAdData] = useState<AdData | null>(null);

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

      const response = await adrop.requestAd({
        unit: 'YOUR_NATIVE_UNIT_ID',
        trackMode: 1
      });

      if (response.code === 0 && response.result) {
        setAdData(response.result);
      }
    }

    loadAd();
  }, []);

  if (!adData) return null;

  return (
    <div className="native-ad">
      <div className="ad-header">
        {adData.profile?.displayLogo && (
          <img src={adData.profile.displayLogo} alt="광고주" />
        )}
        <span>{adData.profile?.displayName}</span>
      </div>
      <h3>{adData.headline}</h3>
      {adData.asset && <img src={adData.asset} alt="광고" />}
      <p>{adData.body}</p>
      <a href={adData.destinationURL} target="_blank" rel="noopener noreferrer">
        {adData.callToAction}
      </a>
    </div>
  );
}

requestAd 사용 시 노출/클릭 추적을 직접 구현해야 합니다. 또한 이 방식에서는 백필 광고가 지원되지 않습니다. 특별한 경우가 아니라면 renderAd를 권장합니다.

AdropAdResponse

requestAd()의 반환값입니다.

필드	타입	설명
`code`	`number`	응답 코드 (0: 성공, 4000-4003: 에러)
`msg`	`string`	응답 메시지
`result`	`AdData`	광고 데이터 (성공 시에만 존재)

AdData

광고 데이터 객체입니다. 이벤트 핸들러에서도 동일한 구조로 전달됩니다. 자세한 내용은 레퍼런스 > AdData를 참고하세요.

필드	타입	설명
`format`	`string`	광고 포맷 (`banner`, `nativeAd`, `backfill`)
`unit`	`string`	유닛 ID
`headline`	`string`	광고 제목
`body`	`string`	광고 설명
`callToAction`	`string`	CTA 버튼 텍스트
`asset`	`string`	메인 이미지 URL
`destinationURL`	`string`	클릭 시 이동할 URL
`profile.displayLogo`	`string`	광고주 로고 URL
`profile.displayName`	`string`	광고주 이름
`profile.link`	`string`	광고주 프로필 링크
`extra`	`Record<string, string>`	추가 텍스트 항목

커스텀 클릭 처리

useCustomClick이 활성화되면 SDK가 자동으로 목적지 URL로 이동하지 않습니다. 대신 클릭 이벤트를 처리하여 사용자 정의 동작을 구현할 수 있습니다.

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

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

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

    // 커스텀 동작으로 광고 클릭 처리
    const handleClicked = (unit: string, adData: any) => {
      console.log('광고 클릭:', unit);
      console.log('목적지 URL:', adData.destinationURL);
      
      // 커스텀 클릭 동작 구현
      // 예시: SPA 내 네비게이션, 모달 표시, 분석 추적 등
      if (adData.destinationURL) {
        // 커스텀 네비게이션 로직
        window.location.href = adData.destinationURL;
      }
    };

    adrop.on(Adrop.Events.AD_CLICKED, handleClicked, filter);

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: unitId,
        trackMode: 1,
        isEntireClick: true,
        useCustomClick: true
      });
    }

    return () => {
      adrop.off(Adrop.Events.AD_CLICKED, handleClicked);
    };
  }, [unitId]);

  return (
    <div ref={containerRef} className="native-ad">
      <div className="ad-profile">
        <img data-adrop-native="profile.displayLogo" alt="광고주" />
        <span data-adrop-native="profile.displayName"></span>
      </div>
      <h3 data-adrop-native="headline"></h3>
      <img data-adrop-native="asset" alt="광고" />
      <p data-adrop-native="body"></p>
      <button data-adrop-native="callToAction"></button>
    </div>
  );
}

커스텀 클릭 처리가 활성화되면 사용자가 광고를 클릭할 때 어떤 일이 일어날지 완전히 제어할 수 있습니다. destinationURL은 adClicked 이벤트 데이터에 포함되어 제공됩니다.

이벤트 처리

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

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

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

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

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

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

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

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

    // 동영상 재생 시작
    const handleVideoStart = (unit: string, adData: any) => {
      console.log('동영상 시작:', unit);
    };

    // 동영상 재생 완료
    const handleVideoEnd = (unit: string, adData: any) => {
      console.log('동영상 완료:', unit);
    };

    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_VIDEO_START, handleVideoStart, filter);
    adrop.on(Adrop.Events.AD_VIDEO_END, handleVideoEnd, filter);

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: unitId,
        trackMode: 1,
        isEntireClick: true
      });
    }

    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_VIDEO_START, handleVideoStart);
      adrop.off(Adrop.Events.AD_VIDEO_END, handleVideoEnd);
    };
  }, [unitId]);

  return (
    <div ref={containerRef} className="native-ad">
      <div className="ad-profile">
        <img data-adrop-native="profile.displayLogo" alt="광고주" />
        <span data-adrop-native="profile.displayName"></span>
      </div>
      <h3 data-adrop-native="headline"></h3>
      <img data-adrop-native="asset" alt="광고" />
      <p data-adrop-native="body"></p>
      <button data-adrop-native="callToAction"></button>
    </div>
  );
}

지원 이벤트

이벤트	상수	설명
광고 수신	`AD_RECEIVED`	광고 요청 성공
광고 없음	`AD_NO_FILL`	송출 가능한 직광고 없음
요청 실패	`AD_FAILED`	광고 요청 실패
노출	`AD_IMPRESSION`	광고 노출 기록됨
클릭	`AD_CLICKED`	사용자가 광고 클릭
백필 없음	`AD_BACKFILL_NO_FILL`	백필 광고 없음
동영상 시작	`AD_VIDEO_START`	동영상 광고 재생 시작
동영상 완료	`AD_VIDEO_END`	동영상 광고 재생 완료

백필 광고

백필 광고가 활성화되면 직광고가 없을 때 자동으로 백필 광고를 요청합니다. adData.format으로 광고 타입을 구분할 수 있습니다.

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

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

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

    // 광고 수신 (직광고 또는 백필)
    const handleReceived = (unit: string, adData: any) => {
      if (adData.format === 'backfill') {
        console.log('백필 광고가 로드되었습니다');
      } else {
        console.log('직광고가 로드되었습니다'); // 'nativeAd'
      }
    };

    // 직광고 없음 (백필 요청 시작)
    const handleNoFill = (unit: string) => {
      console.log('직광고 없음, 백필 광고 요청 중...');
    };

    // 백필 광고도 없음
    const handleBackfillNoFill = (unit: string) => {
      console.warn('백필 광고도 없습니다');
      // 광고 영역 숨기기 등 처리
    };

    adrop.on(Adrop.Events.AD_RECEIVED, handleReceived, filter);
    adrop.on(Adrop.Events.AD_NO_FILL, handleNoFill, 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_BACKFILL_NO_FILL, handleBackfillNoFill);
    };
  }, [unitId]);

  return (
    <div ref={containerRef}>
      <h3 data-adrop-native="headline"></h3>
      <img data-adrop-native="asset" alt="광고" />
      <p data-adrop-native="body"></p>
      <button data-adrop-native="callToAction"></button>
    </div>
  );
}

개발 환경 테스트: 앱에 연결된 광고 유닛 중 하나라도 수익화 중이면 localhost에서도 백필 광고 요청이 가능합니다. 승인되지 않은 도메인에서는 AD_BACKFILL_NO_FILL 이벤트가 발생합니다.

​구현 방법

​기본 템플릿

​커스텀 UI

​1. Data Attributes 방식

​Data Attributes

​2. renderAd 방식

​renderAd 옵션

​필드 바인딩

​광고 크기

​requestAd로 데이터만 가져오기

​AdropAdResponse

​AdData

​커스텀 클릭 처리

​이벤트 처리

​지원 이벤트

​백필 광고

구현 방법

기본 템플릿

커스텀 UI

1. Data Attributes 방식

Data Attributes

2. renderAd 방식

renderAd 옵션

필드 바인딩

광고 크기

requestAd로 데이터만 가져오기

AdropAdResponse

AdData

커스텀 클릭 처리

이벤트 처리

지원 이벤트

백필 광고