@adwhale/web-sdk

ADwhale 광고 미디에이션 Web SDK. 배너, 전면(Interstitial), 네이티브 광고를 웹에서 워터폴 미디에이션 방식으로 제공합니다.

설치

npm install @adwhale/web-sdk

프레임워크별 래퍼도 제공됩니다:

• React: npm install @adwhale/web-sdk-react
• Vue 3: npm install @adwhale/web-sdk-vue
• Angular: npm install @adwhale/web-sdk-angular
• AngularJS: npm install @adwhale/web-sdk-angularjs

CDN 사용

<script src="https://cdn.fsn.co.kr/sdk/adwhale/adwhale.sdk.min.js"></script>
<script>
  adwhale.cmd.push(function() {
    adwhale.AdWhaleMediationAds.init({ publisherUid: 'PUB-XXXX' });
  });
</script>

빠른 시작

1. SDK 초기화

import { AdWhaleMediationAds } from '@adwhale/web-sdk';

AdWhaleMediationAds.init({
  publisherUid: 'PUB-XXXX',
  debug: true,       // 콘솔 로그 출력
  testMode: false,   // 테스트 광고 모드
});

2. 배너 광고

const banner = AdWhaleMediationAds.createBanner({
  placementUid: 'PLACE-XXXX',
  container: '#ad-banner',    // CSS 셀렉터 또는 HTMLElement
  adSize: '320x50',
  autoRefresh: true,
  loading: 'lazy',
  passbackTag: '<div>fallback ad</div>',
});

banner
  .onAdLoaded((info) => console.log('loaded', info))
  .onAdLoadFailed((error) => console.log('failed', error))
  .onAdImpression((info) => console.log('impression', info))
  .onAdClicked(() => console.log('clicked'))
  .onAdRefreshed((info) => console.log('refreshed', info))
  .onPassback(() => console.log('passback'))
  .load();

// 정리
banner.destroy();

3. 전면 광고 (Interstitial)

const interstitial = AdWhaleMediationAds.createInterstitial({
  placementUid: 'PLACE-YYYY',
});

interstitial
  .onAdLoaded((info) => console.log('ready', info))
  .onAdLoadFailed((error) => console.log('failed', error))
  .onAdShowed(() => console.log('showed'))
  .onAdImpression((info) => console.log('impression', info))
  .onAdClosed(() => console.log('closed'))
  .onAdClicked(() => console.log('clicked'))
  .load();

// 로드 완료 후 표시
interstitial.show();

// 정리
interstitial.destroy();

4. 네이티브 광고

const native = AdWhaleMediationAds.createNative({
  placementUid: 'PLACE-ZZZZ',
  container: '#native-ad',
  loading: 'lazy',
});

native
  .onAdLoaded((info) => {
    const data = native.adData;
    // data.title, data.desc, data.imageMain, data.imageIcon,
    // data.linkUrl, data.ctaText, data.sponsored
  })
  .onAdLoadFailed((error) => console.log('failed', error))
  .onAdImpression((info) => console.log('impression', info))
  .onAdClicked(() => console.log('clicked'))
  .load();

5. <ins> 태그 선언적 방식

HTML에 <ins> 태그를 추가하면 SDK가 자동으로 배너 광고를 생성합니다.

<ins class="adwhale-ad"
  data-placement-uid="PLACE-XXXX"
  data-ad-size="320x50"
  data-loading="lazy"
></ins>

SPA에서 동적으로 추가되는 <ins> 태그도 MutationObserver로 자동 감지합니다.

Ad Blocker 감지

AdWhaleMediationAds.onAdBlocked(() => {
  console.log('Ad blocker detected');
});

// 또는 직접 확인
if (AdWhaleMediationAds.isAdBlockerDetected()) {
  // ...
}

API

AdWhaleMediationAds

| 메서드 | 설명 | |--------|------| | init(config) | SDK 초기화 (최초 1회) | | reset() | SDK 상태 리셋 (재초기화 시 필요) | | isInitialized() | 초기화 여부 | | createBanner(options) | 배너 광고 인스턴스 생성 | | createInterstitial(options) | 전면 광고 인스턴스 생성 | | createNative(options) | 네이티브 광고 인스턴스 생성 | | onAdBlocked(cb) | Ad blocker 감지 콜백 | | isAdBlockerDetected() | Ad blocker 감지 여부 |

AdWhaleInitConfig

| 필드 | 타입 | 필수 | 설명 | |------|------|------|------| | publisherUid | string | O | 매체 UID | | debug | boolean | | 디버그 로그 (기본: false) | | testMode | boolean | | 테스트 모드 (기본: false) | | environment | "real" \| "uat" | | 환경 (기본: "real") | | coreSdkUrl | string | | Core SDK CDN URL (커스텀) |

BannerOptions

| 필드 | 타입 | 필수 | 설명 | |------|------|------|------| | placementUid | string | O | 지면 UID | | container | string \| HTMLElement | O | 광고 컨테이너 | | adSize | "320x50" \| "320x100" \| "300x250" \| "250x250" \| "adaptive" | | 광고 사이즈 | | autoRefresh | boolean | | 자동 갱신 | | loading | "lazy" \| "eager" | | 로딩 방식 (기본: "lazy") | | passbackTag | string | | Passback HTML |

InterstitialOptions

| 필드 | 타입 | 필수 | 설명 | |------|------|------|------| | placementUid | string | O | 지면 UID | | passbackTag | string | | Passback HTML |

NativeOptions

| 필드 | 타입 | 필수 | 설명 | |------|------|------|------| | placementUid | string | O | 지면 UID | | container | string \| HTMLElement | O | 광고 컨테이너 | | loading | "lazy" \| "eager" | | 로딩 방식 | | passbackTag | string | | Passback HTML |

라이선스

MIT