> ## 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.

# PixelSetupElement

> Whop Pixel을 설치하고 전환 이벤트를 연결합니다. 스니펫을 복사하고, 페이지에 설치되었는지 확인하고, 이벤트가 실행되는지 확인합니다. 인라인으로 마운트하거나 자체 오버레이 안에 마운트하세요.

> [!NOTE]
>
> 이 페이지는 `@whop/elements@1.10.0` 및 `@whop/elements-react@1.10.0`을 다룹니다.

*`v1.0.0`부터 지원.*

[`Websites`](https://docs.whop.com/ko/elements/latest/websites/overview) 안에 마운트됩니다. props와 콜백은 생성 옵션 또는 React props로 전달합니다.

> [!NOTE]
>
> 이 엘리먼트는 **인라인**(`create`)으로 마운트하거나 **모달** 오버레이(`createOverlay`)로 열 수 있습니다.

```tsx React theme={null}
import { WhopElements, Websites, PixelSetupElement } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Websites /* options */>
        <PixelSetupElement onRedirectUrlChanged={(e) => console.log(e)} onScanned={(e) => console.log(e)} onFinished={(e) => console.log(e)} onUrlSubmitted={(e) => console.log(e)} onVerifyLaunched={(e) => console.log(e)} onVerifyConnected={(e) => console.log(e)} onVerdict={(e) => console.log(e)} onEventVerified={(e) => console.log(e)} />
      </Websites>
    </WhopElements>
  );
}
```

```html JavaScript theme={null}
<script src="https://cdn.whop.com/elements/amber/elements.js" data-whop-elements></script>
<script type="module">
  const websites = window.WhopElements().websites.create({ /* options */ });
  websites.create('pixel-setup', {
    onRedirectUrlChanged: (e) => console.log(e),
    onScanned: (e) => console.log(e),
    onFinished: (e) => console.log(e),
    onUrlSubmitted: (e) => console.log(e),
    onVerifyLaunched: (e) => console.log(e),
    onVerifyConnected: (e) => console.log(e),
    onVerdict: (e) => console.log(e),
    onEventVerified: (e) => console.log(e)
  }).mount('#websites-pixel-setup');
</script>
```

예시 데이터입니다. [Playground 열기](https://docs.whop.com/ko/elements/latest/websites/overview#playground).

## Props

**accountId** `string`

이 픽셀을 소유한 계정 ID로, `biz_` 접두사가 붙습니다. 필수 항목이며 스니펫, 스캔, 초대가 모두 이 계정을 대상으로 실행됩니다. 기본값은 `""`입니다.

**accessToken** `string`

스캔과 개발자 초대에 사용하는 범위 지정 토큰입니다. 스캔에는 `company:basic:read`가 필요하고, “Invite a developer”에는 추가로 `authorized_user:create`가 필요하며, 이벤트 프리셋은 `company:balance:read`로 계정을 읽습니다(이 범위가 없어도 마법사는 일반 프리셋 목록으로 작동합니다). `destinationUrl`을 전달하지 않으면 빈 URL 필드에 계정의 광고 및 픽셀 트래픽에서 가져온 페이지도 제안됩니다. 이 읽기에는 `ad_campaign:basic:read`와 `stats:read`가 필요하며, 없으면 필드가 비어 있는 상태로 표시됩니다. 서버에서 `POST /api/v1/access_tokens`로 발급하고, 만료되기 전에 새 토큰을 설정하세요. 이 마법사를 자체적으로 여는 다른 엘리먼트(예: 광고 `campaign-creator`)는 자신의 토큰으로 이 호출을 실행하므로, 두 번째 토큰을 발급하지 말고 해당 토큰에 이 범위를 추가하세요. 이 엘리먼트는 다른 곳에서 설정한 자격 증명을 읽을 수 없습니다. 생략하면 호출에 시청자 자신의 세션이 사용되며, 이는 동일 출처에서만 응답합니다.

**destinationUrl** `string`

확인할 페이지로, 마운트 시 스캔됩니다. 비워 두면 마법사가 페이지를 요청합니다. 이벤트 단계의 "Verify live" 표시 여부도 이 값으로 결정됩니다. 이 버튼은 서버 측 스캔으로는 볼 수 없는 이벤트를 포착하기 위해 계정 소유자가 자신의 퍼널을 직접 거치도록 안내하므로, 여기서 지정했거나 마법사에서 입력한 대상이 있을 때만 표시됩니다. 부팅 시 한 번만 읽으므로 `update()`로 진행 중에 대상을 바꿀 수 없습니다. 다른 페이지를 확인하려면 새로 마운트하세요. 기본값은 `""`입니다.

**eventName** `string`

선택 사항입니다. 해당 페이지에서 반드시 실행되어야 하는 이벤트(`lead`, `schedule`, `view_content`, …)로, 감지될 때까지 이벤트 단계가 진행되지 않습니다. 설정하지 않으면 모든 이벤트가 제공되며 필수 이벤트는 없습니다. Whop이 서버 측에서 기록하는 이벤트(`purchase`, `subscribe`, 체험판, 결제 단계)는 무시됩니다. 부팅 시 한 번만 읽습니다. 기본값은 `""`입니다.

**redirectUrl** `string`

이벤트가 대상 페이지 대신 리디렉션된 곳에서 실행되는 경우, 대상 페이지가 리디렉션하는 URL입니다. 계정 소유자가 마법사에서 직접 설정할 수도 있습니다. `redirectUrlChanged`를 수신하고 다음에 다시 전달하세요. 기본값은 `""`입니다.

**initialStep** `"events" | "install"`

마법사가 열리는 위치입니다. 설치 단계에서 열거나, 픽셀이 이미 설치되어 있고 전환 이벤트만 누락된 경우 바로 `events`로 엽니다. 기본값은 `"install"`입니다.

**showIntro** `boolean`

"why a pixel" 소개 화면에서 시작합니다. 계정 소유자가 이미 목적을 알고 있는 경우(예: 캠페인 시작 도중 이 화면으로 보내는 흐름)에는 끄세요. 그러면 마법사가 바로 설치 단계에서 열립니다. 기본값은 `true`입니다.

**showInviteDeveloper** `boolean`

"Invite a developer to install it" 경로를 제공합니다. 임베드를 사용하는 사람들이 그 뒤의 Whop 팀에 멤버를 초대해서는 안 되는 경우 숨기세요. 기본값은 `true`입니다.

**showOptimizePrompt** `boolean`

페이지 확인이 통과한 후 "your pixel is live" 화면을 표시하며, 다음 단계로 전환 이벤트 설정을 제안합니다. 계정 소유자가 이벤트 설정 자체를 위해 온 경우에는 끄세요. 그러면 확인이 통과했을 때 그냥 클릭해 넘길 화면에서 멈추지 않고 바로 이벤트로 이동합니다. 기본값은 `true`입니다.

**verifyFirst** `boolean`

설치 안내 대신 페이지 확인을 먼저 보여줍니다. URL 필드(및 제안 목록)가 맨 위에 표시되고, 설치 경로는 "Pixel not installed yet?" 토글 아래로 접히며, 헤더에는 "Verify your pixel"이 표시됩니다. 이미 픽셀이 있지만 기여가 집계되지 않는 이유를 알아보려는 계정 소유자를 위한 옵션입니다. `showIntro: false`와 함께 사용하세요. 기본값은 `false`입니다.

## 이벤트

생성 옵션 또는 React props로 콜백을 전달합니다.

### `onRedirectUrlChanged`

계정 소유자가 마법사에서 리디렉션 URL을 설정하거나 지웠습니다. 이 값을 저장해 두고 다음에 `redirectUrl`로 다시 전달하세요.

**payload** `object`

**properties**

**url** `string` *required*

### `onScanned`

픽셀 스캔이 완료되었습니다. 마법사가 확인하는 모든 URL에 대해 실행되므로 자체 설치 배지가 이를 따라갈 수 있습니다. `primary`는 설정 중인 페이지를 나타냅니다. 퍼널 검사기는 계정 소유자가 나열한 다른 페이지(다른 호스트 이름 포함)도 스캔하므로, 결과를 해당 사이트에 대한 것으로 취급하기 전에 이 값으로 확인하세요. `websites` 테이블을 정확하게 유지하기 위해 이 이벤트가 필요하지는 않습니다. 해당 핸들 아래에 마운트되어 있으면, 활성 상태가 확인된 사이트는 이미 대기 행을 갖게 됩니다.

**payload** `object`

**properties**

**url** `string` *required*

**status** `"installed" | "missing" | "unreachable"` *required*

**installed** `boolean` *required*

**primary** `boolean` *required*

### `onFinished`

Done 버튼이 눌렸습니다. 페이지를 직접 다시 확인하세요. 이 이벤트는 마법사가 끝났다는 의미일 뿐, 요구 사항이 충족되었다는 의미는 아닙니다.

### `onUrlSubmitted`

계정 소유자가 마법사 안에서 확인할 페이지를 지정했습니다(직접 입력했거나 제안된 페이지에서 선택). 마운트 시 대상이 제공되지 않은 경우에만 발생합니다.

**payload** `object`

**properties**

**url** `string` *required*

**source** `"typed" | "suggested"` *required*

### `onVerifyLaunched`

"Verify live"가 눌렸습니다. `popupBlocked`는 브라우저가 퍼널 창을 차단하여 확인 과정이 시작되지 않았음을 의미합니다.

**payload** `object`

**properties**

**url** `string` *required*

**popupBlocked** `boolean` *required*

### `onVerifyConnected`

퍼널 페이지가 마법사에 응답했습니다. 해당 페이지에 픽셀이 로드되었으며 확인 과정이 진행 중입니다.

**payload** `object`

**properties**

**url** `string` *required*

### `onVerdict`

Verify live 확인 과정이 끝났습니다. `ok`는 추적 누락이 없음을 의미하며, 그렇지 않으면 `gaps`에 확인 과정에서 발견된 누락 코드가 담깁니다.

**payload** `object`

**properties**

**url** `string` *required*

**ok** `boolean` *required*

**gaps** `string[]` *required*

**eventsCaptured** `number` *required*

### `onEventVerified`

계정 소유자가 "Verify live"로 퍼널을 거쳤고 이 이벤트가 실행되었습니다. 서버 측 스캔이 닿지 않는 곳에서도 이벤트가 연결되어 있다는 증거입니다.

**payload** `object`

**properties**

**url** `string` *required*

**event** `string` *required*

### `onLoaderStart`

로딩 스켈레톤이 처음 그려진 후, `onReady` 전에 실행됩니다.

### `onReady`

엘리먼트가 처음으로 완전히 그려진 후 실행됩니다.

### `onError`

엘리먼트가 로드에 실패하거나 충돌할 때 실행됩니다. 대체 화면은 계속 표시됩니다. 프로그래밍 방식으로 처리하려면 `code`를 사용하세요. `sourceKey`는 실패한 호스트 상태 소스를 식별합니다.

**e** `object`

**properties**

**message** `string` *required*

**code** `string`

**sourceKey** `string`

## 메서드

`create`가 반환한 핸들에서, 또는 React `ref`를 통해 호출합니다.

### `mount`

`target`에 엘리먼트를 마운트하고 로딩을 시작합니다. React 컴포넌트는 자동으로 마운트됩니다.

**매개변수**

**target** `string | HTMLElement` *required*

### `destroy`

엘리먼트를 제거하고 프레임과 구독을 해제합니다. 여러 번 호출해도 됩니다. React는 엘리먼트를 자동으로 제거합니다.

### `update`

마운트된 엘리먼트에 새 props를 병합합니다. React에서는 대신 컴포넌트 props를 변경하세요.

**매개변수**

**options** `Partial\<PixelSetupElementProps\>` *required*

## 스타일링

`appearance.classes`를 통해 다음 부분의 스타일을 지정합니다. 속성 이름은 카멜 케이스 또는 케밥 케이스를 사용하고 단위를 포함하세요. 페이지 스타일시트는 엘리먼트의 프레임에 적용되지 않습니다. 프레임워크는 각 선언을 삽입하기 전에 유효성을 검사합니다.

| 클래스 | 대상 |
| - | - |
| `.whop-PixelSetupSurface` | 픽셀 설정 마법사 루트 — 한 번에 한 단계씩 |

```ts theme={null}
const websites = whop.websites.create({
  appearance: {
    classes: {
      'whop-PixelSetupSurface': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

websites.update({
  appearance: {
    classes: { 'whop-PixelSetupSurface': { fontWeight: '700' } }
  }
});
```

React에서는 `appearance`를 `<Websites>`에 전달합니다. 전역으로 설정하려면 `WhopElements({ appearance })`를 사용하세요.
