@gfactory/ad-mediation

React용 광고 매디에이션 워터폴 시스템. Google Ad Manager (GPT) Rewarded Ads 지원.

설치

npm install @gfactory/ad-mediation

사용법

기본 사용

import { useAdMediation } from '@gfactory/ad-mediation'
import { useEffect } from 'react'

function GamePage() {
  const ad = useAdMediation({
    providers: [
      { name: 'google-gpt', key: '/22996174068/your-ad-unit-path' }
    ],
    onAdCompleted: () => {
      console.log('광고 시청 완료 - 보상 지급')
    },
    onAdClosed: () => {
      console.log('광고 닫힘')
    },
    onNoAd: () => {
      console.log('광고 없음')
    }
  })

  // 페이지 진입 시 사전 로딩 (권장)
  useEffect(() => {
    ad.preloadGoogleGPT()
  }, [])

  // 버튼 클릭 등 원하는 시점에 호출
  return (
    <button onClick={ad.startMediation} disabled={ad.isLoading}>
      광고 보기
    </button>
  )
}

워터폴 (여러 슬롯 순차 시도)

const ad = useAdMediation({
  providers: [
    { name: 'google-gpt', key: '/22996174068/slot-A' },
    { name: 'google-gpt', key: '/22996174068/slot-B' },
  ],
  onAdCompleted: () => grantReward(),
})

첫 번째 슬롯이 실패하면 자동으로 두 번째 슬롯을 시도합니다.

전환 이벤트 추적

const ad = useAdMediation({
  providers: [{ name: 'google-gpt', key: '/22996174068/my-slot' }],
  onAdCompleted: () => grantReward(),
  onConversion: (providerName) => {
    // 서버에 전환 이벤트 전송
    fetch('/api/ad-event', {
      method: 'POST',
      body: JSON.stringify({ provider: providerName, contentId: 'my-content' })
    })
  }
})

디버그 모드

URL에 ?ad_debug 파라미터를 추가하면 콘솔에 상세 로그가 출력됩니다.

https://example.com/game?ad_debug

API

useAdMediation(options)

Options

| 속성 | 타입 | 필수 | 설명 | |------|------|------|------| | providers | AdProviderConfig[] | O | 광고 프로바이더 목록 (순서대로 시도) | | onAdCompleted | () => void | - | 광고 시청 완료 콜백 | | onAdClosed | () => void | - | 광고 닫힘 콜백 | | onNoAd | () => void | - | 모든 프로바이더 실패 콜백 | | onConversion | (provider: string) => void | - | 전환 이벤트 콜백 |

Returns

| 속성 | 타입 | 설명 | |------|------|------| | startMediation | () => Promise<void> | 워터폴 시작 | | isLoading | boolean | 로딩 중 여부 | | currentProvider | string \| null | 현재 시도 중인 프로바이더 | | adCompleted | boolean | 시청 완료 여부 | | preloadGoogleGPT | (key?) => Promise<void> | GPT 사전 로딩 | | clearPreloadedGPT | () => void | 사전 로딩 슬롯 정리 | | gptPreloadState | GptPreloadState | 'idle' \| 'loading' \| 'ready' \| 'failed' |

지원 프로바이더

| 프로바이더 | key 형식 | 상태 | |-----------|---------|------| | google-gpt | Ad Unit Path (예: /22996174068/slot) | 지원 |

라이선스

MIT