이 글에서 다루는 내용

RevenueCat과 Flutter를 연동할 때 서버 담당자가 실제로 어떤 업무를 해야 하는지, 앱(클라이언트)과 서버(백엔드)의 역할을 명확히 구분하고, 각 항목의 필수 여부와 구현 방식을 정리합니다. 또한 RevenueCat의 app_user_id와 자사 유저 ID를 어떻게 연동하는지, Entitlement 구성은 어떻게 해야 하는지도 함께 다룹니다.

RevenueCat이 대신 해주는 것

RevenueCat은 구독/결제 관리의 핵심 복잡도를 대신 처리해 줍니다. 아래 항목은 서버를 따로 구현하지 않아도 됩니다.

  • App Store / Play Store 영수증 검증
  • 구독 상태 관리 및 갱신 추적
  • Entitlement(권한) 판단
  • 구독 만료 / 갱신 / 취소 감지

서버 담당자 업무 전체 목록

필수 항목

1. Webhook 수신 엔드포인트 구현

RevenueCat이 구독 이벤트를 서버로 전송합니다. 서버는 이를 수신하여 DB에 구독 상태를 반영해야 합니다. 처리해야 하는 주요 이벤트는 다음과 같습니다.

  • INITIAL_PURCHASE — 최초 구독 결제
  • RENEWAL — 구독 갱신
  • CANCELLATION — 구독 취소
  • EXPIRATION — 구독 만료

2. 사용자 인증 연동

RevenueCat의 app_user_id와 자사 유저 ID를 일치시켜야 합니다. Flutter 클라이언트에서 로그인 성공 후 Purchases.logIn(userId)를 호출하면 app_user_id가 자사 유저 ID로 세팅됩니다. Webhook payload에 해당 ID가 그대로 포함되므로 별도 매핑 테이블이 필요 없습니다.

// 로그인 성공 후 호출
await Purchases.logIn('your_server_user_id'); // ex) "user_12345"

// 로그아웃 시 반드시 호출
await Purchases.logOut();

3. 구독 상태 기반 권한 제어 API

클라이언트 요청 시 해당 유저가 프리미엄 구독자인지를 서버에서 검증합니다. Webhook으로 동기화된 DB를 참조하거나, RevenueCat REST API를 직접 호출하는 방식으로 구현합니다.

4. Webhook 보안 처리

RevenueCat이 보내는 요청의 Authorization 헤더를 검증하여 외부 위조 요청을 차단해야 합니다. 이 처리가 없으면 구독 상태를 외부에서 조작할 수 있는 보안 취약점이 생깁니다.

선택 항목

5. RevenueCat REST API 직접 호출

Webhook이 유실되는 경우를 대비한 fallback으로 사용하거나, 실시간 최신 구독 상태가 필요할 때 서버에서 직접 조회합니다. API Key는 반드시 서버에서만 관리하고 클라이언트에 노출되지 않도록 해야 합니다.

GET https://api.revenuecat.com/v1/subscribers/{app_user_id}

6. 이벤트 로깅 / 분석 데이터 적재

구독 이벤트를 사내 데이터 파이프라인이나 분석 DB에 저장합니다. 매출 분석, 이탈률 추적 등 데이터 기반 운영이 필요한 경우에 구현합니다. 런칭 후 안정화 단계에서 추가해도 무방합니다.

앱 vs 서버 역할 구분

항목 앱 (Flutter) 서버 (Backend)
Webhook 수신 엔드포인트 ❌ 없음 ✅ 전담
사용자 인증 연동 ✅ Purchases.logIn() 호출 ✅ userId 기반 DB 조회
구독 상태 권한 제어 ✅ Entitlement 로컬 확인 (UI용) ✅ API 엔드포인트로 최종 검증
RevenueCat REST API ❌ 금지 (API Key 노출 위험) ✅ 전담
Webhook 보안 처리 ❌ 없음 ✅ 전담
이벤트 로깅/분석 🔺 Firebase 등 클라이언트 이벤트 ✅ 구독 이벤트 DB 적재

앱에서는 빠른 UX를 위해 Entitlement를 로컬에서 먼저 확인하고, 서버에서 보안이 필요한 최종 권한 검증을 이중으로 처리하는 구조가 표준입니다.

최소 구현 순서 (MVP 기준)

1단계: 유저 ID 매핑 — Flutter에서 Purchases.logIn(userId) 연동
   ↓
2단계: Webhook 엔드포인트 구현 + Authorization 헤더 보안 처리
   ↓
3단계: 구독 상태 기반 권한 제어 API 구현
   ↓
4단계 (런칭 후): REST API fallback + 이벤트 로깅 추가

Entitlement 구성 예시

Play Store와 App Store의 Pro 월간/연간 상품을 하나의 pro Entitlement에 묶습니다. 월간/연간 중 어느 것을 구매해도 동일한 Pro 권한이 부여되는 구조입니다.

스토어 상품 ID Entitlement
Play Store meetjool.subscription:pro-year-auto pro
Play Store meetjool.subscription:pro-monthly-auto pro
App Store com.meetjool.app.subscription.pro.monthly pro
App Store com.meetjool.app.subscription.pro.yearly pro

premium 플랜을 별도로 운영할 경우 premium Entitlement를 따로 만들어 해당 상품들을 연결합니다.