> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Iframe SDK

> @whop/iframe SDK를 사용해 임베드된 앱에서 Whop과 통신하세요. 예를 들어 링크를 열거나 인앱 구매를 시작할 수 있습니다.

Whop은 iframe을 사용해 앱을 사이트에 임베드합니다. 이 SDK는 `window.postMessage`를 사용하는 요청-응답 API를 통해 Whop 애플리케이션과 타입 안전하게 통신하는 방법을 제공합니다.

이 패키지는 `window.postMessage`에 의존하므로 **클라이언트 컴포넌트** 또는 클라이언트 측 JavaScript에서만 작동합니다.

### 관련 패키지

* `@whop/iframe` - iframe SDK의 기본 패키지입니다.
* `@whop/react` - iframe SDK용 헬퍼를 포함한 Whop 앱용 React 래퍼입니다.

***

## 설정

`@whop/iframe` 패키지에서 내보내는 주요 함수는 `createSdk` 함수입니다. 이 함수를 호출하면 `window.on('message', ...)`를 사용해 메인 Whop 사이트에서 오는 메시지에 대한 리스너를 설정합니다. 이 함수는 `@whop/react`의 `WhopIframeSdkProvider` 컴포넌트를 통해서도 제공됩니다.

### React

React를 사용한다면 `@whop/react`의 `WhopIframeSdkProvider` 컴포넌트를 추가하여 모든 하위 컴포넌트에 iframe SDK를 제공하세요.

**1. 루트 레이아웃에 프로바이더 마운트하기**

```javascript theme={null}
// app/layout.tsx
import { WhopIframeSdkProvider } from "@whop/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode,
}) {
  return (
    <html lang="en">
      <body>
        <WhopIframeSdkProvider>{children}</WhopIframeSdkProvider>
      </body>
    </html>
  );
}
```

**2. 컴포넌트에서 iframe SDK 사용하기**

```javascript theme={null}
// components/example.tsx
import { useIframeSdk } from "@whop/react";

export const Example = () => {
  const iframeSdk = useIframeSdk();

  return (
    <button
      onClick={() => iframeSdk.openExternalUrl({ url: "https://example.com" })}
    >
      Open External URL
    </button>
  );
};
```

### 기타 프레임워크

다른 프레임워크에서는 `@whop/iframe`의 `createSdk` 함수를 사용해 iframe SDK 인스턴스를 만들 수 있습니다.

**1. iframe SDK 인스턴스 만들기**

```javascript theme={null}
// lib/iframe-sdk.ts
import { createSdk } from "@whop/iframe";

export const iframeSdk = createSdk({
  appId: process.env.NEXT_PUBLIC_WHOP_APP_ID,
});
```

**2. iframe SDK 인스턴스 사용하기**

```javascript theme={null}
// index.ts
import { iframeSdk } from "@/lib/iframe-sdk";

const navigationButtonElement = document.querySelector("button");

if (navigationButtonElement) {
  navigationButtonElement.addEventListener("click", () => {
    iframeSdk.openExternalUrl({ url: "https://example.com" });
  });
}
```

> [!TIP]
>
> 이제 SDK와 iframe이 설정되었습니다.

## 외부 링크 열기

iframe SDK를 초기화한 후에는 이를 사용해 외부 링크를 열 수 있습니다. 이렇게 하면 앱이 닫히고 새 웹사이트로 이동합니다.

```javascript React theme={null}
"use client";
import { useIframeSdk } from "@whop/react";

export default function Home() {
	const iframeSdk = useIframeSdk();

    function openLink() {
    	iframeSdk.openExternalUrl({ url: "https://google.com" });
    }

    return <button onClick={openLink}>Click me to open Google</button>;

}

```

```javascript Vanilla JS theme={null}
import { iframeSdk } from "@/lib/iframe-sdk";

const navigationButtonElement = document.querySelector("button");

if (navigationButtonElement) {
  navigationButtonElement.addEventListener("click", () => {
    iframeSdk.openExternalUrl({ url: "https://google.com" });
  });
}
```

### 사용자 프로필 열기

Whop 사용자 프로필을 표시하려면 `openExternalUrl` 메서드를 사용하고 `https://whop.com/@username` 형식의 프로필 페이지 링크를 전달하세요.

Whop 앱이 이를 가로채서 다른 페이지로 이동하는 대신 사용자 프로필이 담긴 모달을 표시합니다.

```javascript React theme={null}
"use client";
import { useIframeSdk } from "@whop/react";

export default function Home() {
	const iframeSdk = useIframeSdk();

    function openProfile() {
    	iframeSdk.openExternalUrl({ url: "https://whop.com/@j" });
    }

    return <button onClick={openProfile}>View Profile</button>;

}

```

```javascript Vanilla JS theme={null}
import { iframeSdk } from "@/lib/iframe-sdk";

const profileButtonElement = document.querySelector("button");

if (profileButtonElement) {
  profileButtonElement.addEventListener("click", () => {
    iframeSdk.openExternalUrl({ url: "https://whop.com/@j" });
  });
}
```

> [!NOTE]
>
> 사용자 이름 대신 사용자 ID를 사용할 수도 있습니다. 최종 링크는 다음과 같은
> 형태여야 합니다: `https://whop.com/@user_XXXXXXXX`

## 인앱 구매

iframe SDK는 앱 내에서 직접 인앱 구매를 시작하는 메서드를 제공합니다. 이를 통해 Whop의 체크아웃을 사용해 일회성 구매나 구독 결제를 받을 수 있습니다.

인앱 구매를 처리하려면 다음을 수행해야 합니다:

1. 서버에서 체크아웃 구성을 만듭니다(호환성 `plan` 필드의 변형 세부 정보와 메타데이터 포함)
2. iframe SDK의 `inAppPurchase` 메서드를 사용해 결제 모달을 엽니다
3. 응답을 처리하고 웹훅으로 결제를 검증합니다

```tsx React theme={null}
"use client";
import { useIframeSdk } from "@whop/react";
import { useState } from "react";

export default function PaymentButton() {
    const iframeSdk = useIframeSdk();
    const [paymentId, setPaymentId] = useState<string>();

    async function handlePurchase() {
        // 1. Create checkout configuration on server
        //    (in this example this is a nextjs server action, but it could also be a plain API route)
        const checkoutConfiguration = await createCheckoutConfiguration(/* can pass options here */);

        // 2. Open payment modal
        const res = await iframeSdk.inAppPurchase({
            planId: checkoutConfiguration.plan.id,
            id: checkoutConfiguration.id
        });

        if (res.status === "ok") {
            setPaymentId(res.data.receipt_id);
        } else {
            // handle errors
        }
    }

    return <button onClick={handlePurchase}>Purchase</button>;

}

```

```javascript Vanilla JS theme={null}
import { iframeSdk } from "@/lib/iframe-sdk";

const paymentButton = document.querySelector("button#payment-button");

paymentButton.addEventListener(
    "click",
    async function onPaymentButtonClick() {
        // 1. Create checkout configuration on server
        const checkoutConfiguration = await createCheckoutConfiguration(/* can pass options here */);

        // 2. Open payment modal
        const res = await iframeSdk.inAppPurchase({
            planId: checkoutConfiguration.plan.id,
            id: checkoutConfiguration.id
        });

        if (res.status === "ok") {
            const paymentId = res.data.receipt_id;
            // Send this id to your backend to validate, or rely on webhooks.
            // User has purchased the item, and it can be unlocked.
        } else {
            // handle errors
        }
    }
);
```

> [!NOTE]
>
> 체크아웃 구성 생성, 웹훅 처리, 결제 검증을 포함한 인앱 구매 설정 전체 가이드는
> [결제 받기 문서](https://docs.whop.com/ko/developer/guides/accept-payments.md)를 참고하세요.


## Related topics

- [Frosted UI](https://docs.whop.com/ko/developer/guides/frosted_ui.md)
- [스타일링 레퍼런스](https://docs.whop.com/ko/sdk/elements/styling-reference.md)
- [인증 및 API 키](https://docs.whop.com/ko/developer/guides/auth-scoping.md)
