광고 (Ads)

Google AdSense를 통한 광고 수익 조회 및 웹사이트 광고 배치 API입니다.

광고 기능을 사용하려면 먼저 Connect Base 콘솔에서 Google AdSense 계정을 연결해야 합니다. 콘솔 > 수익화 > 광고에서 Google 계정을 연결하세요.

초기화

typescript

import ConnectBase from 'connectbase-client'

const cb = new ConnectBase({
    publicKey: 'your-public-key'
})

typescript

const status = await cb.ads.getConnectionStatus()

if (status.adsense.is_connected) {
    console.log('AdSense 연결됨:', status.adsense.email)
    console.log('AdSense Account ID:', status.adsense.account_id)
}
if (status.admob.is_connected) {
    console.log('AdMob 연결됨:', status.admob.email)
    console.log('AdMob Account ID:', status.admob.account_id)
    console.log('AdMob Publisher ID:', status.admob.publisher_id)
}

GoogleConnectionStatus 타입:

필드	타입	설명
`adsense.is_connected`	boolean	AdSense 연결 여부
`adsense.email`	string?	AdSense Google 계정 이메일
`adsense.account_id`	string?	AdSense 계정 ID
`admob.is_connected`	boolean	AdMob 연결 여부
`admob.email`	string?	AdMob Google 계정 이메일
`admob.account_id`	string?	AdMob 계정 ID
`admob.publisher_id`	string?	AdMob Publisher ID

광고 수익 리포트 조회

typescript

// 기간 지정 조회
const report = await cb.ads.getReport('2025-01-01', '2025-01-31')

// 요약 데이터
console.log('총 수익:', report.summary.total_earnings)
console.log('총 노출:', report.summary.total_impressions)
console.log('총 클릭:', report.summary.total_clicks)
console.log('CTR:', report.summary.ctr, '%')
console.log('CPC:', report.summary.cpc)
console.log('RPM:', report.summary.rpm)

// 일별 데이터
report.daily.forEach(day => {
    console.log(\`\${day.date}: $\${day.earnings} (노출: \${day.impressions})\`)
})

// 기간 미지정 시 최근 30일 자동 조회
const defaultReport = await cb.ads.getReport()

최근 30일 요약 조회

typescript

const summary = await cb.ads.getReportSummary()

console.log(\`총 수익: $\${summary.total_earnings.toFixed(2)}\`)
console.log(\`총 노출: \${summary.total_impressions.toLocaleString()}\`)
console.log(\`클릭률: \${summary.ctr.toFixed(2)}%\`)
console.log(\`RPM: $\${summary.rpm.toFixed(2)}\`)

React에서 광고 수익 대시보드

tsx

import { useState, useEffect } from 'react'

function AdDashboard() {
    const [summary, setSummary] = useState(null)
    const [isConnected, setIsConnected] = useState(false)

    useEffect(() => {
        async function loadAdData() {
            const status = await cb.ads.getConnectionStatus()
            setIsConnected(status.adsense.is_connected)
            if (status.adsense.is_connected) {
                const data = await cb.ads.getReportSummary()
                setSummary(data)
            }
        }
        loadAdData()
    }, [])

    if (!isConnected) return <p>AdSense 미연결</p>
    if (!summary) return <p>로딩 중...</p>

    return (
        <div>
            <h2>광고 수익 (최근 30일)</h2>
            <p>수익: ${summary.total_earnings.toFixed(2)}</p>
            <p>노출: {summary.total_impressions.toLocaleString()}</p>
            <p>클릭: {summary.total_clicks.toLocaleString()}</p>
            <p>CTR: {summary.ctr.toFixed(2)}%</p>
        </div>
    )
}

자동 광고 (Auto Ads)

콘솔에서 설정하면 웹 스토리지에 배포한 사이트에 Google 자동 광고가 자동 삽입됩니다.

설정 방법:

Google AdSense 계정 연결: 콘솔 > 수익화 > 광고 > "Google 계정 연결"
웹 스토리지에서 활성화: 콘솔 > 스토리지 > 웹 > 스토리지 선택 > AdSense 탭
Publisher ID 입력: ca-pub-XXXXXXXXXXXXXXXX 형식
ads.txt 자동 생성: Publisher ID 입력 시 자동 생성됨 (커스텀 가능)

adsbygoogle.js 스크립트는 web-proxy-server가 자동으로 <head>에 주입합니다. ads.txt는 웹 스토리지 도메인의 /ads.txt 경로에서 자동 제공됩니다.

수동 광고 배치

원하는 위치에 직접 광고를 배치하려면 AdSense 콘솔에서 광고 단위를 생성한 후 HTML에 삽입합니다.

광고 유형:

디스플레이 광고: 반응형 배너 (가장 범용적)
인피드 광고: 피드/목록 사이에 삽입
콘텐츠 내 광고: 글 본문 중간에 삽입
멀티플렉스 광고: 여러 광고를 그리드로 표시

HTML에 광고 코드 삽입:

html

<!-- 원하는 위치에 삽입 -->
<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-XXXXXXXXXXXXXXXX"
     data-ad-slot="1234567890"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>(adsbygoogle = window.adsbygoogle || []).push({});</script>

adsbygoogle.js는 콘솔에서 AdSense 활성화 시 자동 주입되므로, <ins> 태그만 삽입하면 됩니다.

React/SPA에서 광고 컴포넌트:

tsx

import { useEffect, useRef } from 'react'

function AdBanner({ adSlot, format = 'auto' }: { adSlot: string; format?: string }) {
    const adRef = useRef<HTMLDivElement>(null)

    useEffect(() => {
        try {
            ((window as any).adsbygoogle = (window as any).adsbygoogle || []).push({})
        } catch (e) {
            // 광고 차단기 등으로 실패 시 무시
        }
    }, [])

    return (
        <div ref={adRef}>
            <ins className="adsbygoogle"
                style={{ display: 'block' }}
                data-ad-client="ca-pub-XXXXXXXXXXXXXXXX"
                data-ad-slot={adSlot}
                data-ad-format={format}
                data-full-width-responsive="true" />
        </div>
    )
}

// 사용
<AdBanner adSlot="1234567890" />

API 레퍼런스

메서드	설명	반환 타입
`getConnectionStatus()`	AdSense 연결 상태 확인	`Promise<GoogleConnectionStatus>`
`getReport(start?, end?)`	리포트 조회 (일별 + 요약)	`Promise<AdReportResponse>`
`getReportSummary()`	최근 30일 요약	`Promise<AdReportSummary>`

API 엔드포인트

메서드	엔드포인트
`getConnectionStatus()`	`GET /v1/public/ads/connection`
`getReport()`	`GET /v1/public/ads/reports?start=YYYY-MM-DD&end=YYYY-MM-DD`
`getReportSummary()`	`GET /v1/public/ads/reports/summary`

모든 /v1/public/* 엔드포인트는 X-Public-Key 헤더로 Public Key 인증이 필요합니다.

응답 타입

typescript

interface AdReportSummary {
    total_earnings: number    // 총 수익 ($)
    total_impressions: number // 총 노출수
    total_clicks: number      // 총 클릭수
    ctr: number               // 클릭률 (%)
    cpc: number               // 클릭당 비용 ($)
    rpm: number               // 1,000 노출당 수익 ($)
}

interface DailyReport {
    date: string              // 날짜 (YYYY-MM-DD)
    earnings: number          // 수익 ($)
    impressions: number       // 노출수
    clicks: number            // 클릭수
    ctr: number               // 클릭률 (%)
}

interface AdReportResponse {
    summary: AdReportSummary
    daily: DailyReport[]
}

구독 (Subscription)

에러 트래커 (Error Tracker)

광고 (Ads)

초기화

AdSense / AdMob 연결 상태 확인

광고 수익 리포트 조회

최근 30일 요약 조회

React에서 광고 수익 대시보드

웹 스토리지에서 AdSense 활성화

자동 광고 (Auto Ads)

수동 광고 배치

API 레퍼런스

API 엔드포인트

응답 타입