Skip to main content
이 페이지는 @whop/elements@1.10.0 및 @whop/elements-react@1.10.0을 다룹니다.
Whop Elements는 자체 사이트에 삽입하는 호스팅형 테마 지원 UI 컴포넌트입니다. 각 엘리먼트는 Whop의 CDN에서 제공되는 격리된 프레임에서 렌더링됩니다. 가볍고 완전한 타입을 갖춘 패키지를 설치하면 엘리먼트 코드는 자동으로 최신 상태를 유지합니다.
Whop Elements는 iOS 앱에서 가져올 수 있는 테마 지원 UI 컴포넌트입니다. 단일 Swift SPM 패키지로 제공됩니다. 각 엘리먼트는 자체 데이터를 가져오고 자체 상태를 관리하는 일반 SwiftUI 뷰이므로, 잔액 화면은 네트워킹 레이어와 뷰 모델 대신 VStack 안의 뷰 몇 개로 구성됩니다. 패키지를 추가하고, SDK에 액세스 토큰을 가져오는 방법을 알려준 다음, 뷰 계층에 엘리먼트를 배치하세요.
Whop Elements는 React Native 앱에 바로 넣을 수 있는 테마 지원 UI 컴포넌트입니다. 웹 뷰가 아닌 실제 React Native 컴포넌트입니다. 결제 수단 타일, 주소 양식, 카드 필드는 모두 네이티브 입력이며, Apple Pay와 Google Pay는 플랫폼 자체의 시트를 엽니다. 패키지를 설치하고, SDK에 액세스 토큰을 가져오는 방법을 알려준 다음, 엘리먼트를 마운트하세요.

설치

Package.swift에 패키지를 추가하세요(또는 Xcode에서 File → Add Package Dependencies):
SDK를 설치합니다:

요구 사항

Content security policy

@whop/elements의 contentSecurityPolicy()는 전달한 환경에 대해 이 표의 모든 소스를 반환합니다. 페이지 측 작업에 대한 행은 프레임이 아닌 사용자의 페이지에서 실행됩니다. Apple Pay, Google Pay, PayPal 및 Plaid 은행 계좌 연결을 위해 엘리먼트가 로드하는 스크립트는 다른 회사에서 제공하며 이 행 외의 리소스를 로드할 수 있습니다. 각 제공업체의 Content Security Policy 가이드도 확인하세요.
엘리먼트는 cdn.whop.com에서 제공되는 프레임에서 렌더링됩니다. Apple Pay, Google Pay, PayPal 및 Plaid 은행 계좌 연결처럼 일부 작업은 사용자의 페이지에서 실행되며 페이지에서 api.whop.com을 호출합니다. CSP가 두 출처 중 하나라도 차단하면 엘리먼트 대신 빈 공간이 표시되거나 요청이 실패하며, 오류는 브라우저 콘솔에만 나타납니다.
모달 엘리먼트는 인라인 스타일로 뒤의 페이지를 어둡게 처리합니다. 인라인 스타일을 허용하지 않는 style-src에서는 페이지가 어두워지지 않지만 모달은 계속 작동합니다.

시작하기 전에

두 가지가 필요합니다:
  1. accountId. biz_ 접두사가 붙은 계정 ID, 또는 사용자 자신의 데이터에 대해서는 user_ 접두사가 붙은 사용자 ID입니다. 결제 화면은 대신 플랜이나 금액을 받으며, 각 엘리먼트 페이지에 필요한 항목이 안내되어 있습니다.
  2. 마운트하는 엘리먼트로 범위가 지정된 액세스 토큰을 생성하는 서버 엔드포인트.
Whop API 키를 브라우저 코드에 절대 넣지 마세요. API 키는 토큰을 생성하므로 브라우저의 개발자 도구를 여는 누구나 계정을 읽을 수 있습니다. 서버에서 토큰을 생성하고 토큰만 전송하세요.
서버는 계정과 엘리먼트에 필요한 스코프로 Create Access Token을 호출합니다:

요구 사항

시작하기 전에

두 가지가 필요합니다:
  1. accountId. biz_ 접두사가 붙은 계정 ID, 또는 사용자 자신의 잔액에 대해서는 user_ 접두사가 붙은 사용자 ID입니다.
  2. 계정에 대한 액세스 토큰을 생성하는 서버 엔드포인트. Whop API 키를 앱에 절대 포함하지 마세요. API 키는 토큰을 생성하므로 이를 추출하는 누구나 계정을 읽을 수 있습니다. 서버에서 토큰을 생성하고 토큰만 반환하세요.
user_… 태그는 사용자 자신의 데이터를 읽으므로 토큰 대신 사용자 OAuth(WhopSDK.configureWithOAuth)를 사용합니다. 채팅 뷰도 마찬가지입니다.서버는 계정과 엘리먼트에 필요한 스코프로 Create Access Token을 호출합니다:

요구 사항

어느 iOS 종속성 관리자든 사용할 수 있습니다. 패키지는 ios/Package.swift와 podspec을 모두 제공하며, 툴체인이 그중 하나를 선택합니다. React Native의 Swift Package Manager 자동 링커는 Package.swift를 우선하므로 이미 SPM을 사용하는 앱은 podspec의 영향을 받지 않습니다. 현재 모든 Expo 앱을 포함하여 CocoaPods를 사용하는 앱은 podspec을 통해 링크되며 추가 작업이 필요하지 않습니다. Package.swift는 0.87에서 처음 제공된 헤더 전용 XCFramework 두 개를 링크하므로 SPM에서는 React Native 최소 버전이 더 높습니다.
네이티브 코드는 React Native Codegen으로 생성된 Swift와 Kotlin입니다. Objective-C나 Java를 직접 편집할 필요가 없으며, 설치할 네이티브 피어 종속성도 없습니다.

시작하기 전에

두 가지가 필요합니다:
  1. accountId. biz_ 접두사가 붙은 회사 ID입니다.
  2. 해당 계정에 대한 액세스 토큰을 발급하는 서버 엔드포인트. Whop API 키를 앱에 절대 포함하지 마세요. API 키는 토큰을 생성하므로 이를 추출하는 누구나 계정으로 행동할 수 있습니다. 서버에서 토큰을 발급하고 토큰만 반환하세요.
서버는 Create Access Token을 호출하고 결과를 getToken에 다시 전달합니다.

첫 번째 엘리먼트 마운트하기

완전한 앱입니다. configure는 실행 시 한 번 실행되며, 완료될 때까지 엘리먼트는 스피너를 렌더링하므로 경쟁 상태가 발생하지 않습니다:
완전한 체크아웃입니다. <WhopElements>는 토큰 리졸버를, <Payments>는 청구를 보유하며, 그 사이의 엘리먼트가 결제 정보를 수집합니다:
스크립트 태그 대신 npm을 사용하고 싶으신가요? loadWhop()은 같은 호스팅 스크립트를 삽입하고 전역 생성자를 resolve합니다:

인증

핸들을 생성할 때 accessToken을 전달합니다. 엘리먼트마다 토큰을 하나씩 사용하지 말고 핸들 전체에 토큰 하나를 사용하세요. 핸들은 그 아래의 모든 엘리먼트에 해당 토큰을 전송하므로, 필요한 모든 스코프를 하나의 토큰에 요청하세요. 각 엘리먼트 페이지에 해당 엘리먼트가 읽는 스코프가 나열되어 있습니다.
토큰은 SDK가 호출하는 콜백이 아니라 직접 설정하는 값입니다. 만료되기 전에 새 토큰을 설정하세요:
accessToken을 생략하면 요청에 대신 사용자의 세션 쿠키가 사용됩니다. 이는 whop.com에서만 작동합니다. API는 교차 출처 프리플라이트에 Access-Control-Allow-Credentials를 보내지 않으므로, 자체 도메인의 페이지에는 대체할 세션이 없어 토큰을 전달해야 합니다.

전역 구성

생성 시 전달하는 모든 항목은 해당 인스턴스에서 생성된 모든 엘리먼트 그룹에 적용됩니다(핸들 자체의 옵션으로 그룹별로 재정의할 수 있습니다):
Appearance
모든 엘리먼트의 시각적 사용자 지정입니다. theme(라이트/다크 + 팔레트), variables(CSS 사용자 지정 속성), classes(파트별 스타일 선언)를 포함합니다. 색 구성표는 엘리먼트가 처음 그려지기 전에 적용되므로 어두운 페이지가 밝게 깜박이지 않습니다. Appearance를 참고하세요.
string
엘리먼트 UI 텍스트의 로케일입니다. 앱에 빌드된 로케일 중 하나여야 하며, 그 외의 값은 기본 로케일로 대체됩니다. 기본값은 "en"입니다."en", "es", "zh", "nl", "pt", "de", "hu", "it", "fr", "ja", "pl", "tr" 중 하나입니다.
"production" | "sandbox"
엘리먼트가 통신하는 Whop API 환경입니다. "sandbox"는 샌드박스 API를 대상으로 합니다(테스트 데이터, 실제 돈은 이동하지 않음). 환경을 선택하는 것이 구매자가 입력한 내용을 엘리먼트가 보내는 위치를 변경하는 유일한 방법이며, 두 환경 모두 Whop 자체 환경입니다. 샌드박스 환경은 아직 정식 출시되지 않았습니다. 기본값은 "production"입니다.
boolean
엘리먼트가 페이지에 토스트 알림을 표시할 수 있는지 여부입니다. 토스트 알림은 오른쪽 하단에 렌더링되는 짧은 상태 메시지(“Payment method added”, “Payment failed”)입니다. 완전히 끄려면 false로 설정하세요. 기본값은 true입니다.
boolean
Whop 픽셀을 건너뜁니다. 기본적으로 엘리먼트는 아직 Whop 광고 픽셀이 실행되지 않는 페이지에 픽셀을 로드하며, 엘리먼트가 작동하는 계정(엘리먼트 그룹의 accountId 또는 체크아웃 플랜의 판매자)으로 범위를 지정합니다. 또한 엘리먼트 분석을 픽셀의 방문자 ID와 연결합니다. 이는 Whop의 ID 그래프에서 엘리먼트 활동을 광고 어트리뷰션 데이터와 결합할 수 있게 하는 일회성 ID 연결입니다. 둘 다 하지 않으려면 true로 설정하세요. 사용 분석 자체에는 영향을 주지 않습니다(핸들별로 analytics: false로 끌 수 있습니다). 기본값은 false입니다.
React에서는 같은 객체를 <WhopElements appearance={…} locale={…}>로 전달합니다.toasts 전역 설정은 이 페이지에서 실제로 작동합니다. 아래 버튼은 엘리먼트가 사용하는 것과 같은 경로로 토스트를 보내며, 이 페이지의 appearance로 테마가 적용됩니다:

엘리먼트가 처리하는 것과 직접 담당하는 것

각 엘리먼트는 자체 데이터를 가져오고 자체 로딩, 빈 상태, 오류 상태를 렌더링합니다.탐색과 저장은 직접 처리합니다. 엘리먼트는 선택과 결과를 이벤트로 보고하며, 데이터베이스에 절대 기록하지 않습니다.예외는 페이지를 벗어나는 흐름입니다. 엘리먼트가 returnUrl을 받는 경우 탭을 해당 위치로 이동시키므로 구매자가 페이지를 벗어날 수 있습니다. 구매자는 외부 단계가 성공한 후뿐만 아니라 실패하거나 중단된 후에도 그곳에 도착하며, URL에는 status(succeeded, failed, canceled)와 시도 ID가 추가됩니다. 따라서 returnUrl 페이지는 성공 메시지를 표시하기 전에 status를 읽어야 합니다. 주문 이행은 브라우저 콜백이 아니라 웹훅에서 처리하세요.엘리먼트는 프레임에서 실행되므로 직렬화 가능한 값만 경계를 넘을 수 있습니다. 공유 DOM이 없으며 객체 동일성은 유지되지 않습니다.

문제 해결

사용 가능한 엘리먼트

Payments

plan_ ID 또는 인라인 통화와 금액으로 결제를 수금하거나, mode: "setup"으로 청구 없이 결제 수단을 저장합니다.

Verifications

계정의 신원 정보를 수집하고 인증합니다.

Checkout

Whop 체크아웃 세션 API를 기반으로 하나 이상의 플랜에 대한 전체 호스팅 체크아웃을 구동합니다. 항목별 가격 요약, 프로모션 코드, 구매자가 결제하는 통화, 그리고 전체 결제 수집 화면(내부에 구성된 결제 엘리먼트)을 포함합니다.

Ads

광고 계정입니다.

Tracking

계정의 추적 대상 오디언스입니다. 픽셀이 확인한 모든 사람과 그들이 수행한 모든 이벤트를 포함합니다.

Wallet

계정의 자금 관련 화면을 구동합니다.

Websites

계정의 웹사이트입니다. whop.site에 구축된 모든 사이트와 Whop 픽셀이 보고하는 모든 도메인을 도메인별 트래픽 및 귀속 수익과 함께 표시합니다.

Dashboard

사이트에 삽입된 계정 자체의 대시보드 화면입니다.

Delivery

비즈니스를 위한 고객 배송 추적입니다.

Chat

채널 목록과 메시지 검색을 갖춘 실시간 채팅입니다.

다음 단계

인증

getToken()은 유일한 통합 지점이며, SDK는 토큰이 만료되기 전에 다시 이를 호출합니다. 따라서 토큰을 캐시하지 말고 매번 새 토큰을 반환하세요:
엘리먼트보다 상위의 아무 곳에서나 한 번 구성하세요. WhopSDK는 프로세스 전역이므로 계정이 변경될 때만 다시 호출하면 됩니다:
채팅과 DM은 계정 대신 OAuth를 통해 사용자를 인증합니다: WhopSDK.configureWithOAuth(appId:).

테마

.whopTheme(_:)는 SwiftUI 환경을 통해 전파되므로 한 번의 호출로 그 아래의 모든 엘리먼트에 테마가 적용됩니다. 6가지 역할이 있으며 각각 WhopTint입니다:
기본값은 accent: .blue, neutral: .gray, danger: .red, info: .sky, success: .green, warning: .amber입니다. WhopTheme.default는 이 6가지 모두입니다. 뷰는 시스템의 라이트/다크 모드를 자동으로 따릅니다.

엘리먼트가 처리하는 것과 직접 담당하는 것

각 뷰는 자체 데이터를 가져오고 재시도를 포함한 자체 로딩, 빈 상태, 오류 상태를 렌더링합니다. 탐색은 직접 담당합니다. 선택 콜백은 값을 전달할 뿐 화면을 push하지 않습니다.

문제 해결

iOS에서 사용 가능

각 페이지에서 실시간 시뮬레이터를 제공하는 지갑 뷰:WhopChatView와 WhopDMsListView는 사용자 인증 채팅을 위해 같은 패키지에 포함되어 있습니다. README를 참고하세요.

iOS에서 결제

결제 엘리먼트는 Elements 모듈을 제공하는 별도 패키지 whopio/elements-swift에서 제공됩니다. 지갑 SDK의 모듈은 WhopElements이므로 두 패키지를 함께 설치할 수 있습니다:
모듈은 WhopElements가 아니라 Elements이므로 import Elements 한 줄만 바뀝니다. 설정 방식도 다르며, SwiftUI의 구조를 따라 나뉩니다. 구성은 앱 루트에서 상속되고, 하나의 청구는 하나의 스코프입니다. 확인 토큰은 구매자가 입력한 내용으로 발급되어 서버에서 확인되므로 토큰이 필요하지 않습니다:
카드 데이터는 PCI로 격리된 호스팅 입력으로 수집되며 앱 프로세스에 절대 들어오지 않습니다. 모든 스타일은 .whopTheme(_:)가 아닌 .whopElementsAppearance(_:)로 지정하세요.

인증

getToken은 유일한 통합 지점이며, SDK는 모든 요청 전에 이를 호출합니다. 따라서 토큰을 캐시하지 말고 새 토큰을 반환하세요:
자격 증명이 필요 없는 엘리먼트는 이 없이도 작동하므로 백엔드를 연결하기 전에 카드 양식을 렌더링할 수 있습니다.

결제 받기

수집과 확인은 분리되어 있으며, 이는 의도된 설계입니다. 앱은 카드 번호를 절대 보지 않고, 서버는 클라이언트를 절대 신뢰하지 않습니다.
  1. 엘리먼트가 수집합니다. 카드 번호는 코드를 거치지 않고 PCI로 격리된 입력에서 바로 토큰으로 전달됩니다.
  2. createConfirmationToken()은 자체 백엔드로 안전하게 보낼 수 있는 확인 토큰을 반환합니다.
  3. 백엔드가 Whop API로 결제를 확인합니다.
  4. API가 결제에 구매자의 추가 조치가 필요하다고 응답하면, 해당 client_secret을 handleNextAction()에 전달하세요. SDK가 3D Secure 또는 리디렉션 단계를 실행합니다.

리디렉션과 3D Secure

앱 외부 단계는 WebView가 아닌 시스템 브라우저(iOS에서는 ASWebAuthenticationSession, Android에서는 Custom Tabs)에서 열리므로, 발급사의 페이지는 앱의 신뢰 경계 밖에 머물고 쿠키도 앱의 쿠키 저장소 밖에 유지됩니다.<Payments>의 returnUrl을 직접 호스팅하는 https URL로 설정하세요. API는 https 또는 루프백 외에는 모두 거부하므로(PaymentsApi::ValidateReturnUrl) 사용자 지정 앱 스킴은 여기서 작동하지 않습니다. 하지만 필요하지도 않습니다. handleNextAction은 앱으로 돌아오는 딥 링크를 기다리는 대신 결제가 안정될 때까지 폴링하고 브라우저를 직접 닫습니다.

Apple Pay 및 Google Pay

플랫폼이 시트를 표시할 수 있으면 지갑 타일이 나타나며, 둘 다 별도 설정이 필요 없습니다. Apple Pay는 Whop 계정에 등록된 판매자를 사용하므로 앱에 판매자 식별자나 Xcode capability가 필요하지 않습니다. <Payments>의 googlePayMerchantName은 시트에 표시되는 이름만 설정합니다.

테마

<WhopElements>의 appearance는 웹 엘리먼트와 같은 theme 객체로 그 아래의 모든 엘리먼트에 테마를 적용합니다. Appearance를 참고하세요.

엘리먼트가 처리하는 것과 직접 담당하는 것

각 엘리먼트는 자체 데이터를 가져오고 자체 로딩, 빈 상태, 오류 상태를 렌더링합니다. 탐색과 제출은 직접 담당합니다. 엘리먼트는 onChange를 통해 보고하며 화면을 push하거나 백엔드를 호출하지 않습니다.

문제 해결

React Native에서 사용 가능

결제 엘리먼트:체크아웃 엘리먼트:
  • ExpressCheckoutElement: <Checkout> 아래에서 체크아웃 전체를 결제하는 한 번의 Apple Pay 또는 Google Pay 탭