loadFullScreenAd

기능 설명

통합 전면 광고를 미리 불러와요. Toss Ad를 우선 표시하고, 사용할 수 없는 환경에서는 자동으로 AdMob으로 전환돼서 안정적으로 광고를 노출할 수 있어요. 광고를 표시하기 전에 반드시 호출해야 해요.

토스앱 버전에 따라 다르게 동작해요:

토스앱 버전	지원 기능
5.239.0 이상	Toss Ad + AdMob 통합 (Toss Ad 우선, 불가능하면 AdMob으로 자동 전환)
5.227.0 이상 ~ 5.239.0 미만	AdMob 광고만 표시
5.227.0 미만	미지원

호출 전에 loadFullScreenAd.isSupported()로 지원 여부를 확인할 수 있어요.

타입

loadFullScreenAd(params: LoadFullScreenAdParams): () => void;

Params

type LoadFullScreenAdParams = {
  options: LoadFullScreenAdOptions;
  onEvent: (event: LoadFullScreenAdEvent) => void;
  onError: (error: unknown) => void;
};

type LoadFullScreenAdOptions = {
  /** 광고 그룹 ID예요. 앱인토스 콘솔에서 발급받은 값을 넣어주세요. */
  adGroupId: string;
};

type LoadFullScreenAdEvent = {
  type: "loaded";
};

Response

앱브릿지 콜백을 해제하는 함수(() => void)를 반환해요.

에러

광고 로드에 실패하면 onError 콜백으로 에러가 전달돼요. 미지원 버전에서 호출하면 onError로 에러가 전달되니, 호출 전에 isSupported()로 확인하세요.

예시 코드

import { Ads } from "@apps-in-toss/web-framework";

let isAdLoaded = false;

function prepareAd() {
  if (!loadFullScreenAd.isSupported()) {
    console.warn("현재 환경에서는 전면 광고를 사용할 수 없어요.");
    return;
  }

  const cleanup = loadFullScreenAd({
    options: { adGroupId: "AD_GROUP_ID" },
    onEvent: (event) => {
      if (event.type === "loaded") {
        console.log("광고 로드 완료");
        isAdLoaded = true;
        cleanup();
      }
    },
    onError: (error) => {
      console.error("광고 로드 실패:", error);
      cleanup();
    },
  });
}