애드핏 광고 SDK

애드핏 광고 SDK 로 파트너사 게임에서 전면 광고와 보상형 전면 광고를 노출하는 방법입니다.
두 광고는 설치·노출 제어·이벤트가 동일하며, 인스턴스를 만드는 팩토리 메서드와 보상 처리만 다릅니다.

관련 가이드: 광고 UX 가이드, 애드핏 설정

신규 연동이라면

게임플레이 JS SDK가 광고 SDK 를 내부에서 다루므로 Gameplay.* 호출만으로 전면·보상형 광고를 노출할 수 있습니다.
이 문서는 애드핏 광고 SDK 를 직접 연동하는 방식입니다.

두 방식을 동시에 구성하는 것은 권장하지 않습니다.
자세한 내용은 SDK 연동 방식 선택을 참고하세요.
광고단위 발급은 방식과 무관하게 파트너사가 직접 진행합니다.

SDK 설치 필수

광고를 노출할 페이지에 아래 스크립트를 삽입합니다.

html

<script
  async
  type="text/javascript"
  charset="utf-8"
  src="https://t1.kakaocdn.net/kas/static/ba.min.js"></script>

페이지 메타태그 설정 필수

모바일 브라우저에서 광고를 상단 내비게이션 영역까지 자연스럽게 표시하려면, 광고를 노출할 페이지 <head> 의 viewport 메타태그에 viewport-fit=cover 를 지정합니다.

html

<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />

기존 viewport 메타태그가 있다면 새 태그를 추가하지 않고 content 값에 viewport-fit=cover 만 덧붙입니다.

타입 정의

SDK는 브라우저 어디서든 접근할 수 있는 window.kakaoAdFit 객체로 제공됩니다.
TypeScript 프로젝트에서는 아래처럼 window.kakaoAdFit 타입을 선언하면 이후 예제를 그대로 컴파일할 수 있습니다.

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

<script>
  window.kakaoAdFit = window.kakaoAdFit || {cmd: []};
  window.kakaoAdFit.cmd.push(async () => {
    const adUnit = '광고단위 ID'; // 발급받은 광고단위 ID
    const safeAreaInset = await window.kakaotalkGamePlay.getSafeArea();
    const options = {safeAreaInset};

    // 전면 광고
    const ad = window.kakaoAdFit.createInterstitialAd(adUnit, options);

    // 보상형 전면 광고
    const rewardedAd = window.kakaoAdFit.createRewardedInterstitialAd(adUnit, options);
  });
</script>

생성 이후의 메서드와 이벤트는 두 유형이 같습니다.
보상형 광고에만 rewarded 이벤트가 추가됩니다.

옵션

팩토리 메서드의 두 번째 인자로 AdFitAdOptions 를 전달합니다.
아래 옵션들은 함께 지정할 수 있습니다.

옵션	용도
`ctag`	채널 CP 수집
`safeAreaInset`	게임웹뷰가 제공하는 Safe Area 값 전달 (단위: px). 리워드·전면형 광고 운영 시 반드시 적용

채널 CP 수집 필수

채널 CP 를 수집하려면 ctag 를 지정합니다.

게임별 광고 지표를 구분하려면 ctag의 CPID와 채널 ID를 정확하게 설정해야 합니다.

주의사항

게임별 광고 수익 통계를 지원하려면 ctag.cp의 CPID를 게임플레이 파트너센터오픈 예정에 등록한 게임 코드와 동일하게 설정해야 합니다.
값이 다르거나 누락되면 광고 수익이 해당 게임과 연결되지 않으므로 반드시 설정하세요.

값	설정 기준
CPID (`cp`)	게임플레이 파트너센터오픈 예정에 등록한 게임 코드와 동일한 값을 입력합니다. 메타데이터 API로 게임을 등록했던 파트너사는 그 `code` 값을 그대로 유지합니다.
채널 ID (`channel`)	카카오에서 발급한 값을 입력합니다. 발급값 확인이 필요한 경우 카카오 담당자에게 문의하세요.

게임마다 CPID가 다르므로 게임별 광고 SDK 인스턴스에 정확한 값을 매핑합니다.

const safeAreaInset = await window.kakaotalkGamePlay.getSafeArea();

const options: AdFitAdOptions = {
  ctag: {
    cp: '파트너사가 설정한 게임 코드와 동일한 CPID',
    channel: '카카오에서 발급한 채널 ID',
  },
  safeAreaInset,
};

const ad = window.kakaoAdFit.createInterstitialAd(adUnit, options);

Safe Area 설정 필수

주의사항

보상형 전면 광고와 전면 광고의 광고단위를 적용할 때는 safeAreaInset 설정이 반드시 필요합니다.
게임웹뷰의 전체 화면 사용 여부와 관계없이 두 광고 상품을 운영하면 모두 적용해야 합니다.

게임웹뷰 SDK의 getSafeArea()가 반환한 top, bottom, left, right 값을 가공하지 않고 safeAreaInset으로 그대로 전달하세요.
값이 0인 방향도 생략하지 말고 0으로 전달합니다.

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()`	강제로 광고를 닫고 제거

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`	광고 리소스 해제

이벤트 등록·해제

function handleLoaded(): void {
  /* 광고 로드 완료 시 동작 */
}

ad.addListener('loaded', handleLoaded);
ad.removeListener('loaded', handleLoaded);

보상 지급 시점

보상은 rewarded 이벤트에서 지급하는 것을 권장합니다.
closed 에서 지급하면 시청 도중 이탈한 사용자에게도 보상이 지급되어 지급 누락이나 오지급이 발생할 수 있습니다.

세부 UX 정책은 광고 UX 가이드: 보상 지급 시점을 참고하세요.

전체 예제

전면 광고

html

<script
  async
  type="text/javascript"
  charset="utf-8"
  src="https://t1.kakaocdn.net/kas/static/ba.min.js"></script>

<div>
  <button id="showAdButton">광고 보기</button>
</div>

<script>
  window.kakaoAdFit = window.kakaoAdFit || {cmd: []};
  window.kakaoAdFit.cmd.push(async () => {
    const adUnit = '광고단위 ID';
    const safeAreaInset = await window.kakaotalkGamePlay.getSafeArea();
    const ad = window.kakaoAdFit.createInterstitialAd(adUnit, {safeAreaInset});
    ad.load();

    document.getElementById('showAdButton').addEventListener('click', () => {
      ad.open();
    });
  });
</script>

보상형 광고

html

<script
  async
  type="text/javascript"
  charset="utf-8"
  src="https://t1.kakaocdn.net/kas/static/ba.min.js"></script>

<div>
  <button id="showRewardedAdButton">보상형 광고 보기</button>
</div>

<script>
  window.kakaoAdFit = window.kakaoAdFit || {cmd: []};
  window.kakaoAdFit.cmd.push(async () => {
    const adUnit = '광고단위 ID';
    const safeAreaInset = await window.kakaotalkGamePlay.getSafeArea();
    const ad = window.kakaoAdFit.createRewardedInterstitialAd(adUnit, {safeAreaInset});
    ad.load();

    document.getElementById('showRewardedAdButton').addEventListener('click', () => {
      ad.open();
    });

    function giveReward() {
      /* 보상 적용 로직 */
    }

    ad.addListener('rewarded', () => {
      giveReward();
    });
  });
</script>

참고 문서

광고 UX 가이드: 노출 정책, 보상 지급, Back Key 처리, 화면 복구 UX
애드핏 설정: 광고단위 발급과 리워드 설정
CP별 리포트 API
기술 문의 — 카카오디벨로퍼스 데브톡

애드핏 광고 SDK ​

SDK 설치 필수 ​

페이지 메타태그 설정 필수 ​

타입 정의 ​

인스턴스 생성 필수 ​

옵션 ​

채널 CP 수집 필수 ​

Safe Area 설정 필수 ​

광고 노출 제어 ​

이벤트 ​

이벤트 종류 ​

이벤트 등록·해제 ​

보상 지급 시점 ​

전체 예제 ​

전면 광고 ​

보상형 광고 ​

참고 문서 ​

애드핏 광고 SDK

SDK 설치 필수

페이지 메타태그 설정 필수

타입 정의

인스턴스 생성 필수

옵션

채널 CP 수집 필수

Safe Area 설정 필수

광고 노출 제어

이벤트

이벤트 종류

이벤트 등록·해제

보상 지급 시점

전체 예제

전면 광고

보상형 광고

참고 문서