Skip to main content

구현 방법

네이티브 광고는 사이트의 디자인에 맞게 커스텀 UI로 광고를 표시할 수 있습니다.
개발 환경에서는 테스트 유닛 ID를 사용하세요: PUBLIC_TEST_UNIT_ID_NATIVE

기본 템플릿

배너 광고와 동일한 방식으로 기본 템플릿을 사용할 수 있습니다. SDK가 제공하는 템플릿에 이미지, 텍스트가 자동으로 렌더링됩니다.
기본 템플릿은 광고주 프로필 섹션을 지원하지 않습니다. 광고주 프로필을 표시하려면 커스텀 UI를 사용하세요.

커스텀 UI

1. Data Attributes 방식

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

Data Attributes

string
필수
애드컨트롤 콘솔에서 생성한 유닛 ID
string
필수
커스텀 UI 사용 시 custom으로 설정
string
문맥 타겟팅용 Context ID
string
기본값:"light"
테마 설정 (light 또는 dark)
boolean
기본값:false
전체 영역 클릭 활성화
  • false: 텍스트/이미지만 클릭 가능, 광고주 프로필 클릭 시 프로필 링크로 이동
  • true: 컨테이너 전체 클릭 가능, 모든 클릭이 광고 목적지로 이동
boolean
기본값:false
커스텀 클릭 처리 활성화 - true로 설정하면 SDK가 자동으로 목적지 URL로 이동하지 않고, adClicked 이벤트만 발생시킵니다. 개발자가 클릭 동작을 직접 구현할 수 있습니다.
string
광고 식별자 — 내 기기에서 보기 기능으로 등록한 테스트 기기에서 소재를 미리 확인할 때 필수입니다. 운영 환경에 하드코딩하지 마세요.

2. renderAd 방식

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

renderAd 옵션

string
필수
애드컨트롤 콘솔에서 생성한 유닛 ID
string
사용자 식별자 (SDK 설정 값을 개별 지면에서 오버라이드할 때 사용)
string
문맥 타겟팅용 Context ID
number
필수
커스텀 UI 사용 시 1로 설정
boolean
기본값:false
전체 영역 클릭 활성화
string
기본값:"light"
테마 설정 (light 또는 dark)
boolean
기본값:false
커스텀 클릭 처리 활성화 - true로 설정하면 SDK가 자동으로 목적지 URL로 이동하지 않고, adClicked 이벤트만 발생시킵니다. 개발자가 클릭 동작을 직접 구현할 수 있습니다.
string
광고 식별자 — 내 기기에서 보기 기능으로 등록한 테스트 기기에서 소재를 미리 확인할 때 필수입니다. 운영 환경에 하드코딩하지 마세요.

필드 바인딩

data-adrop-native 속성으로 광고 데이터를 UI 요소에 바인딩합니다.
extra.{key}는 애드컨트롤 콘솔에서 설정한 추가 텍스트 항목의 ID입니다. 필수로 설정하지 않았다면 비어있을 수 있습니다.
extraAssets.{id}는 다중 미디어 유닛의 미디어 아이디(예: m2)입니다. 이 바인딩은 이미지만 표시합니다. 동영상을 받는 유닛이라면 다중 미디어 소재에 따라 미디어를 표시하세요. (SDK 1.4.0+)
광고주 프로필(profile.displayLogo, profile.displayName)을 표시하려면 애드컨트롤 콘솔에서 해당 광고 유닛의 광고주 프로필 표시를 활성화해야 합니다.

광고 크기

커스텀 UI의 크기는 자유롭게 설정할 수 있습니다.
백필 광고는 컨테이너 크기에 맞는 소재를 요청합니다. 적절한 크기를 지정하세요.

requestAd로 데이터만 가져오기

UI를 완전히 직접 제어하고 싶다면 requestAd로 광고 데이터만 가져올 수 있습니다.
requestAd 사용 시 노출/클릭 추적을 직접 구현해야 합니다. 또한 이 방식에서는 백필 광고가 지원되지 않습니다. 특별한 경우가 아니라면 renderAd를 권장합니다.

AdropAdResponse

requestAd()의 반환값입니다.

AdData

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

커스텀 클릭 처리

useCustomClick이 활성화되면 SDK가 자동으로 목적지 URL로 이동하지 않습니다. 대신 클릭 이벤트를 처리하여 사용자 정의 동작을 구현할 수 있습니다.
커스텀 클릭 처리가 활성화되면 사용자가 광고를 클릭할 때 어떤 일이 일어날지 완전히 제어할 수 있습니다. destinationURL은 adClicked 이벤트 데이터에 포함되어 제공됩니다.

이벤트 처리

지원 이벤트


다중 미디어 소재

@adrop/ads-web-sdk 1.4.0 이상이 필요합니다.
네이티브 유닛에 미디어가 2개 이상이면 소재에 미디어마다 파일이 들어 있습니다. extraAssets에는 광고의 모든 미디어가 들어 있으며, 키는 콘솔에서 정한 미디어 아이디입니다. 미디어 1은 항상 m1이고, 나머지 미디어는 광고 유닛 상세 화면의 미디어 크기에 표시된 아이디(예: m2, m3)를 씁니다. extraAssets는 AD_RECEIVED 같은 SDK 이벤트의 광고 데이터와 requestAd(), requestAds() 결과에 포함됩니다.
  • 미디어 1(m1)은 광고의 대표 미디어(asset 또는 ad)입니다. 지금처럼 표시하고, 나머지 미디어만 직접 그리세요.
  • 미디어가 하나인 유닛의 소재와 백필 광고에는 extraAssets가 없습니다.
  • 미디어는 순서에 기대지 말고 아이디로 찾으세요.
  • 광고가 다크 모드로 송출되면 이미지 미디어도 다크 모드용 이미지로 제공됩니다.
  • 다중 미디어 소재로 레이아웃을 확인하려면 테스트 기기에서 소재를 미리 보세요.

AdropNativeAsset

미디어 표시하기

이 섹션은 커스텀 UI(trackMode: 1) 기준입니다.
  • 이미지: 직접 넣은 이미지의 클릭도 광고 클릭으로 집계되도록 isEntireClick: true로 설정하세요. 이미지는 asset으로 표시하세요. trackMode: 1에서는 이미지의 ad HTML이 클릭을 Adrop에 보고하지 않습니다.
  • 동영상: asset URL이 아니라 ad HTML을 <iframe>에서 재생하세요. HTML에 동영상 플레이어와 트래킹이 들어 있어, 동영상 지표는 이 HTML로만 측정됩니다. <iframe> 안의 클릭은 광고 컨테이너로 전달되지 않으므로 동영상 탭은 HTML만 처리합니다. <iframe>에 sandbox 속성은 넣지 마세요. HTML이 스크립트를 실행하고 랜딩 페이지를 열어야 합니다.
  • 랜딩 페이지: 사용자가 동영상을 탭하면 HTML이 클릭을 보고하고 랜딩 페이지를 엽니다.

노출과 클릭

노출, 클릭, 동영상 지표는 SDK와 미디어가 모두 보고해도 미디어별이 아니라 광고당 한 번만 집계됩니다.
동영상의 어떤 탭이 클릭으로 집계되는지는 유닛의 영상 컨트롤러 설정에 따라 다릅니다. 컨트롤러가 꺼져 있으면 동영상의 모든 탭이 클릭으로 집계되고, 켜져 있으면 재생·음소거 컨트롤을 누른 것은 클릭으로 집계되지 않습니다.

예제

미디어 2(m2)를 이미지나 동영상으로 광고 컨테이너 안에 표시하는 예제입니다. m2는 유닛의 미디어 아이디로 바꾸세요.
<iframe> 크기는 유닛에 설정한 미디어 크기에 맞추세요. 예제는 16:9 미디어 기준입니다.

백필 광고

백필 광고가 활성화되면 직광고가 없을 때 자동으로 백필 광고를 요청합니다. adData.format으로 광고 타입을 구분할 수 있습니다.
개발 환경 테스트: 앱에 연결된 광고 유닛 중 하나라도 수익화 중이면 localhost에서도 백필 광고 요청이 가능합니다. 승인되지 않은 도메인에서는 AD_BACKFILL_NO_FILL 이벤트가 발생합니다.