AGENT SKILL
03-ssot
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-04-12
- Stars
- ★ 0
- Forks
- 0
03 SKILL.md 正文
03-ssot — 47-advertise-system (통합 SSOT)
Status: ACTIVE AppliesTo: v10
이 문서가 정본이다 (SSOT)
광고 관련 규칙의 단일 SSOT는 이 문서다.
ADVERTISE테이블 스키마advertise_id/reward_group_id/ 포맷 규칙- AdsManager의 책임과 provider 분리 규칙
- Rewarded 광고의 지급 위임 규칙
비정본(이 문서에서 다루지 않음):
- RewardData 스키마/보상 해석
49-reward-system
- 결제 NoAds entitlement 원장/복구
30-purchase-system
A) Core Terms (정본)
advertise_id: 광고 placement의 논리 키.ADVERTISE테이블 PK.format: 광고 포맷.ADVERTISE_FORMATprovider: 광고 SDK 구현체 키.ADVERTISE_PROVIDERreward_group_id: Rewarded 광고가 성공적으로 완료됐을 때 RewardManager에 전달하는 보상 그룹 키show cycle: 한 번의 show 시도 단위. Rewarded는 show cycle당 최대 1회만 지급한다.MockAdProvider: 네트워크 없이 scripted callback으로 동작하는 테스트용 provider
B) Content Source of Truth (정본)
광고 메타데이터 정본은 Game 도메인 안의 ADVERTISE 테이블이다.
- 위치:
input/Domains/Game/*.xlsx중ADVERTISEsheet를 포함한 파일 - 현재 샘플 파일:
input/Domains/Game/MetaTable.xlsx - sheet/table 정본 이름:
ADVERTISE - 생성 대상:
TB_ADVERTISE - 도메인 소속:
com.devian.foundation/Samples~/GamePackage(기존TB_REWARD와 동일) - 빌더 등록: 추가 등록 불필요.
{buildInputJson}(예:input/build_input.json)의domains.Game.tableFiles=["*.xlsx"]에 이미 포함된다.
AdsManager는 TB_ADVERTISE를 직접 참조하여 placement 설정을 읽는다.
C) ADVERTISE 테이블 스키마 (정본)
ADVERTISE는 1행=1광고 placement 구조다.
| 필드 | 타입 | Row 3 옵션 | 설명 |
|---|---|---|---|
Advertise_id |
string | pk | 광고 placement 논리 키 |
Format |
enum:ADVERTISE_FORMAT | BANNER / INTERSTITIAL / REWARDED / APP_OPEN |
|
Provider |
enum:ADVERTISE_PROVIDER | GOOGLE_MOBILE_ADS / MOCK |
|
Reward_group_id |
string | Rewarded 성공 시 지급할 보상 그룹 키 | |
Is_active |
bool | 활성 여부 | |
Auto_load |
bool | 초기화 후 자동 preload 여부 | |
Cooldown_sec |
int | 동일 placement 재표시 최소 간격(초) | |
Android_ad_unit_id |
string | Android ad unit id | |
Ios_ad_unit_id |
string | iOS ad unit id |
C-1) Format 규칙
Format=REWARDED이면Reward_group_id는 필수다.Format=BANNER|INTERSTITIAL|APP_OPEN이면Reward_group_id는 비워둔다.Provider는 현재GOOGLE_MOBILE_ADS또는MOCK만 허용한다.Is_active=false면 로드/표시 대상에서 제외한다.Cooldown_sec <= 0이면 쿨다운 없음으로 해석할 수 있다.
C-2) 광고 ID 해석 규칙
- 상위 로직은
advertise_id만 사용한다. - 플랫폼별 ad unit id(
Android_ad_unit_id,Ios_ad_unit_id)는 provider/AdsManager 레이어 내부에서만 해석한다. - 상위 로직이 ad unit id를 직접 알거나 분기하지 않는다.
D) Rewarded 지급 경로 (정본)
Rewarded 광고는 아래 순서를 따른다.
- 상위 로직이
ShowAsync(advertise_id, skip, ct)를 호출한다. - AdsManager가
TB_ADVERTISE.Get(advertise_id)로 row를 읽는다. skip=true이면 광고 없이SkipAndReward로 Reward만 즉시 지급하고 반환한다.- provider가 rewarded 광고를 표시한다.
- provider에서
reward earned콜백이 오면, AdsManager가 해당 show cycle의 중복 여부를 확인한다. Reward_group_id가 유효하면RewardManager.ApplyRewardGroup(reward_group_id)를 호출한다.- show cycle 종료 결과를 반환한다.
정본 규칙:
- 광고 시스템은
RewardData[]를 직접 생성하지 않는다. reward earned이전에 선지급하지 않는다.- 동일 show cycle에서 중복 reward 콜백이 와도 1회만 지급한다.
연관:
E) AdsManager 책임 (정본)
TB_ADVERTISE조회- provider 초기화/선택
- preload/show 상태 관리
- format별 gating(no-ads, consent, unsupported platform, cooldown)
- Rewarded 성공 시 RewardManager 호출
AdsManager의 비책임:
- 보상 내용 해석(
TB_REWARD직접 조회 금지) - 결제 entitlement 저장/복구
- 실광고 테스트 자동화
- 공급자 SDK 타입을 상위 로직으로 노출
F) Provider 분리 규칙 (정본)
- provider는
IAdProvider류의 공통 인터페이스 뒤로 숨긴다. - Google Mobile Ads SDK 의존은 provider 구현 파일에만 둔다.
- MockAdProvider는 동일 인터페이스를 구현해 Editor/CI 테스트 기본값으로 사용한다.
G) Non-goals
- 광고 수익 분석/BI 파이프라인
- mediation waterfall 설정 UI
- live ops A/B 실험 도구
H) Rewarded SSV (Server-Side Verification) 참조
AdMob SSV를 통해 Rewarded 광고 완료를 서버에서 검증하고 감사 로그를 기록한다.
- 보상 지급 방식: 클라이언트 즉시 지급 (현재 방식 유지). SSV는 감사/사후 검증 용도.
- SSV 서버 구현 정본: 40-ad-ssv-firebase
- SSV 고정 결정값: 41-ad-ssv-decisions
핵심 흐름:
- 클라이언트: Rewarded 로드 후
ServerSideVerificationOptions(userId, customData) 설정 - 유저 광고 시청 완료 → 클라이언트 즉시 보상 지급 (§D 경로 그대로)
- AdMob → Firebase HTTP endpoint로 SSV 콜백 전송
- 서버: ECDSA 서명 검증 → Firestore 감사 로그 기록