03-ssot
Define the single source of truth for the purchase system across Unity IAP, backend verification, entitlements, restore rules, and routing. Use when deciding canonical purchase concepts and cross-document invariants for the purchase module.
- License 许可
- MIT
- 最近更新
- 2026-04-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- 03-ssot
- description
- Define the single source of truth for the purchase system across Unity IAP, backend verification, entitlements, restore rules, and routing. Use when deciding canonical purchase concepts and cross-document invariants for the purchase module.
03 SKILL.md 正文
03-ssot — 30-purchase-system (통합 SSOT)
Status: ACTIVE AppliesTo: v10
이 문서가 정본이다 (SSOT)
이 문서는 30-purchase-system의 단일 SSOT 허브이다. 기존 04~08 분할 문서의 핵심 내용이 이 문서에 통합되었다. 운영/보안/테스트/DoD는 09-ssot-operations를 참조한다.
관심사별 라우팅 (중복 금지)
- 운영/보안/테스트/DoD 체크리스트:
../09-ssot-operations/SKILL.md - PurchaseStorage(로컬/클라우드 저장용 최소 상태 스냅샷):
../33-purchase-storage/SKILL.md - Firebase Functions + Firestore 구현 상세:
../40-purchase-backend-firebase/SKILL.md - Firebase 레포 구성/CLI/배포 셋업:
../11-purchase-repo-firebase-functions-setup/SKILL.md - 고정 결정사항(Callable 이름/경로/시크릿/정책 결정):
../46-purchase-decisions/SKILL.md
이 문서(03)는 통합 SSOT 허브/핵심 합의에 집중하고, 구현/운영 상세의 원문은 위 문서로 분리한다.
우선순위
- Root SSOT:
skills/devian/10-module/03-ssot/SKILL.md - Unity 관련 SSOT:
skills/devian-unity/03-ssot/SKILL.md - 결제/IAP 관련 SSOT: 이 문서
충돌 시 Root SSOT의 정의/플레이스홀더/규약이 우선한다.
A. Unity IAP (from 04-ssot-unity-iap)
전제
- 결제 SDK는 Unity In-App Purchasing (Unity IAP) 5.1.2 (
com.unity.purchasing@5.1.2)를 사용한다. - 스토어별 구현 차이는 존재하지만, 최종 지급/상태는 서버 검증 결과를 따른다.
Unity IAP 5.x v5 API 정책
- 현재 구현은 v5 신규 API (
StoreController+UnityIAPServices+ 이벤트 기반)를 사용한다. [Obsolete]Legacy API (IDetailedStoreListener,UnityPurchasing.Initialize,ConfigurationBuilder,IStoreController,Product.receipt)는 사용하지 않는다.
v5 API 사용 패턴
| 기능 | v5 API |
|---|---|
| 초기화 | UnityIAPServices.StoreController() → await controller.Connect() → controller.FetchProducts(definitions) |
| 제품 등록 | List<ProductDefinition> + controller.FetchProducts(...) (ProductCatalog에서 변환) |
| 구매 시작 | controller.PurchaseProduct(productId) |
| 구매 확인 | controller.ConfirmPurchase(pendingOrder) |
| Receipt 접근 | PendingOrder.Info.Receipt |
| Restore | controller.RestoreTransactions(Action<bool, string?>) (플랫폼 분기 불필요) |
| 구매 성공 콜백 | controller.OnPurchasePending (PendingOrder) |
| 구매 실패 콜백 | controller.OnPurchaseFailed (FailedOrder) |
| 제품 Fetch 콜백 | controller.OnProductsFetched / OnProductsFetchFailed |
참고: 4.x → 5.x 주요 변경 사항
| 항목 | 변경 |
|---|---|
| Amazon/UWP/Facebook 스토어 | 제거됨 |
| Apple Receipt Validation | Deprecated (Google Play만 지원) |
IAppleExtensions.RestoreTransactions |
Action<bool> → Action<bool, string> |
플랫폼 차이
iOS: Restore(복원)
- iOS는 재설치/기기 변경 시 Restore 플로우가 필요하다.
- Restore는 "스토어 구매 이력 재동기화 트리거"이며, 최종 Entitlement는 서버 상태(purchases/entitlements)를 기준으로 확정한다.
Android: 복원 UX
- Android는 보통 Restore 버튼을 직접 노출하지 않고, 앱 시작/로그인 시 서버 상태 동기화로 복원을 처리해도 된다.
Pending / Deferred 상태
- iOS: 승인 대기(deferred) 상태가 발생할 수 있다.
- Android: pending 상태가 발생할 수 있다.
- 공통 규칙: PENDING/DEFERRED 상태에서는 지급 금지 (서버 검증 확정 전 지급 금지)
B. Product Catalog (from 05-ssot-product-catalog)
SSOT 원칙
1) 내부 표준 ID가 정본
- 상위 로직은
internal_product_id를 정본으로 사용한다. - Store SKU는 매핑 데이터로만 취급한다.
2) 타입 규칙
-
Consumable: 재화 등 반복 구매/즉시 지급
-
Rental: 기간제 구매(예: NoAds 30일). 반복 구매 허용, 만료일 연장 방식
-
Subscription: "구독 기반 NoAds" 등 상태 기반
-
Season Pass: 시즌별 구매 1회성 Entitlement로 운영
-
kind의 정본 enum은 컨텐츠 레이어가 정의한
PurchaseKind다. -
테이블(
ShopTable.xlsxPURCHASE.kind)의 타입은PurchaseKind를 사용한다.
카탈로그 통합
PurchaseManager는 TB_PURCHASE 테이블을 직접 참조하여 카탈로그를 구성한다.
Devian.Samples.MobilePackage.asmdef에 Devian.Domain.Game 참조가 포함되어 있다.
Purchase 지급을 위해 internal_product_id -> reward_group_id 변환이 필요하다.
PurchaseManager가ResolveRewardGroupId(internal_product_id)→TB_PURCHASE.Get(internal_product_id).Reward_group_id로 직접 변환한다.BuildProductDefinitions()→TB_PURCHASE.GetAll()에서is_active필터링 후 ProductDefinition 목록을 생성한다.
Unity IAP 5.x (v5) Catalog Notes
- 본 SSOT에서 "카탈로그"는 내부 ID(
internal_product_id) ↔ 스토어 SKU(Apple/Google) 매핑 데이터를 의미한다. - Unity IAP 5.x(v5)에서는 과거 방식의
ProductCatalog.LoadDefaultCatalog()같은 런타임 로딩 API에 의존하지 않는다. (obsolete 전제 제거) - 런타임에서는 "등록된 제품 정의"를 사용해 구매를 시작하며, 상위 로직은 반드시
internal_product_id만 사용한다. - 스토어 SKU는 플랫폼별 매핑 데이터일 뿐이며, 운영/코드에서 직접 참조하지 않는다.
NEEDS CHECK (형준 결정 필요)
Product Catalog (상품 요약/매핑) SSOT — ✅ 전체 결정됨
- [x] SSOT 저장 위치: (A) Devian input 테이블(Excel) 기반 — 결정됨
- PURCHASE 테이블 스키마를 이 문서(03-ssot)에서 SSOT로 정의한다.
ShopTable.xlsx의 PURCHASE 시트에서 데이터를 관리한다.
- [x]
{buildInputJson}도메인 등록: — 결정됨- 도메인 등록 정보는 컨텐츠 레이어 SSOT에서 관리
- [x] ShopTable.xlsx 경로: — 결정됨
- 경로는 컨텐츠 레이어 SSOT에서 관리
- [x] PURCHASE 테이블 스키마/필드: — 결정됨
internal_product_id(string, pk) — 내부 상품 ID (정본)reward_group_id(string) — 지급 Reward Key,internal_product_id -> reward_group_id변환의 SSOTkind(PurchaseKind) — 상품 타입 (Consumable/Rental/Subscription/SeasonPass)is_active(bool) — 운영 활성 토글store_sku_apple(string) — Apple Store SKUstore_sku_google(string) — Google Play SKU
- [x] 시즌 매핑 필드 위치: — 결정됨
- 시즌 구매 제한용
season_id는SHOP_ITEM_PURCHASE.season_id에서 관리한다. (PURCHASE스키마에는 포함하지 않는다.)
- 시즌 구매 제한용
C. Verification Server + Idempotency + Firestore Ledger (from 06-ssot-verify-idempotency)
SSOT (핵심 합의)
- 별도 VM 서버 없이 Firebase Cloud Functions를 "검증 서버"로 사용한다.
- 결제/구매 정보는 Firestore Cloud에 저장한다. (원장/entitlements)
- 클라이언트는 결제 원장에 직접 write 하지 않는다. (서버 write only)
- 멱등 처리(Idempotency)로 중복 verify/중복 지급을 방지한다.
구현 상세(함수 구조/스키마/인덱스)는 40, 레포/배포 셋업은 44, 최종 고정 결정값은 46을 참조한다.
resultStatus (정본 enum)
클라이언트·서버 모두 아래 값만 사용한다. (문자열 비교, 대문자)
| 값 | 의미 |
|---|---|
GRANTED |
신규 검증 성공 — 지급 실행 |
ALREADY_GRANTED |
동일 구매 재요청 — 이미 지급됨(멱등) |
REJECTED |
스토어 검증 실패 / 위변조 |
PENDING |
스토어가 아직 확정하지 않은 상태 (deferred/pending) — 지급 금지 |
REVOKED |
환불/취소 등으로 사후 철회 |
REFUNDED |
스토어 환불 확인 |
- Firestore purchase 문서의 정본 상태 필드는
verifyStatus다. (resultStatus와 같은 의미의 서버 상태) clientGrantStatus는 클라이언트 로컬 지급 결과 보고 상태를 별도로 저장한다. (PENDING/APPLIED_ACKED/FAILED_REPORTED)storeConfirmStatus는 스토어ConfirmPurchase처리 상태를 별도로 저장한다. (PENDING/CONFIRMED)- 01-policy의 기존 표기(
GRANTED|ALREADY_GRANTED|REJECTED|PENDING)와 정합.
엔드포인트(최소 세트)
1) verifyPurchase (Callable 권장)
- 입력
uid— Auth context에서 확보 (클라가 보내지 않음)storeKey: string— "apple" | "google"internal_product_id: stringkind: string— "Consumable" | "Rental" | "Subscription" | "SeasonPass" (=PurchaseKindstring)payload: string— 스토어 영수증/검증 데이터 (클라에서BuildVerifyPayload(receipt)결과)
- 처리
- 스토어 서버 검증(Apple/Google)
- Firestore 원장 기록 upsert (멱등)
- 결과 반환 (entitlements 갱신은 별도
getEntitlements호출로 분리)
- 출력
resultStatus: string— 위 enum 중 하나purchaseId: string—{storeKey}_{storePurchaseId}verifyStatus: string— 서버 purchase 상태 필드(verifyStatus)와 정합clientGrantStatus: string—"PENDING" | "APPLIED_ACKED" | "FAILED_REPORTED"storeConfirmStatus: string—"PENDING" | "CONFIRMED"grants: array— (server informational, 클라 지급 입력으로 미사용) 지급 내역 참고용. 보상은reward_group_id경로로 지급entitlementsSnapshot: object?— (optional) 갱신된 entitlements 스냅샷. GRANTED/ALREADY_GRANTED 시 포함. 클라는ParseEntitlementsSnapshot으로 파싱 +cacheEntitlementsSnapshot으로 InventoryStorage에 동기화
C# ↔ Callable 필드 매핑
C# (VerifyPurchaseRequest) |
Callable JSON key | 비고 |
|---|---|---|
Internal_product_id |
internal_product_id |
|
Kind (enum → string) |
kind |
"Consumable" / "Rental" / "Subscription" / "SeasonPass" |
Store |
storeKey |
|
Payload |
payload |
| Callable JSON response | C# (VerifyPurchaseResponse) |
비고 |
|---|---|---|
resultStatus |
ResultStatus |
위 enum 값 |
purchaseId |
PurchaseId |
verify 멱등키 |
verifyStatus |
VerifyStatus |
Firestore purchase 상태 필드와 정합 |
clientGrantStatus |
ClientGrantStatus |
로컬 지급 결과 보고 상태 |
storeConfirmStatus |
StoreConfirmStatus |
스토어 Confirm 처리 상태 |
grants[] |
(클라이언트 미사용 — 무시) | 서버 informational. 보상은 reward_group_id 경로로 지급 |
entitlementsSnapshot |
Snapshot (EntitlementsSnapshot?) |
optional |
1-1) ackPurchaseClientGrant (Callable)
- 입력
uid— Auth context에서 확보 (클라가 보내지 않음)purchaseId: stringclientGrantStatus: string—"APPLIED_ACKED"|"FAILED_REPORTED"
- 처리
- purchase 문서 소유자/상태 확인 (
verifyStatus == GRANTED) clientGrantStatus = APPLIED_ACKED | FAILED_REPORTED멱등 업데이트
- purchase 문서 소유자/상태 확인 (
- 출력
purchaseIdverifyStatusclientGrantStatus
1-2) ackPurchaseStoreConfirm (Callable)
- 입력
uid— Auth context에서 확보 (클라가 보내지 않음)purchaseId: string
- 처리
- purchase 문서 소유자/상태 확인 (
verifyStatus == GRANTED) storeConfirmStatus = CONFIRMED멱등 업데이트
- purchase 문서 소유자/상태 확인 (
- 출력
purchaseIdverifyStatusclientGrantStatusstoreConfirmStatus
2) getEntitlements (Callable/HTTPS 중 택1)
- 입력:
uid(Auth context) - 출력:
| Callable JSON response | C# (EntitlementsSnapshot) |
비고 |
|---|---|---|
ownedSeasonPasses |
OwnedSeasonPasses: IReadOnlyList<string> |
|
rentals |
Rentals: IReadOnlyDictionary<string, long> |
key=internal_product_id, value=expiresAtServerUtcMs |
currencyBalances |
CurrencyBalances: IReadOnlyDictionary<string, long> |
key=재화ID, value=잔고 |
serverNowUtcMs |
ServerNowUtcMs: long |
Rental 남은시간 계산 기준 |
3) getRecentPurchases30d (Callable)
- 목적: "최근 30일 이내" 구매 내역 조회 (kind 파라미터로 필터)
- 기준 시각:
storePurchasedAt(영수증 날짜) - 30일 기준: 서버 now − 30일 (클라/기기 시간 금지)
- 최신(latest):
storePurchasedAtdesc, 동률이면 docId desc - 인증:
context.auth.uid필수 - 입력:
kind(string, 필수 — PurchaseKind 값.Consumable/Rental등),pageSize(optional, 기본 20) - 출력:
items: array— 각 원소:{ purchaseId, internal_product_id, storePurchasedAt, verifyStatus, status }status는 legacy response compatibility alias (temporary)
nextCursor: string | null— 형식:"storePurchasedAtMs|docId"(페이지네이션 토큰)
PurchaseManager 정식 API
GetLatestConsumablePurchase30dAsync()- 서버 Callable:
getRecentPurchases30d(kind="Consumable",pageSize=1로 호출,items[0]만 사용) - 최근 30일 내 해당 kind 내역이 없으면 실패(
GAME_ERROR_TYPE.PURCHASE_*+ 메시지)로 처리 - 페이지네이션 없이 최신 1건만 반환하는 단일 API
- 서버 Callable:
Client-Side Purchase Flow (정본)
ConfirmPurchase 타이밍 정책
verifyPurchase응답의resultStatus에 따라:GRANTEDcontroller.ConfirmPurchase(pendingOrder)→ackPurchaseStoreConfirm먼저 실행 (스토어 잠김 방지 우선)- 이후 로컬 지급 →
ackPurchaseClientGrant(APPLIED_ACKED)수행 PurchaseStorage.current는Confirm + storeConfirm ACK + clientGrant report종결 후 clear- 로컬 지급 실패 →
ackPurchaseClientGrant(FAILED_REPORTED)보고 가능, 단storeConfirmStatus != CONFIRMED이면 clear 금지
ALREADY_GRANTEDstoreConfirmStatus == PENDING이고 로컬에서 이미 Confirm 완료(storeConfirmedLocal) 상태면ackPurchaseStoreConfirm복구 먼저 수행clientGrantStatus == APPLIED_ACKED→ 중복 지급 없이 Confirm/ACK 복구만 진행clientGrantStatus == PENDING또는FAILED_REPORTED→ 로컬 지급 복구 재시도 허용 → APPLIED_ACKED 보고PurchaseStorage.current는 복구 단계가 모두 종결될 때만 clear
REJECTED→ Confirm 하지 않음 (Unity가 자동 환불 처리)PENDING→ Confirm 하지 않음 (스토어 확정 대기)
- Confirm을 호출하지 않으면 Unity IAP가 다음 앱 실행 시
OnPurchasePending을 재전달한다.
Client-side local snapshot (PurchaseStorage)
- 클라이언트는
PurchaseManager가 소유하는PurchaseStorage에 최소 상태 스냅샷만 기록할 수 있다. - 목적: 구매 진행 중 상태(current)의 local/cloud 저장 (복구 보조) + 환불/지원 대응용 최소 로그(refundSupportLogs)
current는 복구 워크아이템이며,Confirm + storeConfirm ACK + clientGrant report가 종결되기 전에는 clear하지 않는다.- 금지: 전체 구매 이력 정본 저장, 구매 실패 상세(코드/메시지) 저장, raw receipt 저장, 서버 원장/멱등 대체
- Rental 만료 시각(
expiresAtClientUtcMs) / SeasonPass 소유권은 InventoryStorage에서 관리한다 (PurchaseStorage 범위 아님).- InventoryStorage:
Rentals(rentalTypeId → expiresAtClientUtcMs),SeasonPasses(seasonPassTypeId → owned) - Reward 파이프라인(
REWARD_TYPE.RENTAL/REWARD_TYPE.PASS)을 통해 설정하고, 만료 시각은 서버 데이터 Sync에서 갱신한다.
- InventoryStorage:
RetryInterruptedPurchaseAsync()는 "재구매"가 아니라PurchaseStorage.current+ 서버 상태를 바탕으로 중단된 상태 전이를 재개하는 경로다.- 정본 문서:
33-purchase-storage
Reward 적용(클라) 규칙
GRANTED이면 컨텐츠 레이어 매핑(internal_product_id -> reward_group_id) 후 RewardManager의ApplyRewardGroup(reward_group_id)를 호출한다. (AppliedRewards수집 가능)ALREADY_GRANTED는 기본적으로 재지급 금지이나,clientGrantStatus == PENDING또는FAILED_REPORTED인 경우에는 로컬 지급 복구 경로를 허용한다.grants[]는 응답 스키마에 존재할 수 있으나, 클라 지급 입력으로 사용하지 않는다(지급 호출은 reward_group_id 기반).- RewardManager는 지급 실행만 담당하며, 멱등/기록/복구는 PurchaseManager(+서버)가 책임진다.
연관:
Pending / Deferred 처리 규칙 (v5)
- v5
OnPurchasePending은 정상 구매와 deferred/pending을 모두 포함한다. - 클라이언트 처리 흐름:
OnPurchasePending수신 → 무조건 서버verifyPurchase호출- 서버가 스토어 검증 시 pending/deferred 상태 감지 →
PENDING반환 - 클라:
PENDING수신 → Confirm 하지 않음, 지급 하지 않음 - 스토어 확정 후 다음 앱 실행 시
OnPurchasePending재전달 → 1)부터 재시도
- PENDING 상태에서는 절대 지급/Confirm 금지
Firestore SSOT Schema (Canonical)
결제 운영(조회/감사/복구)을 위해 "구매 상세 조회"가 가능한 최소 필드를 유지한다.
/users/{uid}/purchases/{purchaseId}
purchaseId권장 규칙:{storeKey}_{storePurchaseId}storePurchaseId는 Apple transaction id / Google orderId 또는 purchaseToken 기반 식별자 등 "스토어에서 유일한 값"
- 최소 필드
storeKey: stringstorePurchaseId: stringinternal_product_id: stringkind: stringverifyStatus: string// "GRANTED" | "REJECTED" | "PENDING" | "REVOKED" | "REFUNDED"clientGrantStatus: string// "PENDING" | "APPLIED_ACKED" | "FAILED_REPORTED"storeConfirmStatus: string// "PENDING" | "CONFIRMED"status: string// legacy compatibility field (temporary)lastStatusChangeAt: timestamp// server timestamp (상태 변경 시각)statusReason: string// "refund" | "refund_reversed" | "chargeback" | "manual" 등payloadHash: string// 원문 저장 대신 해시 권장environment: string// "sandbox" | "production" (가능하면 기록)storePurchasedAt: timestamp// 스토어(영수증/서버 검증 응답)에서 추출한 "구매 시각" — 클라이언트/디바이스 시간 사용 금지(서버에서만 생성)createdAt: timestamp(server timestamp)updatedAt: timestamp(server timestamp)raw: map(optional; 민감정보 제외한 최소 subset)
/users/{uid}/entitlements/current
- 최소 필드(프로젝트 확장 가능)
updatedAt: timestamp(server timestamp)- (예시)
ownedSeasonPasses: array<string> - (예시)
rentals: map<string, number>//internal_product_id -> expiresAtServerUtcMs - (예시)
currencyBalances: map<string, number>
SeasonPass / Rental Restore Projection (design fixed, server-side)
SeasonPass/Rental복원 정본은 서버 Firestore projection(/users/{uid}/entitlements/current)을 사용한다.SyncEntitlementsAsync()는getEntitlements를 호출해InventoryStorage.Passes/Rentals를 서버 값으로 덮어쓴 뒤 snapshot을 반환한다.RestoreAsync()(스토어 복원)는 스토어 복원 트리거 후 동일한 entitlements 복원 규칙을 적용한다.SeasonPass복원은 시즌 유효 구간(TB_SEASON.start <= now < end)일 때만 반영한다.- Rental/SeasonPass 조회:
GetRentalRemainingMsAsync는 로컬 저장값 기준 남은 시간(ms)을 조회한다. Rental재구매 만료일 계산 정책(클라이언트):newExpiry = max(existingExpiry, now) + 30일(연장 방식)
- Rental 복원 정책(클라이언트):
expiresAtServerUtcMs > serverNowUtcMs만 반영- 누적 연장을 허용하므로 복원 시 상한(30일 cap)을 두지 않는다.
Idempotency (멱등) 규칙
- 멱등 키는
purchaseId(권장:{storeKey}_{storePurchaseId})를 사용한다. verifyPurchase는 같은purchaseId로 여러 번 호출되어도:- purchases 문서는 upsert로 유지
- entitlements는 "원장 기반 재계산" 또는 트랜잭션으로 갱신
- 중복 지급이 발생하지 않아야 한다
Write / Read Policy
- Firestore write는 서버(Functions/Admin SDK) 만 수행한다.
- 클라이언트는 verify +
getEntitlements동기화 + SaveData(local/cloud) 저장/복원으로 상태를 갱신/조회한다. - (정책 선택) 클라이언트 Firestore direct read를 허용한다면:
/users/{uid}/entitlements/current만 제한적으로 허용을 권장- purchases 원장 direct read는 기본 비권장
- Refund visibility (minimum)
- 환불 발생 시:
verifyStatus="REFUNDED",statusReason="refund",lastStatusChangeAt=serverTimestamp - 환불 취소(철회) 시:
verifyStatus를 정상 상태로 되돌리고,statusReason="refund_reversed",lastStatusChangeAt=serverTimestamp - 이 2개 필드로 "환불/환불취소가 실제로 있었는지"를
purchaseId단건 조회에서 확인 가능하다.
- 환불 발생 시:
Privacy (Raw 데이터)
- receipt/payload 원문 저장은 피한다.
payloadHash저장을 기본으로 하고, raw 저장이 필요하면 "민감정보 제외 + 최소 subset"만 저장한다.
End-to-End Flow
- 클라: Unity IAP로 구매 진행
- 클라: 영수증/receipt 확보 후 서버
verifyPurchase호출 - 서버: 스토어 검증(Apple/Google) 수행
- 서버: Firestore에 purchases 기록 저장 + entitlements/current 갱신 (필수)
- 클라: 서버 verify 성공 응답 수신 후에만 ConfirmPendingPurchase / 지급 처리
- 클라:
SyncEntitlementsAsync로 entitlements/current를 반영해mPasses/mRentals를 복원 - 클라: 반영된 상태를 SaveData(local/cloud) payload에 저장/복원
Security Rules (High-level)
- purchases 컬렉션은 클라이언트 write 금지.
- entitlements/current는 (정책에 따라) 클라 read 허용 가능, write 금지.
- UID 스코프는 반드시
request.auth.uid == uid로 제한.
NEEDS CHECK (code alignment)
- 현재 저장소 코드가 실제로 어떤 Firestore 경로/필드를 사용 중인지 별도 점검 필요. (본 작업은 문서-only이며 코드 변경 금지)
D. Subscription NoAds (from 07-ssot-subscription-noads)
SSOT 원칙
- NoAds는 "구독 Active 상태"로만 판정한다.
- 클라이언트 Unity IAP 콜백만으로 NoAds를 영구 적용하지 않는다.
- 최종 상태는 verifyPurchase +
SyncEntitlementsAsync(server restore) + SaveData(local/cloud) 저장/복원으로 확정한다.
상태 갱신
iOS
- 서버 알림(Apple Server Notifications)을 수신하여 구독 상태를 갱신하는 구성을 권장한다.
- 알림 기반 갱신이 불가할 경우, scheduled recheck로 보조할 수 있다.
Android
- 운영 초기에는 scheduled recheck로 시작할 수 있다(선택).
- 최종 목표는 서버에서 "현재 유효 구독"을 신뢰 가능한 방식으로 유지하는 것이다.
클라이언트 적용 규칙
- NoAds 상태의 정본은 서버 entitlements 기반으로 복원된
InventoryStorageRental(NO_ADS) 값이다. - 동기화 방식:
PurchaseManager.SyncEntitlementsAsync(ct)가 서버getEntitlements를 호출해 Rental/SeasonPass를 복원(덮어쓰기)한다. - NoAds는 광고 표시 로직의 단일 입력값으로 사용한다(여러 군데 중복 판정 금지).
E. Season Pass (from 08-ssot-season-pass)
SSOT 원칙
- 시즌 패스는 시즌별 구매 1회성 Entitlement로 운영한다.
- 시즌별 Store SKU를 분리한다(시즌별 SKU 1개 원칙).
- 예:
season_pass_s2026_01,season_pass_s2026_02
- 예:
- 소유 여부는 Firestore Entitlement 상태로 저장/복구한다.
- 시즌 패스 구매 결과는 Entitlement(
SeasonPass(season_id) owned)로 저장한다.
구매/지급 규칙
verifyPurchase결과가GRANTED인 경우에만, 해당 시즌owned=true로 반영한다.- 이미 소유(owned=true)인 시즌은 "추가 구매/중복 지급"이 발생하지 않도록 처리한다.
- 중복 방지는 서버 멱등 원장과 Entitlement 상태가 최종 방어선이다.
Legacy / Deprecated Notes
- 과거 문서에서
purchaseRecords,userEntitlements,subscriptionState같은 루트 컬렉션 명칭이 등장할 수 있다. - SSOT는 본 문서의
/users/{uid}/...스키마를 기준으로 한다.