> ## Documentation Index > Fetch the complete documentation index at: https://docs.adrop.io/llms.txt > Use this file to discover all available pages before exploring further. # 레퍼런스 > Adrop Web SDK의 클래스, 인터페이스, 상수, 타입 정의입니다. ## 클래스 ### Adrop SDK의 메인 클래스입니다. 싱글톤 패턴으로 동작합니다. #### 정적 메서드 | 메서드 | 반환 타입 | 설명 | | ----------------- | ------- | ---------------------- | | `observe(config)` | `Adrop` | SDK 초기화 및 DOM 자동 감지 시작 | | `instance()` | `Adrop` | 기존 인스턴스 반환 | #### 인스턴스 메서드 | 메서드 | 반환 타입 | 설명 | | ------------------------------- | --------------------------- | --------------- | | `renderAd(container, request?)` | `Promise` | 광고 렌더링 | | `requestAd(request)` | `Promise` | 광고 데이터만 요청 (단일) | | `requestAds(request)` | `Promise` | 복수 광고 데이터 요청 | | `clear(container)` | `void` | 광고 제거 | | `setConfig(config)` | `void` | 설정 변경 | | `on(event, callback, filter?)` | `void` | 이벤트 리스너 등록 | | `off(event, callback)` | `void` | 이벤트 리스너 해제 | #### 인스턴스 속성 | 속성 | 타입 | 설명 | | --------- | -------------- | ------------------------ | | `uid` | `string` | 사용자 식별자 (getter/setter) | | `appKey` | `string` | API 인증 키 (getter/setter) | | `metrics` | `AdropMetrics` | 사용자 속성 관리 | ### AdropMetrics 사용자 속성 관리 클래스입니다. #### 메서드 | 메서드 | 반환 타입 | 설명 | | -------------------------- | --------------- | ------------------------ | | `setUserProperties(props)` | `AdropMetrics` | 사용자 속성 설정 (체이닝 가능) | | `setAppProperties(props)` | `AdropMetrics` | 앱 속성 설정 (체이닝 가능) | | `commit()` | `Promise` | 속성을 서버에 저장 | | `properties()` | `Properties` | 현재 설정된 속성 반환 | | `clear()` | `void` | 설정된 속성 초기화 (디바이스 속성은 유지) | *** ## 인터페이스 ### AdropConfig SDK 초기화 옵션입니다. ```typescript theme={null} interface AdropConfig { appId: string; // 앱 ID (필수) uid?: string; // 사용자 식별자 appKey?: string; // API 인증 키 debug?: boolean; // 디버그 로깅 (기본값: false) backfillMode?: BackfillMode; // 전역 백필 렌더링 모드 (1.2.3+, 기본값: 'responsive') } ``` ### AdropAdRequest 광고 요청 파라미터입니다. ```typescript theme={null} interface AdropAdRequest { unit: string; // 유닛 ID (필수) uid?: string; // 사용자 식별자 contextId?: string; // 문맥 타겟팅 ID trackMode?: 0 | 1; // 0: 자동, 1: 수동 (네이티브) isEntireClick?: boolean; // 전체 영역 클릭 (네이티브) theme?: AdTheme; // 테마 useCustomClick?: boolean; // 커스텀 클릭 처리 backfillMode?: BackfillMode; // 슬롯별 백필 렌더링 모드 오버라이드 (1.2.3+) adId?: string; // 광고 식별자 — 내 기기에서 보기 시 필수 } ``` `adId`는 **내 기기에서 보기** 기능으로 등록한 테스트 기기에서 소재를 미리 확인할 때 사용하는 광고 식별자입니다. 사용 방법은 [테스트 기기에서 소재 미리보기](/ko/management/support#테스트-기기에서-소재-미리보기) 가이드를 참고하세요. 운영 환경에 `adId`를 하드코딩한 채 배포하지 마세요. ### AdropAdResponse 광고 응답 객체입니다 (단일 광고). ```typescript theme={null} interface AdropAdResponse { code: AdropErrorCode; // 응답 코드 msg: string; // 응답 메시지 result?: AdData; // 광고 데이터 (성공 시) } ``` ### AdropAdsResponse 광고 응답 객체입니다 (복수 광고). ```typescript theme={null} interface AdropAdsResponse { code: AdropErrorCode; // 응답 코드 msg: string; // 응답 메시지 results?: AdData[]; // 광고 데이터 배열 (성공 시) } ``` ### AdData 광고 데이터 객체입니다. ```typescript theme={null} interface AdData { // 공통 format: AdFormat; // 광고 포맷 unit: string; // 유닛 ID ad: string; // 광고 HTML 콘텐츠 w: number; // 광고 너비 h: number; // 광고 높이 type?: string; // 광고 타입 target?: string; // 타겟 URL 열기 방식 // 네이티브 광고 필드 headline?: string; // 광고 제목 body?: string; // 광고 설명 callToAction?: string; // CTA 버튼 텍스트 asset?: string; // 메인 이미지 URL destinationURL?: string; // 클릭 시 이동 URL // 식별자 필드 id?: string; // 광고 ID cpId?: string; // 캠페인 ID creativeId?: string; // 크리에이티브 ID accountTag?: string; // 계정 레벨 태그 creativeTag?: string; // 크리에이티브 레벨 태그 // 트래커 필드 (trackMode=1) pixelTracker?: string; // 픽셀 트래커 URL (1x1 이미지, 노출 추적) imprTracker?: string; // 노출 트래커 URL clickTracker?: string; // 클릭 트래커 URL // 광고주 프로필 profile?: { displayLogo?: string; // 광고주 로고 URL displayName?: string; // 광고주 이름 link?: string; // 광고주 프로필 링크 }; // 추가 텍스트 항목 extra?: Record; } ``` ### AdropEventFilter 이벤트 필터 옵션입니다. ```typescript theme={null} interface AdropEventFilter { unit?: string; // 특정 유닛만 필터링 } ``` *** ## 상수 ### Adrop.Events 이벤트 상수입니다. `Adrop.Events`로 접근합니다. | 상수 | 값 | 설명 | | --------------------- | -------------------- | ------------ | | `AD_RECEIVED` | `'adReceived'` | 광고 수신 성공 | | `AD_NO_FILL` | `'adNoFill'` | 직광고 없음 | | `AD_IMPRESSION` | `'adImpression'` | 광고 노출 | | `AD_CLICKED` | `'adClicked'` | 광고 클릭 | | `AD_FAILED` | `'adFailed'` | 광고 요청 실패 | | `AD_BACKFILL_NO_FILL` | `'adBackfillNoFill'` | 백필 광고 없음 | | `AD_VIDEO_START` | `'adVideoStart'` | 동영상 광고 재생 시작 | | `AD_VIDEO_END` | `'adVideoEnd'` | 동영상 광고 재생 완료 | ### Adrop.ErrorCode 에러 코드입니다. `Adrop.ErrorCode`로 접근합니다. | 상수 | 값 | 설명 | | --------------------------- | ------ | ---------- | | `OK` | `0` | 성공 | | `ERROR_CODE_INVALID_UNIT` | `4000` | 잘못된 유닛 ID | | `ERROR_CODE_AD_INACTIVE` | `4001` | 활성 캠페인 없음 | | `ERROR_CODE_AD_NO_FILL` | `4002` | 매칭되는 광고 없음 | | `ERROR_CODE_INVALID_PARAMS` | `4003` | 잘못된 파라미터 | *** ## 타입 ### AdFormat 광고 포맷 타입입니다. ```typescript theme={null} type AdFormat = 'banner' | 'nativeAd' | 'backfill'; ``` ### AdTheme 테마 타입입니다. ```typescript theme={null} type AdTheme = 'light' | 'dark'; ``` ### BackfillMode 백필 광고 렌더링 모드 타입입니다. (SDK 1.2.3+) ```typescript theme={null} type BackfillMode = 'responsive' | 'fixed'; ``` 자세한 동작과 선택 기준은 [백필 렌더링 모드](/ko/sdk/web/backfill) 가이드를 참고하세요. *** ## 이벤트 콜백 각 이벤트의 콜백 시그니처입니다. ```typescript theme={null} // 광고 수신, 노출, 클릭 type AdReceivedCallback = (unit: string, adData: AdData) => void; type AdImpressionCallback = (unit: string, adData: AdData) => void; type AdClickedCallback = (unit: string, adData: AdData) => void; // 광고 없음, 실패, 백필 광고 없음 type AdNoFillCallback = (unit: string) => void; type AdFailedCallback = (unit: string) => void; type AdBackfillNoFillCallback = (unit: string) => void; // 동영상 type AdVideoStartCallback = (unit: string, adData: AdData) => void; type AdVideoEndCallback = (unit: string, adData: AdData) => void; ``` 모든 이벤트 콜백은 첫 번째 인자로 `unit`을 받습니다. `AD_RECEIVED`, `AD_IMPRESSION`, `AD_CLICKED`, `AD_VIDEO_START`, `AD_VIDEO_END` 이벤트는 두 번째 인자로 `adData`도 함께 받습니다.