161 lines
6.2 KiB
Markdown
161 lines
6.2 KiB
Markdown
# 볼링 매니저 구독 및 인앱 결제 통합 문서
|
|
|
|
## 개요
|
|
|
|
볼링 매니저 앱은 구독 기반 비즈니스 모델을 채택하여 다양한 기능을 제공합니다. 이 문서는 Flutter 모바일 앱에서 구독 및 인앱 결제 기능의 구현과 통합에 대한 상세 정보를 제공합니다.
|
|
|
|
## 아키텍처 개요
|
|
|
|
구독 및 인앱 결제 시스템은 다음 주요 구성 요소로 이루어져 있습니다:
|
|
|
|
1. **모델 (Models)**
|
|
- `Subscription`: 사용자의 구독 정보를 나타냅니다.
|
|
- `SubscriptionPlan`: 사용 가능한 구독 플랜의 세부 정보를 포함합니다.
|
|
|
|
2. **서비스 (Services)**
|
|
- `SubscriptionService`: 구독 상태 관리 및 백엔드 API와의 통신을 담당합니다.
|
|
- `InAppPurchaseService`: 플랫폼별 인앱 결제 처리를 담당합니다.
|
|
|
|
3. **백엔드 API**
|
|
- 구독 검증, 상태 관리, 영수증 검증 등의 서버 측 로직을 제공합니다.
|
|
|
|
## 데이터 흐름
|
|
|
|
### 구독 구매 프로세스
|
|
|
|
1. 사용자가 구독 구매 버튼을 클릭합니다.
|
|
2. `SubscriptionService.createSubscription()`이 호출됩니다.
|
|
3. `InAppPurchaseService.purchaseSubscription()`이 호출되어 플랫폼별 결제 프로세스를 시작합니다.
|
|
4. 결제가 완료되면 `InAppPurchaseService`의 `purchaseStream`이 업데이트됩니다.
|
|
5. 결제 상태가 `PurchaseStatus.purchased`로 변경되면 `_verifyAndSavePurchase()` 메서드가 호출됩니다.
|
|
6. `_verifyAndSavePurchase()`는 플랫폼별 영수증 데이터를 추출하고 서버에 전송하여 검증합니다.
|
|
7. 서버는 영수증을 검증하고 구독 정보를 데이터베이스에 저장합니다.
|
|
8. 검증이 성공하면 `SubscriptionService`는 서버에서 최신 구독 정보를 가져와 로컬 상태를 업데이트합니다.
|
|
|
|
### 구독 상태 확인 및 기능 접근 제어
|
|
|
|
1. 앱이 시작되면 `SubscriptionService.loadCurrentSubscription()`이 호출되어 현재 구독 상태를 로드합니다.
|
|
2. 사용자가 특정 기능에 접근하려고 할 때 `SubscriptionService.canAccessFeature()`가 호출됩니다.
|
|
3. 현재 구독 상태에 따라 기능 접근 권한이 결정됩니다.
|
|
4. 접근 권한이 없는 경우 업그레이드 안내 대화상자가 표시됩니다.
|
|
|
|
## 주요 클래스 및 메서드
|
|
|
|
### SubscriptionService
|
|
|
|
```dart
|
|
class SubscriptionService extends ChangeNotifier {
|
|
// 주요 속성
|
|
Subscription? _currentSubscription;
|
|
List<SubscriptionPlan> _availablePlans;
|
|
InAppPurchaseService _purchaseService;
|
|
|
|
// 주요 메서드
|
|
Future<void> loadCurrentSubscription();
|
|
Future<bool> createSubscription(SubscriptionPlanType planType, bool isYearly);
|
|
Future<bool> restoreSubscriptions();
|
|
Future<bool> changePlan(SubscriptionPlanType newPlanType, bool isYearly);
|
|
Future<bool> toggleAutoRenew();
|
|
bool canAccessFeature(SubscriptionFeature feature);
|
|
Future<bool> checkFeatureAccess(SubscriptionFeature feature, BuildContext context);
|
|
int getMaxMembersAllowed();
|
|
int getMaxEventsAllowed();
|
|
}
|
|
```
|
|
|
|
### InAppPurchaseService
|
|
|
|
```dart
|
|
class InAppPurchaseService extends ChangeNotifier {
|
|
// 주요 속성
|
|
List<ProductDetails> _products;
|
|
List<PurchaseDetails> _purchases;
|
|
bool _purchaseVerified;
|
|
Map<String, dynamic>? _verifiedPurchase;
|
|
|
|
// 주요 메서드
|
|
Future<void> initialize();
|
|
Future<bool> purchaseSubscription(SubscriptionPlanType planType);
|
|
Future<bool> restorePurchases();
|
|
Future<bool> _verifyAndSavePurchase(PurchaseDetails purchaseDetails);
|
|
}
|
|
```
|
|
|
|
## 구독 플랜 및 기능
|
|
|
|
볼링 매니저는 다음과 같은 구독 플랜을 제공합니다:
|
|
|
|
1. **무료 (Free)**
|
|
- 기본 볼링 점수 추적
|
|
- 최대 10명의 회원 관리
|
|
- 최대 5개의 이벤트 관리
|
|
|
|
2. **기본 (Basic)**
|
|
- 모든 무료 기능
|
|
- 최대 30명의 회원 관리
|
|
- 최대 10개의 이벤트 관리
|
|
- 기본 통계 분석
|
|
|
|
3. **프리미엄 (Premium)**
|
|
- 모든 기본 기능
|
|
- 최대 100명의 회원 관리
|
|
- 최대 50개의 이벤트 관리
|
|
- 고급 통계 분석
|
|
- 커스터마이징 옵션
|
|
|
|
4. **프로 (Pro)**
|
|
- 모든 프리미엄 기능
|
|
- 최대 500명의 회원 관리
|
|
- 최대 200개의 이벤트 관리
|
|
- 우선 지원
|
|
- 모든 고급 기능 접근
|
|
|
|
## 영수증 검증 프로세스
|
|
|
|
1. **iOS 영수증 검증**
|
|
- App Store 영수증 데이터 추출
|
|
- 서버에 영수증 데이터 전송
|
|
- 서버는 Apple 서버에 영수증 검증 요청
|
|
- 검증 결과에 따라 구독 상태 업데이트
|
|
|
|
2. **Android 영수증 검증**
|
|
- Google Play 영수증 데이터(JSON) 추출
|
|
- 서버에 영수증 데이터 전송
|
|
- 서버는 Google Play API를 통해 영수증 검증
|
|
- 검증 결과에 따라 구독 상태 업데이트
|
|
|
|
## 오류 처리
|
|
|
|
- 결제 프로세스 중 발생하는 오류는 `_error` 속성에 저장되고 UI에 표시됩니다.
|
|
- 네트워크 오류, 서버 오류, 검증 오류 등 다양한 오류 상황에 대한 처리가 구현되어 있습니다.
|
|
- 오류 발생 시 사용자에게 적절한 피드백을 제공하고 필요한 경우 재시도 옵션을 제공합니다.
|
|
|
|
## 테스트 및 QA
|
|
|
|
구독 및 인앱 결제 기능을 테스트하려면:
|
|
|
|
1. **샌드박스 환경 설정**
|
|
- iOS: App Store Connect에서 샌드박스 테스터 계정 설정
|
|
- Android: Google Play Console에서 테스트 트랙 설정
|
|
|
|
2. **테스트 시나리오**
|
|
- 구독 구매
|
|
- 구독 복원
|
|
- 플랜 변경
|
|
- 자동 갱신 설정 변경
|
|
- 구독 만료 처리
|
|
- 다양한 오류 상황 테스트
|
|
|
|
## 백엔드 API 엔드포인트
|
|
|
|
- `/subscriptions/current`: 현재 구독 정보 조회
|
|
- `/subscriptions/plans`: 사용 가능한 구독 플랜 목록 조회
|
|
- `/subscriptions/subscribe`: 새 구독 생성
|
|
- `/subscriptions/verify-receipt`: 인앱 결제 영수증 검증
|
|
- `/subscriptions/change-with-features`: 구독 플랜 변경
|
|
- `/subscriptions/autorenew`: 자동 갱신 설정 변경
|
|
|
|
## 결론
|
|
|
|
볼링 매니저의 구독 및 인앱 결제 시스템은 Flutter의 `in_app_purchase` 패키지와 커스텀 백엔드 API를 통합하여 안전하고 사용자 친화적인 결제 경험을 제공합니다. 이 문서는 시스템의 주요 구성 요소와 데이터 흐름을 설명하여 개발자들이 시스템을 이해하고 유지보수할 수 있도록 돕습니다.
|