---
url: /api-sdk/sdk/adfit.md
description: 애드핏 전면 광고·보상형 전면 광고 SDK 의 설치·인스턴스 생성·노출 제어·이벤트 스펙
---
# 애드핏 광고 SDK
애드핏 광고 SDK 로 파트너사 게임에서 전면 광고와 보상형 전면 광고를 노출하는 방법입니다. 두 광고는 설치·노출 제어·이벤트가 동일하며, 인스턴스를 만드는 팩토리 메서드와 보상 처리만 다릅니다.
> **관련 가이드**: [광고 UX 가이드](/docs/ads/ux-guideline), [애드핏 설정](/docs/ads/iaa-options)
::: info 신규 연동이라면
[게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/)가 광고 SDK 를 내부에서 다루므로 `Gameplay.*` 호출만으로 전면·보상형 광고를 노출할 수 있습니다. 이 문서는 애드핏 광고 SDK 를 **직접** 연동하는 방식입니다.
두 방식을 동시에 구성하는 것은 권장하지 않습니다. 자세한 내용은 [SDK 연동 방식 선택](/api-sdk/sdk/)을 참고하세요. 광고단위 발급은 방식과 무관하게 파트너사가 직접 진행합니다.
:::
## SDK 설치
광고를 노출할 페이지에 아래 스크립트를 삽입합니다.
```html
```
### 페이지 메타태그 설정
모바일 브라우저에서 광고를 상단 내비게이션 영역까지 자연스럽게 표시하려면, 광고를 노출할 페이지 `` 의 viewport 메타태그에 `viewport-fit=cover` 를 지정합니다.
```html
```
기존 viewport 메타태그가 있다면 새 태그를 추가하지 않고 `content` 값에 `viewport-fit=cover` 만 덧붙입니다.
## 타입 정의
SDK는 브라우저 어디서든 접근할 수 있는 `window.kakaoAdFit` 객체로 제공됩니다. TypeScript 프로젝트에서는 아래처럼 `window.kakaoAdFit` 타입을 선언하면 이후 예제를 그대로 컴파일할 수 있습니다.
```ts
type AdFitAdEvent = 'loaded' | 'failed' | 'opened' | 'closed' | 'rewarded' | 'unloaded';
interface AdFitAdOptions {
ctag?: {cp: string; channel: string};
safeAreaInset?: {
top: number;
bottom: number;
left: number;
right: number;
};
}
interface AdFitAd {
load(): void;
open(): void;
close(): void;
destroy(): void;
addListener(event: AdFitAdEvent, handler: () => void): void;
removeListener(event: AdFitAdEvent, handler: () => void): void;
}
declare global {
interface Window {
kakaoAdFit: {
cmd: Array<() => void>;
createInterstitialAd(adUnit: string, options?: AdFitAdOptions): AdFitAd;
createRewardedInterstitialAd(adUnit: string, options?: AdFitAdOptions): AdFitAd;
};
}
}
```
`rewarded` 는 보상형 광고에서만 발생합니다. 전면 광고 인스턴스에 등록해도 호출되지 않습니다.
## 인스턴스 생성
광고의 노출·미노출을 관리할 인스턴스를 생성합니다. 광고 관련 모든 스크립트는 SDK 설치 이후 실행되어야 하므로 `window.kakaoAdFit.cmd.push` 콜백 안에서 작성합니다.
| 광고 유형 | 팩토리 메서드 |
| --- | --- |
| 전면 광고 | `window.kakaoAdFit.createInterstitialAd(adUnit, options?)` |
| 보상형 전면 광고 | `window.kakaoAdFit.createRewardedInterstitialAd(adUnit, options?)` |
```html
```
생성 이후의 메서드와 이벤트는 두 유형이 같습니다. 보상형 광고에만 `rewarded` 이벤트가 추가됩니다.
### 옵션
팩토리 메서드의 두 번째 인자로 `AdFitAdOptions` 를 전달합니다. 아래 옵션들은 함께 지정할 수 있습니다.
| 옵션 | 용도 |
| --- | --- |
| `ctag` | 채널 CP 수집 |
| `safeAreaInset` | 게임웹뷰가 제공하는 Safe Area 값 전달 (단위: px). 리워드·전면형 광고 운영 시 반드시 적용 |
### 채널 CP 수집
채널 CP 를 수집하려면 `ctag` 를 지정합니다.
게임별 광고 지표를 구분하려면 `ctag`의 CPID와 채널 ID를 정확하게 설정해야 합니다.
::: danger 주의사항
게임별 광고 수익 통계를 지원하려면 `ctag.cp`의 CPID를 게임플레이 파트너센터에 등록한 게임 코드와 동일하게 설정해야 합니다.
값이 다르거나 누락되면 광고 수익이 해당 게임과 연결되지 않으므로 반드시 설정하세요.
:::
| 값 | 설정 기준 |
| --- | --- |
| **CPID** (`cp`) | 게임플레이 파트너센터에 등록한 게임 코드와 **동일한 값**을 입력합니다.메타데이터 API로 게임을 등록했던 파트너사는 그 `code` 값을 그대로 유지합니다. |
| **채널 ID** (`channel`) | 카카오에서 발급한 값을 입력합니다.발급값 확인이 필요한 경우 카카오 담당자에게 문의하세요. |
게임마다 CPID가 다르므로 게임별 광고 SDK 인스턴스에 정확한 값을 매핑합니다.
```ts
const safeAreaInset = await window.kakaotalkGamePlay.getSafeArea();
const options: AdFitAdOptions = {
ctag: {
cp: '파트너사가 설정한 게임 코드와 동일한 CPID',
channel: '카카오에서 발급한 채널 ID',
},
safeAreaInset,
};
const ad = window.kakaoAdFit.createInterstitialAd(adUnit, options);
```
### Safe Area 설정
::: danger 주의사항
보상형 전면 광고와 전면 광고의 광고단위를 적용할 때는 `safeAreaInset` 설정이 반드시 필요합니다.
게임웹뷰의 전체 화면 사용 여부와 관계없이 두 광고 상품을 운영하면 모두 적용해야 합니다.
:::
[게임웹뷰 SDK의 `getSafeArea()`](/api-sdk/sdk/kakaotalk-gameplay#getsafearea)가 반환한 `top`, `bottom`, `left`, `right` 값을 가공하지 않고 `safeAreaInset`으로 그대로 전달하세요.
값이 `0`인 방향도 생략하지 말고 `0`으로 전달합니다.
```ts
const safeAreaInset = await window.kakaotalkGamePlay.getSafeArea();
// 예: {top: 47, bottom: 34, left: 0, right: 0}
const options: AdFitAdOptions = {
safeAreaInset,
};
const ad = window.kakaoAdFit.createRewardedInterstitialAd(adUnit, options);
```
## 광고 노출 제어
인스턴스 생성 이후 아래 네 개의 메서드로 광고 노출을 제어합니다.
| 메서드 | 동작 |
| --- | --- |
| `ad.load()` | 광고 로딩 (노출하지 않음) |
| `ad.open()` | 광고 노출 (로딩이 안 되어 있으면 로딩부터 진행) |
| `ad.close()` | 광고 닫기 시도. 사용자가 닫기 버튼을 누른 것과 동일하게 동작 |
| `ad.destroy()` | 강제로 광고를 닫고 제거 |
```ts
window.kakaoAdFit.cmd.push(() => {
const ad = window.kakaoAdFit.createInterstitialAd(adUnit, options);
ad.load();
ad.open();
ad.close();
ad.destroy();
});
```
**`ad.close()` 참고**: 광고 시청 중에 호출하면 닫기 버튼을 누른 것과 동일하게 동작합니다. 닫기 버튼 클릭 시 확인 팝업이 노출되는 경우, `ad.close()` 호출로 동일한 팝업을 노출할 수 있습니다.
## 이벤트
특정 시점마다 발생하는 이벤트에 리스너를 등록·해제할 수 있습니다.
### 이벤트 종류
| 이벤트 | 발생 시점 |
| --- | --- |
| `loaded` | 광고 로딩 완료 |
| `failed` | 광고 로딩 실패 |
| `opened` | 광고 노출 |
| `closed` | 광고 종료 |
| `rewarded` | **보상 지급 조건 충족** (보상형 광고 전용) |
| `unloaded` | 광고 리소스 해제 |
### 이벤트 등록·해제
```ts
function handleLoaded(): void {
/* 광고 로드 완료 시 동작 */
}
ad.addListener('loaded', handleLoaded);
ad.removeListener('loaded', handleLoaded);
```
### 보상 지급 시점
보상은 `rewarded` 이벤트에서 지급하는 것을 권장합니다. `closed` 에서 지급하면 시청 도중 이탈한 사용자에게도 보상이 지급되어 지급 누락이나 오지급이 발생할 수 있습니다.
세부 UX 정책은 [광고 UX 가이드: 보상 지급 시점](/docs/ads/ux-guideline#보상-지급-시점)을 참고하세요.
## 전체 예제
### 전면 광고
```html
```
### 보상형 광고
```html
```
## 참고 문서
* [광고 UX 가이드](/docs/ads/ux-guideline): 노출 정책, 보상 지급, Back Key 처리, 화면 복구 UX
* [애드핏 설정](/docs/ads/iaa-options): 광고단위 발급과 리워드 설정
* [CP별 리포트 API](/api-sdk/ads/cp-report)
* 기술 문의 — [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353)