App Registration

App Registration

SDK를 붙이려면 먼저 appId가 있어야 합니다. 앱 레지스트리의 source of truth는 저장소의 registry/apps/*.json이고, 파일 하나가 앱 하나입니다. 콘솔이나 Firestore를 직접 고치지 않습니다.

절차

1. registry/apps/<app_id>.json을 추가하는 PR을 엽니다.
2. CI의 regsync --dry-run이 스키마를 검증합니다. 모르는 키가 하나라도 있으면 실패합니다 — 오타로 기능이 꺼진 채 배포되는 걸 막기 위해서입니다.
3. 병합 후 메인테이너가 cmd/regsync로 Firestore에 올립니다. 파일을 고치는 것만으로는 아무 일도 일어나지 않습니다. 런타임은 Firestore를 60초 TTL 캐시로 읽습니다.

3번이 빠지면 app_unknown이 계속 납니다. 실제로 겪은 사고가 README에 적혀 있습니다.

flowchart LR
  A["registry/apps/app-id.json<br/>PR"] --> B["CI — regsync --dry-run<br/>스키마 검증 · 미지 키 거부"]
  B --> C["main 병합"]
  C --> D["메인테이너가 regsync 실행"]
  D --> E[("Firestore apps/app-id")]
  E --> F["런타임 캐시<br/>TTL 60초"]
  F --> G["SDK 호출 허용"]
  C -.->|regsync 누락| H["파일만 바뀌고 런타임은 옛 값<br/>app_unknown 계속"]

Loading

최소 항목

{
  "app_id": "my-app",                       // 소문자·숫자·하이픈, 64자 이내
  "display_name": "내 앱",
  "firebase_project_id": "my-app-firebase",
  "status": "active",                       // active | paused (kill switch)
  "features": {
    "events": true,
    "config": true,
    "iap": false,
    "ads": false,
    "content": false,
    "firebase_custom_token_bridge": false
  },
  "require_app_check": false,
  "ga4": { "event_prefix": "" },
  "platform_event_allowlist": [],           // 비우면 전부 허용
  "cors_origins": []                        // 웹·AppsInToss WebView·Capacitor만
}

기능 플래그

features.*	켜면 필요한 것
events	없음
config	없음
iap	iap 블록 — ledger_environment, markets, entitlement_ids(비어 있으면 안 됨), 마켓별 패키지·번들 ID
ads	ads.providers와 ads.placements — 광고 unit, reward 범위, daily_limit, cooldown_seconds. 여기가 원장이고 운영툴은 읽기만
firebase_custom_token_bridge	같은 Firebase 프로젝트의 firebase_custom_token_service_account. 비밀이 아니고 private key는 저장하지 않음 — 서버는 IAM signJwt 권한만 받음
presence	없음. SDK 쪽 presenceEnabled와 둘 다 켜져야 heartbeat 동작
content	운글 전용

인증 관련

항목	뜻
require_app_check	custom token 발급과 계정 삭제 경계에서 X-Firebase-AppCheck 강제. 실기기 attestation을 확인한 뒤에만 true
auth.account_providers	Kakao·Apple OIDC ID token의 aud allowlist. 카카오는 앱 ID가 아니라 앱 키, Apple은 bundle ID. secret은 넣지 않음
iap.require_linked_account	true면 구매·복원·계정 참조 발급이 연결 세션에서만 가능

AppsInToss는 mTLS Toss Login 세션을 연결 계정으로 보므로 account_providers를 쓰지 않습니다.

왜 API key가 없나

클라이언트 바이너리에 박히는 순간 비밀이 아닙니다. 진짜 인증은 토큰의 aud 검증이 담당합니다 — 어떤 앱을 사칭하려면 그 Firebase 프로젝트의 유효한 ID 토큰이 필요합니다. X-Seori-App 헤더는 어느 프로젝트로 검증할지 고르는 힌트일 뿐 권한이 아닙니다.

status: paused

kill switch입니다. 해당 앱의 모든 플랫폼 호출이 즉시 app_paused(403)가 됩니다. 진행 중인 결제도 막히므로 — 이미 마켓에서 과금된 구매가 pending으로 남습니다 — 정지가 길수록 CS가 늘어납니다.

개별 계정 차단은 레지스트리가 아니라 Admin API(/v1/admin/apps/{appId}/blocks)로 합니다. 사용자 식별자는 git에 넣지 않습니다.

전체 형식과 규칙

필드 전체, CORS origin 규칙, IAP 카탈로그 매핑, 환경 불일치 진단은 registry/apps/README.md에 있습니다. 등록된 앱 목록도 거기 있습니다.