Flutter용 SubSovereign — 통합 가이드

이 가이드는 subsovereign Flutter 패키지(sdk-flutter/)를 다룹니다. 데이터 클라이언트이자 네이티브 결제 화면(paywall) 위젯이기도 합니다. SubSovereign 대시보드에서 디자인한 결제 화면은 iOS, Android, 웹, React, React Native SDK와 동일한 설정을 사용해 실제 Flutter Paywall 위젯으로 렌더링됩니다.

시작하기 전에

SubSovereign 서버가 실행 중이어야 하고, 대시보드에 앱이 등록되어 있어야 합니다(**appId**와 SDK 역할의 API 키 필요). 또한 스토어 상품과 연결된 접근 등급(예: pro)과 게시된 결제 화면이 있어야 합니다. 실제 구매 처리는 기존에 사용하던 결제 플러그인(예: in_app_purchase)으로 하시고, SubSovereign은 그 이후에 구매를 검증하고 기록합니다.

1단계 — 설치

패키지를 추가합니다(pub.dev 출시 전이므로 path 또는 git 의존성으로 지정):

dependencies:
  subsovereign:
    path: ../sdk-flutter   # or a git dependency

import 'package:subsovereign/subsovereign.dart';

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

SubSovereign.instance.configure(SubSovereignConfig(
  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',
));

**안정적인 userId**를 사용하세요. 어디서든 동일한 값을 써야 사용자가 기기를 바꿔도 이용 권한이 따라옵니다.

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

try {
  final result = await SubSovereign.instance.checkEntitlements();
  if (result.hasAccess) {
    showPremiumContent();
  } else {
    showPaywall();
  }
} on SubSovereignException catch (e) {
  // Keep the user on their last-known access and retry later.
  debugPrint('Entitlement check failed: $e');
}

4단계 — 결제 화면 표시 및 판매

final config = await SubSovereign.instance.getPaywallConfig(platform: 'android');

Paywall(
  config: config,
  onSelectProduct: (productId) => buy(productId), // your billing plugin
)

구매가 완료되면 서버에서 구매를 검증한 뒤, 권한을 다시 확인하고 잠금을 해제합니다:

final granted = await SubSovereign.instance.validateGooglePurchase(
  purchaseToken: purchase.verificationData.serverVerificationData,
  productId: purchase.productID,
  accessLevelId: 'pro',
);
if (granted) {
  final result = await SubSovereign.instance.checkEntitlements();
  if (result.hasAccess) unlockProFeatures();
}

개인정보 보호 (GDPR)

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

EU 철회 버튼 (Compliance Passport)

온라인으로 EU 소비자에게 구독 상품을 판매하는 경우, EU 지침 2023/2673에 따라 명확하게 표시된 철회 기능을 제공해야 합니다:

WithdrawalButton(subscriptionId: sub.id)

이 버튼은 눈에 잘 띄게 표시되고, 사용자에게 한 번 확인을 받은 뒤 멱등적으로 요청을 제출합니다(네트워크 재시도가 발생해도 철회가 중복 생성되지 않습니다). 커스텀 UI를 사용하는 경우 SubSovereign.instance.withdraw(subscriptionId: …)와 getWithdrawalConfig()를 직접 호출하세요.

빠른 참조

다음 단계

• 실행 가능한 샘플은 sdk-flutter/example/에 있습니다.
• 개념이 처음이신가요? SubSovereign 동작 원리를 읽어보세요.