SubSovereign on React Native — 통합 가이드

이 가이드는 @subsovereign/react-native (sdk-react-native/)를 다룹니다. 이 패키지는 데이터 클라이언트와 네이티브 결제 화면(페이월) 렌더러를 하나로 묶은 패키지입니다. SubSovereign 대시보드에서 디자인한 페이월이 iOS, Android, 웹, React, Flutter SDK와 동일한 설정을 사용해 네이티브 RN 프리미티브(View/Text/Pressable)로 렌더링됩니다.

React Native에서 이미 @subsovereign/js-sdk를 사용 중이신가요? 그대로 사용하셔도 됩니다(웹 & React Native 가이드 참고). 이 패키지는 네이티브 <Paywall> 컴포넌트와 네이티브 의존성 없이 순수 fetch를 사용하는 데이터 클라이언트를 추가로 제공합니다.

시작하기 전에

SubSovereign 서버가 실행 중이어야 하고, 대시보드에 앱이 등록되어 있어야 합니다(**appId**와 SDK 역할의 API 키 포함). 또한 스토어 상품과 연결된 액세스 레벨(예: pro)과 게시된 페이월이 필요합니다.

1단계 — 설치

이 패키지는 sdk-react-native/에 위치하며 아직 npm에 등록되어 있지 않습니다. 경로 또는 git 의존성으로 추가하거나 폴더를 프로젝트에 직접 복사하세요:

npm install ./sdk-react-native   # path dependency while it's pre-npm

아래 패키지들은 선택 사항으로, 설치되어 있으면 자동으로 사용됩니다(필수 의존성이 아님):

npx expo install expo-linear-gradient   # gradient paywall backgrounds
npm install react-native-video          # hero video (falls back to image without it)

2단계 — 앱 시작 시 한 번만 설정

import { SubSovereign } from '@subsovereign/react-native';

SubSovereign.configure({
  apiKey:  'YOUR_SDK_KEY',
  appId:   'your-app-id',
  baseUrl: 'https://subs.yourdomain.com/api/v1', // YOUR self-hosted server
  userId:  currentUser.id,                        // your own stable user id
  locale:  'en',
});

3단계 — 사용자의 접근 권한 확인

const result = await SubSovereign.checkEntitlements();
if (result.hasAccess) showPremiumContent();
else showPaywall();

try/catch로 감싸세요. 오류가 발생하면 마지막으로 알려진 접근 권한을 유지하고 나중에 다시 시도하세요. 네트워크 오류 한 번으로 결제한 사용자를 절대 차단해서는 안 됩니다.

4단계 — 페이월 표시 및 구독 판매

import { Paywall, usePaywallConfig } from '@subsovereign/react-native';
import { Platform } from 'react-native';

const config = await SubSovereign.getPaywallConfig(Platform.OS); // or usePaywallConfig(params)

<Paywall config={config} onSelectProduct={(productId) => buy(productId)} />

평소처럼 결제 라이브러리로 구매를 진행한 뒤, 서버에서 영수증을 검증하세요:

// Android (Play Billing) — built into this client:
await SubSovereign.validateGooglePurchase({ purchaseToken, productId, accessLevelId: 'pro' });

// iOS (StoreKit): use the Web/JS data SDK's validateApplePurchase —
// this client does not ship an Apple call. See web.en.md Step 4.

이후 checkEntitlements()를 다시 실행하여 기능을 잠금 해제하세요.

개인정보 보호 (GDPR)

await SubSovereign.recordConsent({ purpose: 'analytics', granted: true });

EU 철회 버튼 (Compliance Passport)

import { WithdrawalButton } from '@subsovereign/react-native';

<WithdrawalButton subscriptionId={sub.id} />

눈에 잘 띄는 라벨이 붙은 버튼을 표시하고, 한 번 확인 후 멱등적으로 요청을 제출합니다. 참고: 이 버튼은 앱의 철회 설정을 별도로 조회하지 않습니다. 대시보드에서 철회 기능을 비활성화하거나 특정 관할권으로 제한한 경우, 버튼의 표시 여부를 SubSovereign.getWithdrawalConfig()로 직접 제어하세요. 커스텀 UI를 위한 SubSovereign.withdraw(subscriptionId, opts)도 사용할 수 있습니다(channel: Platform.OS 전달).

빠른 참조

다음 단계

• 데이터 레이어 심화 안내(플래그, 데이터 삭제, 내보내기): 웹 & React Native 가이드.
• 개념이 낯선가요? SubSovereign 작동 원리를 읽어보세요.