Skip to main content
하나의 React Native 코드베이스로 Whop용 네이티브 iOS, Android, 웹 경험을 구축하세요. 앱은 Whop 모바일 앱 내부에서 직접 실행되며 네이티브 플랫폼 기능에 접근할 수 있습니다.

작동 방식

Whop은 React Native 앱을 여러 플랫폼에서 실행되는 경험으로 임베드합니다:
  • 모바일(iOS/Android): 앱이 Whop 모바일 앱 내부에서 네이티브로 실행되며 플랫폼과 완전히 통합됩니다
  • 웹: 앱이 브라우저에서 실행되며 플랫폼별 기능에 대한 자동 대체 동작이 제공됩니다
  • 유니버설 코드: 한 번 작성하면 플랫폼별 최적화와 함께 어디에나 배포할 수 있습니다
앱은 인증된 사용자 컨텍스트를 받으며 Whop SDK를 통해 API를 호출할 수 있습니다. 빌드 시스템은 모바일용 Metro와 웹용 esbuild를 사용하여 플랫폼별 번들링을 자동으로 처리합니다.

시작하기

시스템 요구 사항

시작하기 전에 시스템이 다음 요구 사항을 충족하는지 확인하세요: 확인하려면 node -v와 pnpm -v를 실행하세요.

앱 만들기

CLI를 사용하여 새 Whop React Native 앱을 만드세요:
다음 구조로 새 프로젝트가 설정됩니다:

환경 변수 구성하기

루트 디렉터리에 .env.local 파일을 만드세요:
Whop 개발자 대시보드에서 다음 자격 증명을 가져오세요:
  1. Whop 개발자 대시보드로 이동하세요
  2. 새 앱을 만들거나 기존 앱을 선택하세요
  3. 앱 설정에서 환경 변수를 복사하세요

뷰

프로젝트 구조
Whop 앱은 표시되는 위치에 따라 서로 다른 “뷰”를 사용합니다. 각 뷰는 인증된 컨텍스트를 props로 받습니다.

경험 뷰

경험 앱의 기본 뷰입니다. 사용자가 앱 콘텐츠와 상호 작용하는 곳입니다.
Props:
  • experienceId - 경험 ID
  • companyId - 이 경험을 소유한 계정
  • currentUserId - 인증된 사용자(로그인하지 않은 경우 null)
  • path - 배열 형태의 탐색 경로(예: ["courses", "123"])
  • params - 객체 형태의 쿼리 매개변수

대시보드 뷰

판매자가 비즈니스를 관리하는 계정 대시보드 통합용입니다.
Props:
  • companyId - 계정 ID
  • currentUserId - 인증된 사용자
  • path - 배열 형태의 탐색 경로
  • params - 쿼리 매개변수

디스커버 뷰(선택 사항)

사용자가 콘텐츠를 둘러보는 마켓플레이스/디스커버리 경험용입니다.

데이터 가져오기

Whop SDK 사용하기

이 예제는 더 이상 사용되지 않는 SDK 인터페이스를 사용합니다. 대체 React Native SDK가 출시되면 업데이트될 예정입니다.
Whop SDK는 클라이언트 측 데이터 가져오기에 바로 사용할 수 있습니다:
TanStack Query는 캐싱, 로딩 상태, 재요청을 자동으로 처리하므로 데이터 가져오기에 적합한 선택입니다.
일부 SDK 작업은 “서버 전용”이며 API에서 호출해야 합니다. 서버 측 실행이 필요한 메서드는 빠른 시작에서 확인하세요.

인증된 API 요청 보내기

서버 측 작업의 경우 API 라우트를 만들고 React Native 앱에서 호출하세요:
1

API 기본 URL 설정하기

개발자 대시보드의 Base URL에서 API 오리진을 구성하세요.
기본 URL
2

API 엔드포인트 만들기

SDK 구성은 빠른 시작을 참조하세요.
3

React Native에서 호출하기

apiOrigin을 사용하여 인증된 요청을 보내세요:
인증된 요청에는 반드시 apiOrigin을 사용해야 합니다. 이렇게 해야 요청이 적절한 인증 헤더와 함께 Whop의 프록시를 통과합니다.

예시: 경험에 대한 액세스 확인하기

이 서버 측 예제는 더 이상 사용되지 않는 SDK 인터페이스를 사용합니다. @whop/sdk를 사용한 최신 서버 측 토큰 검증은 인증을 참조하세요.

스타일링

색상 테마

React Native는 기기의 색상 구성표를 감지하는 useColorScheme 훅을 제공합니다. 이는 Whop 앱에서 자동으로 작동합니다:

Radix UI 색상 사용하기

자동 다크 모드를 지원하는 포괄적인 색상 시스템을 위해 Radix UI 색상과 함께 useColors 훅 패턴을 사용하세요:
사용법:

내부 탐색 API를 사용하여 화면 간에 이동하고 모달을 표시하세요:
Whop은 path와 params를 뷰 컴포넌트에 props로 전달합니다.

뒤로 가기

시트 또는 모달 표시하기

현재 라우트 가져오기


플랫폼별 기능

내비게이션 바의 제목과 설명을 구성하세요:

화면 방향

화면 방향을 제어하세요:

햅틱 피드백

모바일 기기에서 햅틱 피드백을 제공하세요:
사용 가능한 햅틱 유형:
  • "selection" - 가벼운 선택 피드백
  • "impactLight" | "impactMedium" | "impactHeavy" - 충격 피드백
  • "notificationSuccess" | "notificationWarning" | "notificationError" - 알림 피드백

로컬 캐싱

기기에 데이터를 로컬로 저장하세요:

호스트 앱 세부 정보

Whop 앱에 대한 정보를 가져오세요:

인앱 구매

앱 내에서 직접 결제를 받으세요:
결제 받기에 대한 전체 가이드는 결제 받기 문서를 참조하세요.

서드파티 라이브러리 사용하기

대부분의 React Native 라이브러리는 바로 작동합니다. 일반적인 라이브러리의 권장 버전은 다음과 같습니다:
새 라이브러리를 추가할 때는 React Native와 호환되는지 확인하세요. 일부 npm 패키지는 웹 전용이며 모바일 플랫폼에서 작동하지 않습니다.

배포하기

빌드 및 배포

ship 명령은 모든 플랫폼용으로 앱을 빌드하고 개발 빌드로 업로드합니다:
특정 플랫폼용으로 빌드하기:
ship 명령은 개발 빌드로 배포되므로 기존 프로덕션 앱에서 안전하게 실행할 수 있습니다. 라이브 사용자에게는 영향을 주지 않습니다.

개발 빌드와 프로덕션 빌드

개발 빌드:
  • pnpm ship으로 배포됩니다
  • Dev mode를 활성화한 경우에만 표시됩니다(휴대폰 흔들기)
  • 프로덕션 사용자에게 영향을 주지 않고 안전하게 테스트할 수 있습니다
  • 언제든지 배포할 수 있습니다
프로덕션 빌드:
  • 대시보드를 통해 개발 빌드에서 승격됩니다
  • 모든 사용자에게 표시됩니다
  • 승인/검토가 필요합니다
  • 승격 전에 테스트하세요

앱 미리 보기

개발 빌드를 배포한 후 기기에서 미리 보세요:
앱을 설치하는 QR 코드가 생성됩니다.
개발 빌드를 미리 보려면 휴대폰을 흔들어 Whop 앱에서 Dev mode를 활성화해야 합니다. 이렇게 하면 프로덕션이 아닌 빌드를 볼 수 있습니다.

빌드 명령

빌드 관리를 위한 추가 명령:

프로덕션으로 승격하기

  1. 개발 빌드를 배포하세요: pnpm ship
  2. Dev mode에서 테스트하세요(흔들어서 활성화)
  3. 앱 대시보드로 이동하세요
  4. Builds 탭으로 이동하세요
  5. 개발 빌드를 선택하세요
  6. Promote to Production을 선택하세요
프로덕션으로 승격
Whop이 앱을 검토하고 승인 후 모든 사용자에게 배포합니다.

롤백

빌드 화면에서 이전 프로덕션 빌드로 즉시 롤백하여 Whop 전체의 모든 사용자에게 라이브로 배포할 수도 있습니다.
롤백

명령줄 인터페이스 레퍼런스

@whop/react-native CLI는 앱을 빌드하고 배포하는 명령을 제공합니다:

명령

빌드 프로세스

pnpm ship을 실행하면 CLI는 다음을 수행합니다:
  1. 엔트리포인트 생성 - 뷰를 등록하는 플랫폼별 엔트리 파일을 만듭니다
  2. 코드 번들링:
    • 모바일(iOS/Android): Metro 번들러 + Hermes 바이트코드 컴파일러를 사용합니다
    • 웹: React Native Web 별칭과 함께 esbuild를 사용합니다
  3. 에셋 패키징 - 이미지 및 기타 에셋을 수집하고 최적화합니다
  4. Whop에 업로드 - 앱 대시보드에 개발 빌드를 만듭니다
  5. 설치 링크 생성 - 테스트용 QR 코드를 제공합니다

빌드 출력


문제 해결

개발 빌드가 표시되지 않음

문제: 개발 빌드를 배포했지만 앱에서 보이지 않습니다. 해결 방법: 휴대폰을 흔들어 Dev mode를 활성화하세요. 개발 빌드는 Dev mode가 활성화된 경우에만 표시됩니다.

빌드 실패

문제: Metro 또는 esbuild 오류로 빌드가 실패합니다. 해결 방법:
  • pnpm clean을 실행하여 빌드 캐시를 지우세요
  • 모든 종속성을 설치했는지 확인하세요: pnpm install
  • Node.js 버전을 확인하세요: node -v(22 이상이어야 함)
  • 뷰에 구문 오류가 있는지 확인하세요

API 요청이 작동하지 않음

문제: API 요청이 401 또는 인증 오류를 반환합니다. 해결 방법:
  • __internal_execSync("getAppApiOrigin", {})의 apiOrigin을 사용하고 있는지 확인하세요
  • .env.local에 WHOP_API_KEY가 설정되어 있는지 확인하세요
  • API 엔드포인트가 whopSdk.verifyUserToken(request.headers)를 호출하는지 확인하세요
  • 대시보드에 기본 URL이 올바르게 설정되어 있는지 확인하세요

뷰를 찾을 수 없음

문제: 빌드는 성공하지만 뷰가 렌더링되지 않습니다. 해결 방법:
  • src/views/에 뷰 파일이 있는지 확인하세요
  • 내보내기가 일치하는지 확인하세요: export function ExperienceView(props: ExperienceViewProps)
  • 뷰 파일이 .tsx 또는 .jsx로 끝나는지 확인하세요

라이브러리가 작동하지 않음

문제: 서드파티 라이브러리로 인해 모바일에서 충돌이 발생합니다. 해결 방법:
  • 라이브러리가 웹뿐 아니라 React Native를 지원하는지 확인하세요
  • 라이브러리 사용하기 섹션의 권장 버전을 사용하세요
  • 라이브러리에 네이티브 모듈이 필요한지 확인하세요(필요하지만 권장 목록에 없다면 지원되지 않습니다)

플랫폼별 문제

문제: 앱이 한 플랫폼에서는 작동하지만 다른 플랫폼에서는 작동하지 않습니다. 해결 방법:
  • Platform.OS를 사용하여 플랫폼을 감지하고 대체 동작을 제공하세요
  • 프로덕션으로 승격하기 전에 모든 플랫폼에서 테스트하세요
  • 플랫폼별 API를 잘못 사용하고 있지 않은지 확인하세요

다음 단계