@adstage/web-sdk 1.3.3 → 1.4.0

package/README.md

@@ -1,15 +1,21 @@
 # AdStage Web SDK
 
-> 🚀 **v1.2.0**: Standalone-First API로 더욱 간단해졌습니다!
+> **확장 가능한 네임스페이스 아키텍처**로 구현된 AdStage Web SDK
 
-모든 웹 프레임워크에서 사용 가능한 AdStage 광고 SDK입니다.
+# AdStage Web SDK
+
+> **동기 초기화**와 **네임스페이스 아키텍처**로 구현된 AdStage Web SDK
+
+## 🚀 새로운 기능
 
-## 🎯 특징
+### ✅ 즉시 사용 가능 (동기 API)
+- **⚡ 동기 초기화** - `await` 없이 즉시 사용 가능
+- **🎯 ads** - 광고 관리 (배너, 텍스트, 비디오, 네이티브, 전면)
+- **⚙️ config** - SDK 설정 및 선택적 API 키 검증
+- **🏃‍♂️ Lazy 로딩** - 즉시 placeholder 표시, 백그라운드 광고 로드
 
-- **프레임워크 독립적**: React, Vue, Angular, Vanilla JS 모든 환경 지원
-- **초간단 API**: Provider나 Hook 없이 함수 호출만으로 사용
-- **자동 최적화**: 중복 방지, ID 자동 생성, 스마트 캐싱
-- **완전한 TypeScript 지원**
+### 📅 구현 예정 모듈 (기본 구조 완성)
+- **📊 events** - 이벤트 추적 시스템 (Q1 2025)
 
 ## 📦 설치
 
@@ -17,46 +23,183 @@
 npm install @adstage/web-sdk
 ```
 
-## 🚀 빠른 시작
+## 🎯 빠른 시작
 
-### 1. SDK 초기화
-```javascript
-import { initAdStage } from '@adstage/web-sdk';
+### 네임스페이스 API (권장)
+
+```typescript
+import { AdStage } from '@adstage/web-sdk';
+
+// 1. 즉시 초기화 (동기)
+AdStage.init({
+  apiKey: 'your-api-key',
+  debug: true,
+  modules: ['ads', 'events'], // 필요한 모듈만 로드
+  validateOnInit: false       // 기본값: 즉시 사용 가능
+});
 
-await initAdStage({
-  apiKey: 'your-api-key'
+// 2. 즉시 광고 생성 (동기)
+const bannerId = AdStage.ads.banner('banner-container', {
+  width: '100%',
+  height: 250,
+  autoSlide: true
 });
+
+const textId = AdStage.ads.text('text-container', {
+  maxLines: 3,
+  style: 'card'
+});
+
+// 3. 이벤트 추적 (향후 구현)
+AdStage.events.track('page_view', {
+  page: '/products'
+});
+
+// 4. 광고 관리
+AdStage.ads.refresh('slot-id');
+AdStage.ads.destroy('slot-id');
+const allSlots = AdStage.ads.getAllSlots();
 ```
 
-### 2. 광고 생성
-```javascript
-import { createBanner } from '@adstage/web-sdk';
+### 간단한 사용법
 
-// HTML에 <div id="banner"></div> 준비 후
-await createBanner('banner');
+```typescript
+import { AdStage } from '@adstage/web-sdk';
+
+// 1. 즉시 초기화 (동기)
+AdStage.init({
+  apiKey: 'your-api-key',
+  debug: true
+});
+
+// 2. 즉시 광고 생성 (동기)
+const bannerId = AdStage.ads.banner('banner-container', {
+  width: '100%',
+  height: 250
+});
+
+const textId = AdStage.ads.text('text-container', {
+  maxLines: 3,
+  style: 'card'
+});
 ```
 
-### 3. 이벤트 추적
-```javascript
-import { trackEvent } from '@adstage/web-sdk';
+## 🏗 아키텍처 특징
+
+### 1. 모듈 독립성
+```typescript
+// 필요한 모듈만 선택적 로드
+AdStage.init({
+  modules: ['ads'] // ads 모듈만 로드 (~15KB)
+});
 
-trackEvent('button_click', { page: 'home' });
+AdStage.init({
+  modules: ['ads', 'events', 'config'] // 필요한 모듈만 (~25KB)
+});
 ```
 
-## 📋 API 레퍼런스
+### 2. 타입 안전성
+```typescript
+// TypeScript 완전 지원
+interface AdStageConfig {
+  apiKey: string;
+  debug?: boolean;
+  modules?: ModuleName[];
+}
+
+// 자동완성 지원
+AdStage.ads.banner('container', {
+  width: '100%',    // ✅ string
+  height: 250,      // ✅ number
+  autoSlide: true   // ✅ boolean
+});
+```
+
+### 3. 네임스페이스 보호
+```typescript
+// 충돌 방지 - 모든 기능이 AdStage 하위에 있음
+AdStage.ads.create()      // 다른 라이브러리와 충돌 없음
+AdStage.events.track()    // 안전한 네임스페이스
+AdStage.users.identify()  // 일관된 API 패턴
+```
+
+## 📊 번들 크기
+
+| 모듈 구성 | 크기 | 설명 |
+|-----------|------|------|
+| `['ads']` | ~15KB | 광고 기능만 |
+| `['ads', 'events']` | ~23KB | 광고 + 이벤트 |
+| `['ads', 'events', 'config']` | ~28KB | 모든 기능 포함 |
+
+## 🔮 향후 구현 계획
+
+### Q1 2025: 이벤트 시스템
+```typescript
+// 기본 이벤트 추적 (동기)
+AdStage.events.track('page_view', { page: '/products' });
+AdStage.events.userAction('button_click', { button_id: 'cta' });
+
+// 배치 처리
+AdStage.events.batch.start();
+AdStage.events.batch.add('event', { data: 'value' });
+AdStage.events.batch.flush(); // 백그라운드 전송
+```
+
+## 🎯 현재 상태
+
+### ✅ 완료된 작업
+- [x] 네임스페이스 아키텍처 설계
+- [x] **동기 초기화 시스템** (await 없는 즉시 사용 가능)
+- [x] **ads 모듈 완전 구현** (배너, 텍스트, 비디오, 네이티브, 전면)
+- [x] **config 모듈 완전 구현** (동기 초기화, 선택적 검증)
+- [x] events 모듈 기본 구조 및 인터페이스
+- [x] **Lazy 로딩 시스템** (즉시 placeholder, 백그라운드 광고 로드)
+- [x] TypeScript 타입 정의
+- [x] 예제 및 문서
+
+### 🚧 진행 중
+- [ ] AdsModule 통합 테스트
+- [ ] ConfigModule API 연동 테스트
+
+### 📋 다음 단계
+1. **Q1 2025**: EventsModule 완전 구현
+
+## 🛠 개발 가이드
+
+### 프로젝트 구조
+```
+src/
+├── core/
+│   └── AdStage.ts          # 메인 네임스페이스 클래스
+├── modules/
+│   ├── ads/                # ✅ 완전 구현됨 (동기)
+│   ├── config/             # ✅ 완전 구현됨 (동기)
+│   └── events/             # 🚧 기본 구조 (Q1 2025)
+├── types/
+│   ├── config.ts           # 설정 및 기본 타입
+│   └── advertisement.ts    # 광고 관련 타입
+├── constants/
+│   └── endpoints.ts        # API 엔드포인트 관리
+└── index.ts               # 메인 익스포트 (순수 네임스페이스만)
+```
+
+### 명명 규칙
+- **클래스/네임스페이스**: `AdStage` (대문자)
+- **타입**: `AdStageConfig` (대문자)  
+- **함수/변수**: `adstageInit`, `adstageConfig` (camelCase)
+
+## 📄 라이선스
+
+MIT License
 
-### 초기화
-- `initAdStage(config)` - SDK 초기화
-- `isAdStageReady()` - 초기화 상태 확인
+## 🤝 기여하기
 
-### 광고 생성
-- `createBanner(containerId, options?)` - 배너 광고
-- `createTextAd(containerId, options?)` - 텍스트 광고  
-- `createVideoAd(containerId, options?)` - 비디오 광고
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
-### 유틸리티
-- `trackEvent(name, params?)` - 이벤트 추적
-- `getAdStageInstance()` - SDK 인스턴스 (고급)
-- `destroyAdStage()` - SDK 정리
+---
 
-자세한 사용법은 [STANDALONE_GUIDE.md](./STANDALONE_GUIDE.md)를 참고하세요.
+**AdStage Web SDK** - 모든 AdStage 기능을 통합한 확장 가능한 SDK