RevenueCat 구매 설정

초보자 연습

존재 이유: Apple과 Google은 앱 내 디지털 구매가 자체 빌링을 거칠 것을 요구하며—Stripe Checkout은 불가—킷은 그 경계를 강제합니다. RevenueCat은 두 스토어 위에 놓여 하나의 통합으로 iOS와 Android를 커버합니다: 영수증, 구독, 복원을 추적하고 서버는 RevenueCat에 워크스페이스가 결제했는지 묻습니다.

전제 조건: 모바일 계정 가이드의 Apple Developer Program(연간 $99)과 Google Play Console($25 일회) 계정—RevenueCat이 연결하기 전에 스토어 제품이 존재해야 합니다—그리고 실제로 테스트할 EAS 개발 빌드. Expo Go는 네이티브 구매 모듈을 전혀 실행할 수 없기 때문입니다. RevenueCat의 무료 등급은 테스트를 커버합니다. 제품이 공개되기 전에는 어떤 것도 청구되지 않습니다.

용어 정리: RevenueCat 프로젝트는 스토어에 연결된 앱을 보유합니다. 제품은 RevenueCat 안에 미러링된 스토어 아이템입니다. 인타이틀먼트는 구독이 활성인 동안 RevenueCat이 부여하는 플래그로 기본값은 pro입니다. 오퍼링은 제품을 앱이 표시하는 페이월로 묶습니다. 공개 SDK 키는 모바일 env에 들어가고 시크릿 API 키와 webhook 인증은 서버 측에 둡니다.

만드는 것: 프로젝트 하나, 스토어에 연결된 앱 두 개, 제품, 인타이틀먼트 하나, 오퍼링 하나—약 한 시간이며 대부분 스토어 제품 설정 대기입니다.

• 모바일 계정 만들기
• 개발 클라이언트 빌드

RevenueCat 계정 및 프로젝트 만들기

1. app.revenuecat.com → 가입하고 제품 이름으로 프로젝트를 만듭니다.

예상 결과: Apps, Products, Entitlements, Offerings, API keys 탭이 있는 빈 프로젝트 대시보드—다음 섹션들이 순서대로 채웁니다.

스토어 제품을 만든 후 두 앱 연결

스토어 측 제품은 RevenueCat이 참조하기 전에 존재해야 합니다. iOS: appstoreconnect.apple.com → My Apps → ios.bundleIdentifier로 앱 레코드 만들기 → In-App Purchases 또는 Subscriptions → 판매할 구독 제품 만들기(테스트하는 동안 초안으로 둘 수 있습니다). Android: play.google.com/console → 앱 만들기 → Monetize → Products → Subscriptions(또는 인앱 제품).

그런 다음 RevenueCat 안에서 둘 다 연결합니다: Apps → New app. iOS는 App Store를 선택하고 번들 ID를 입력하고 양식이 요구하는 App Store Connect 자격 증명을 제공합니다—각 필드에 대한 RevenueCat 자체 설정 문서를 링크합니다. Android는 Play Store를 선택하고 패키지 이름을 입력하고 Play 서비스 계정 JSON을 업로드합니다—링크된 문서가 Google Cloud에서 만드는 과정을 안내합니다.

예상 결과: 두 앱이 프로젝트 아래에 나열되고 스토어 콘솔에 제품이 존재합니다—이 단계에서는 초안 상태도 괜찮습니다.

제품, 인타이틀먼트, 오퍼링

1. Products → New: 스토어 제품마다 RevenueCat 제품을 하나씩 만들고 일치하는 App Store 또는 Play 제품 ID를 붙입니다—ID는 콘솔과 정확히 일치해야 합니다.

2. Entitlements → New: REVENUECAT_ENTITLEMENT_ID에 맞는 이름을 지정합니다—킷의 기본값은 pro—그리고 그것을 부여하는 제품을 첨부합니다.

3. Offerings → New: 오퍼링을 만들고 제품을 가리키는 패키지를 추가하고 Current로 표시합니다—앱은 페이월을 렌더링할 때 offerings.current를 읽습니다.

REVENUECAT_ENTITLEMENT_KEY는 기본값 ai.reference-task로 유지하세요: 이것은 킷의 내부 원장 키—제공된 웹 플랜이 부여하는 것과 동일한 키—이며 RevenueCat 액세스는 그 아래에 기록됩니다. 제품의 플랜 키가 바뀔 때만 이름을 바꾸세요.

키 복사 및 webhook 등록

Project → API keys에 아래 세 종류가 나열됩니다. 플랫폼별 공개 SDK 키(iOS는 appl_…, Android는 goog_…)는 apps/mobile/.env.local에 들어갑니다—앱을 식별하고 지출 권한이 없으며 EXPO_PUBLIC_ 접두사가 이들에게 올바릅니다.

시크릿 API 키(sk_…, v1 키)와 webhook 인증은 apps/web/.env.local의 서버 전용입니다—EXPO_PUBLIC_에 넣지 말고 커밋도 하지 마세요. 서버는 시크릿 키로 RevenueCat의 구독자 API를 호출하여 각 워크스페이스의 구매 상태를 확인합니다.

Webhook: RevenueCat → Integrations → Webhooks → URL을 {APP_URL}/api/billing/webhook/revenuecat으로 설정하고 Authorization 헤더 값—직접 만든 임의의 긴 무작위 문자열—을 설정한 다음 정확히 같은 문자열을 REVENUECAT_WEBHOOK_AUTHORIZATION에 넣습니다. 킷은 헤더를 그대로 비교하고 다른 것은 거부하므로 갱신, 취소, 환불이 다음 앱 실행을 기다리지 않고 서버에 도달합니다.

샌드박스 구매는 프로덕션 외부에서 자동으로 허용됩니다. 프로덕션 env의 REVENUECAT_ALLOW_SANDBOX=true는 시작 시 거부되므로 공개 후에는 설정 해제로 두세요.

# apps/mobile/.env.local
EXPO_PUBLIC_MOBILE_PURCHASES_PROVIDER=revenuecat
EXPO_PUBLIC_REVENUECAT_IOS_API_KEY=appl_…
EXPO_PUBLIC_REVENUECAT_ANDROID_API_KEY=goog_…

# apps/web/.env.local — server side
MOBILE_PURCHASES_PROVIDER=revenuecat
REVENUECAT_SECRET_API_KEY=sk_…
REVENUECAT_WEBHOOK_AUTHORIZATION=<the exact Authorization value set on the webhook>
REVENUECAT_ENTITLEMENT_ID=pro
REVENUECAT_ENTITLEMENT_KEY=ai.reference-task

샌드박스 구매로 확인

구매는 개발 또는 프로덕션 빌드 안에서만 실행됩니다—Expo Go에는 네이티브 모듈이 전혀 없으므로 이 단계는 eas build --profile development가 개발 클라이언트를 생성했음을 가정합니다(EAS 가이드가 이를 빌드합니다).

1. 샌드박스 계정으로 로그인한 기기 또는 시뮬레이터에 개발 빌드를 설치합니다: iOS는 App Store Connect → Users and Access → Sandbox Testers, Android는 Play Console → license testing.

2. 앱에서 페이월을 열고 샌드박스 계정으로 구매합니다. 예상 결과: 구매가 샌드박스에서 완료되고—실제 청구 없음—구매 복원이 작동하며 워크스페이스의 인타이틀먼트가 ai.reference-task 키 아래에 서버 측으로 기록된 활성으로 표시됩니다.

일반적인 실패: 빈 페이월은 오퍼링이 Current가 아니거나 제품이 연결되지 않았음을 의미합니다. 기기 구매 실패는 스토어 제품이 아직 초안이거나 잘못된 샌드박스 계정으로 로그인했음을 의미합니다. 뒤집히지 않는 인타이틀먼트는 MOBILE_PURCHASES_PROVIDER/EXPO_PUBLIC_MOBILE_PURCHASES_PROVIDER가 꺼져 있거나 webhook Authorization이 불일치함을 의미합니다—RevenueCat 대시보드가 각 webhook 전달 상태를 나열합니다.

• 기기에서 빌드 및 확인
• 웹 체크아웃은 대신 Stripe 사용