> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/ads/loadfullscreenad.md).

# 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()`로 지원 여부를 확인할 수 있어요.

### 타입

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

**Params**

```ts
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()`로 확인하세요.

### 예시 코드

```js
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();
    },
  });
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/ads/loadfullscreenad.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.