showFullScreenAd

loadFullScreenAd로 미리 로드된 전면 광고를 사용자에게 노출합니다. loadFullScreenAd의 loaded 이벤트를 수신한 후에 호출하세요. GoogleAdMob과 별개의 전면 광고 네임스페이스입니다.

시그니처

showFullScreenAd는 @apps-in-toss/web-framework에서 직접 export됩니다.

import { showFullScreenAd } from '@apps-in-toss/web-framework';

declare const showFullScreenAd: ((args: {
  onEvent: (data: ShowFullScreenAdEvent) => void;
  onError: (error: Error) => void;
  options?: ShowFullScreenAdOptions;
}) => () => void) & {
  isSupported: () => boolean;
};

interface ShowFullScreenAdOptions {
  adGroupId: string;
}

type ShowFullScreenAdEvent =
  | { type: 'requested' }
  | { type: 'clicked' }
  | { type: 'dismissed' }
  | { type: 'failedToShow' }
  | { type: 'impression' }
  | { type: 'show' }
  | { type: 'userEarnedReward'; data: { unitType: string; unitAmount: number } };

파라미터

이름	타입	필수	설명
args.onEvent	(data: ShowFullScreenAdEvent) => void	✓	광고 노출 이벤트 핸들러. requested, clicked, dismissed, impression, show, failedToShow, userEarnedReward 이벤트를 수신합니다.
args.onError	(error: Error) => void	✓	광고 노출 실패 시 호출되는 에러 핸들러.
args.options	ShowFullScreenAdOptions	—	광고 옵션. adGroupId를 포함합니다.
args.options.adGroupId	string	—	loadFullScreenAd에 사용한 것과 동일한 광고 그룹 단위 ID.

반환값

• () => void — cleanup 함수. 이벤트 구독을 해제합니다.

권한

권한이 필요하지 않습니다 — showFullScreenAd는 별도의 PermissionName에 바인딩되지 않습니다. 권한이 필요한 다른 네임스페이스의 일반적인 처리 흐름은 Guides — 권한 처리 패턴을 참고하세요.

예제

최소 예제

import { showFullScreenAd } from '@apps-in-toss/web-framework';

showFullScreenAd({
  onEvent: (event) => {
    console.log('광고 이벤트', event.type);
  },
  onError: (error) => {
    console.error('광고 노출 실패', error);
  },
});

실전 예제 — 광고 닫힘 후 보상 처리

import { loadFullScreenAd, showFullScreenAd } from '@apps-in-toss/web-framework';
import { useCallback, useEffect, useState } from 'react';

const AD_GROUP_ID = 'ad-group-id-here';

function RewardAdSection() {
  const [adReady, setAdReady] = useState(false);
  const [earned, setEarned] = useState(false);

  useEffect(() => {
    if (!loadFullScreenAd.isSupported()) return;

    const cleanup = loadFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        if (event.type === 'loaded') setAdReady(true);
      },
      onError: console.error,
    });

    return cleanup;
  }, []);

  const handleShow = useCallback(() => {
    if (!showFullScreenAd.isSupported()) return;

    showFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        switch (event.type) {
          case 'userEarnedReward':
            setEarned(true);
            console.log('보상 획득', event.data);
            break;
          case 'dismissed':
            if (earned) console.log('보상 지급 처리 완료');
            break;
        }
      },
      onError: console.error,
    });
  }, [earned]);

  return (
    <button type="button" onClick={handleShow} disabled={!adReady}>
      보상형 전면 광고 보기
    </button>
  );
}

직접 실행해 보기

sdk-example의 Ads 페이지에서 FullScreen Ad를 직접 실행해 볼 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• loadFullScreenAd — 전면 광고를 미리 로드합니다. 반드시 먼저 호출해야 합니다.
• GoogleAdMob.showAppsInTossAdMob — Google AdMob 전면 광고 노출 함수.

관련 가이드

• Guides — 광고 통합 패턴 — 라이프사이클·클린업·환경 가드를 한 곳에 정리한 가이드.

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.