@adstage/web-sdk 3.0.1 → 3.0.3

package/README.md

@@ -1,47 +1,20 @@
-# AdStage Web SDK
+# adstage Web SDK
 
-> **프로덕션 레디** AdStage 마케팅 플랫폼 공식 웹 SDK
+> JavaScript/TypeScript SDK for AdStage marketing platform
 
-[![npm version](https://badge.fury.io/js/@adstage%2Fweb-sdk.svg)](https://www.npmjs.com/package/@adstage/web-sdk)
+[![npm version](https://img.shields.io/npm/v/%40adstage/web-sdk.svg?label=npm)](https://www.npmjs.com/package/@adstage/web-sdk)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-AdStage Web SDK는 멀티테넌트 마케팅 데이터 플랫폼인 AdStage의 웹 기능을 통합하는 JavaScript/TypeScript 라이브러리입니다. 딥링크 트래킹, 광고 표시, 이벤트 추적 등의 기능을 제공합니다.
-
-## ✨ 주요 기능
-
-### 🎯 광고 시스템 (완전 구현)
-- **5가지 광고 타입**: 배너, 텍스트, 비디오, 네이티브, 전면 광고
-- **타입별 렌더러**: 각 광고 타입에 최적화된 전용 렌더링 엔진
-- **스마트 슬라이더**: 여러 광고 자동 순환 및 페이드 효과
-- **Lazy 로딩**: 즉시 placeholder 표시, 백그라운드 광고 로드
-- **이벤트 추적**: 노출, 클릭, 뷰어빌리티 등 자동 추적
-- **중복 방지**: 동일 광고 중복 노출 방지 시스템
-
-### 🏗️ 모듈화 아키텍처 (v2.5.3+)
-- **팩토리 패턴**: AdRenderer가 광고 타입에 따라 적절한 렌더러 선택
-- **타입별 렌더러**: 
-  - `BannerAdRenderer`: 배너 광고 최적화 및 이미지 처리
-  - `TextAdRenderer`: 텍스트 전환 효과 및 스타일링
-  - `VideoAdRenderer`: 비디오 컨트롤 커스터마이징 및 폴백
-  - `NativeAdRenderer`: 네이티브 광고 레이아웃
-  - `InterstitialAdRenderer`: 전면 광고 오버레이
-- **공통 인터페이스**: 일관된 API와 확장 가능한 구조
-- **독립적 유지보수**: 각 광고 타입별 독립적 개발 및 테스트 가능
-
-### ⚙️ 설정 관리 (완전 구현)
-- **동기 초기화**: `await` 없이 즉시 사용 가능
-- **모듈 선택**: 필요한 기능만 선택적 로드
-- **환경 자동 감지**: 개발/프로덕션 환경 자동 설정
-- **런타임 설정 변경**: 실시간 설정 업데이트
-
-### 📊 이벤트 추적 (기본 구조 완성)
-- **커스텀 이벤트**: 사용자 정의 이벤트 추적
-- **페이지 뷰**: 자동 페이지 방문 추적
-- **배치 처리**: 효율적인 이벤트 전송
-- **오프라인 지원**: 네트워크 오류 시 로컬 저장
-
-## 📦 설치
+Lightweight SDK for rendering ads (banner / text / video) and tracking user events.
+
+## ✨ Features
+
+- Ad rendering: banner, text, video
+- Event tracking: clicks, page views, custom events
+
+
+## 📦 Installation
 
 ```bash
 # npm
@@ -54,573 +27,236 @@ yarn add @adstage/web-sdk
 pnpm add @adstage/web-sdk
 ```
 
-## 🚀 빠른 시작
+## 🚀 Quick Start
 
-### 기본 사용법
-
-```typescript
+```javascript
 import { AdStage } from '@adstage/web-sdk';
 
-// 1. SDK 초기화 (동기)
 AdStage.init({
-  apiKey: 'your-api-key',
-  debug: true,
-  modules: ['ads', 'config'] // 필요한 모듈만 로드
+  apiKey: 'your-api-key'
 });
 
-// 2. 광고 표시 (즉시 실행)
-const bannerId = AdStage.ads.banner('banner-container', {
-  width: '100%',
-  height: 250,
-  autoSlide: true,
-  slideInterval: 5000
-});
-
-// 3. 텍스트 광고
-const textId = AdStage.ads.text('text-container', {
-  maxLines: 3,
-  style: 'card'
-});
-```
-
-## 🏗️ 아키텍처 구조
-
-### 광고 렌더링 시스템
-
-```
-AdRenderer (Factory)
-├── IAdRenderer (Interface)
-├── BaseAdRenderer (Base Class)
-└── renderers/
-    ├── BannerAdRenderer     - 배너 광고 (이미지 최적화, 비율 계산)
-    ├── TextAdRenderer       - 텍스트 광고 (전환 효과, 스타일링)
-    ├── VideoAdRenderer      - 비디오 광고 (컨트롤 커스터마이징)
-    ├── NativeAdRenderer     - 네이티브 광고 (레이아웃 구성)
-    └── InterstitialAdRenderer - 전면 광고 (오버레이, 모달)
-```
-
-### 주요 클래스 관계
-
-```mermaid
-graph TD
-    A[AdStage] --> B[AdsModule]
-    B --> C[AdRenderer Factory]
-    C --> D[IAdRenderer Interface]
-    D --> E[BaseAdRenderer]
-    E --> F[BannerAdRenderer]
-    E --> G[TextAdRenderer]
-    E --> H[VideoAdRenderer]
-    E --> I[NativeAdRenderer]
-    E --> J[InterstitialAdRenderer]
-    
-    F --> K[CarouselSliderManager]
-    G --> L[TextTransitionManager]
-    
-    C --> M[AdvertisementEventTracker]
-    C --> N[ViewableEventTracker]
+AdStage.ads.banner('banner-container');
+AdStage.ads.text('text-container');
+AdStage.ads.video('video-container');
 ```
 
-### 렌더러별 특화 기능
+## 📖 Usage Examples
 
-| 렌더러 | 주요 기능 | 고유 특성 |
-|--------|-----------|-----------|
-| **BannerAdRenderer** | 이미지 최적화, 비율 계산 | 스마트 크기 조정, 다중 이미지 슬라이더 |
-| **TextAdRenderer** | 텍스트 전환, 스타일링 | 페이드 효과, 라인 제한, 그라디언트 배경 |
-| **VideoAdRenderer** | 비디오 제어, 폴백 처리 | 컨트롤 커스터마이징, 자동 이미지 폴백 |
-| **NativeAdRenderer** | 네이티브 레이아웃 | 제목/설명/CTA 구조화, 자연스러운 디자인 |
-| **InterstitialAdRenderer** | 전면 오버레이 | 모달 UI, ESC/클릭 닫기, 애니메이션 |
+### 1. Ad Rendering
 
-### HTML 마크업
+#### Plain HTML (UMD)
 
 ```html
 <!DOCTYPE html>
 <html>
-<head>
-  <title>AdStage 예제</title>
-</head>
 <body>
-  <!-- 광고 컨테이너 -->
-  <div id="banner-container"></div>
-  <div id="text-container"></div>
-  
-  <script type="module">
-    import { AdStage } from '@adstage/web-sdk';
-    
+  <div id="banner-ad"></div>
+  <div id="text-ad"></div>
+  <div id="video-ad"></div>
+
+  <script src="https://unpkg.com/@adstage/web-sdk/dist/index.umd.js"></script>
+  <script>
     AdStage.init({ apiKey: 'your-api-key' });
-    AdStage.ads.banner('banner-container');
-    AdStage.ads.text('text-container');
+    AdStage.ads.banner('banner-ad');
+    AdStage.ads.text('text-ad');
+    AdStage.ads.video('video-ad');
   </script>
 </body>
 </html>
 ```
 
-## 📖 상세 API 가이드
+#### ES Module (Standalone build)
 
-### 광고 모듈 (AdStage.ads)
+```javascript
+import { AdStage } from 'https://unpkg.com/@adstage/web-sdk/dist/index.standalone.js';
 
-#### 배너 광고
-```typescript
-const bannerId = AdStage.ads.banner('container-id', {
-  width: '100%',          // 너비 (px 또는 %)
-  height: 250,            // 높이 (px)
-  autoSlide: true,        // 자동 슬라이드
-  slideInterval: 5000,    // 슬라이드 간격 (ms)
-  onClick: (adData) => {  // 클릭 콜백
-    console.log('Ad clicked:', adData);
-  }
-});
+AdStage.init({ apiKey: 'your-api-key' });
+AdStage.ads.banner('banner-ad');
+AdStage.ads.text('text-ad');
+AdStage.ads.video('video-ad');
 ```
 
-#### 텍스트 광고
-```typescript
-const textId = AdStage.ads.text('container-id', {
-  maxLines: 3,            // 최대 라인 수
-  style: 'card',          // 스타일 ('default', 'card')
-  onClick: (adData) => {  // 클릭 콜백
-    console.log('Text ad clicked:', adData);
-  }
-});
-```
+#### React (Basic)
 
-#### 비디오 광고
-```typescript
-const videoId = AdStage.ads.video('container-id', {
-  width: 640,
-  height: 360,
-  autoplay: false,        // 자동 재생
-  muted: true,           // 음소거
-  onClick: (adData) => {
-    console.log('Video ad clicked:', adData);
-  }
-});
-```
-
-#### 광고 관리
-```typescript
-// 광고 새로고침
-AdStage.ads.refresh('slot-id');
-
-// 광고 제거
-AdStage.ads.destroy('slot-id');
-
-// 모든 광고 슬롯 조회
-const allSlots = AdStage.ads.getAllSlots();
+```jsx
+import { useEffect, useRef } from 'react';
+import { AdStage } from '@adstage/web-sdk';
 
-// 특정 슬롯 조회
-const slot = AdStage.ads.getSlotById('slot-id');
+export function Banner() {
+  const ref = useRef(null);
+  useEffect(() => {
+    AdStage.init({ apiKey: 'your-api-key' });
+    AdStage.ads.banner(ref.current.id);
+  }, []);
+  return <div id="banner-ad" ref={ref} />;
+}
 ```
 
-### 설정 모듈 (AdStage.config)
-
-```typescript
-// 현재 설정 조회
-const config = AdStage.config.getConfig();
+#### React (Provider + Hook)
 
-// 디버그 모드 확인
-const isDebug = AdStage.config.isDebugMode();
+```jsx
+import { AdStageProvider, useAdStageInstance } from '@adstage/web-sdk';
+import { useEffect, useRef } from 'react';
 
-// 모듈 활성화 확인
-const isAdsEnabled = AdStage.config.isModuleEnabled('ads');
-
-// 런타임 설정 변경
-AdStage.config.updateConfig({
-  debug: false,
-  timeout: 15000
-});
+export function App() {
+  return (
+    <AdStageProvider config={{ apiKey: 'your-api-key' }}>
+      <Banner />
+    </AdStageProvider>
+  );
+}
 
-// API 엔드포인트 확인
-const endpoint = AdStage.config.getApiEndpoint();
+function Banner() {
+  const ref = useRef(null);
+  const adstage = useAdStageInstance();
+  useEffect(() => {
+    if (adstage && ref.current) adstage.ads.banner(ref.current.id);
+  }, [adstage]);
+  return <div id="banner-ad" ref={ref} />;
+}
 ```
 
-### 이벤트 모듈 (AdStage.events) - 기본 구조
+### 2. Event Tracking
+
+#### Plain JS
 
-```typescript
-// 커스텀 이벤트 추적
-await AdStage.events.track('button_click', {
+```javascript
+AdStage.events.track('button_click', {
   button_id: 'cta',
-  page: '/pricing'
+  page: '/home'
 });
 
-// 페이지 뷰 추적
-await AdStage.events.pageView({
+AdStage.events.track('page_view', {
   page: '/products',
-  title: 'Products Page',
-  category: 'shopping'
-});
-
-// 사용자 액션 추적
-await AdStage.events.userAction('form_submit', {
-  form_id: 'contact',
-  email: 'user@example.com'
+  title: 'Products'
 });
-
-// 배치 이벤트 처리
-AdStage.events.batch.start();
-AdStage.events.batch.add('event1', { data: 'value1' });
-AdStage.events.batch.add('event2', { data: 'value2' });
-await AdStage.events.batch.flush();
 ```
 
-## 🔧 고급 설정
+#### Using Global Helpers
 
-### 모듈 선택적 로딩
+```javascript
+import { track, setUserId, setUserProperties } from '@adstage/web-sdk';
 
-```typescript
-// 광고 기능만 사용 (~15KB)
-AdStage.init({
-  apiKey: 'your-api-key',
-  modules: ['ads']
-});
-
-// 모든 기능 사용 (~28KB)
-AdStage.init({
-  apiKey: 'your-api-key',
-  modules: ['ads', 'events', 'config']
-});
+track('purchase', { value: 99 });
+setUserId('user123');
+setUserProperties({ country: 'KR', gender: 'male' });
 ```
 
-### 환경별 설정
-
-```typescript
-// 개발 환경
-AdStage.init({
-  apiKey: 'dev-api-key',
-  baseUrl: 'https://beta-api.adstage.app', // 베타 환경
-  debug: true,
-  validateOnInit: false
-});
-
-// 프로덕션 환경
-AdStage.init({
-  apiKey: 'prod-api-key',
-  baseUrl: 'https://api.adstage.io', // 프로덕션 환경
-  debug: false,
-  productionMode: true,
-  timeout: 10000
-});
-```
+## ⚙️ Configuration
 
-### 오류 처리
+### Basic Initialization
 
-```typescript
+```javascript
 AdStage.init({
   apiKey: 'your-api-key',
-  fallbackMode: true,    // 네트워크 오류 시 fallback 모드
-  offlineMode: false,    // 오프라인 모드 비활성화
   debug: true
 });
-
-try {
-  const bannerId = AdStage.ads.banner('container');
-} catch (error) {
-  console.error('광고 로드 실패:', error);
-  // fallback 처리
-}
-```
-
-## 📱 React 통합
-
-```tsx
-import React, { useEffect, useRef } from 'react';
-import { AdStage } from '@adstage/web-sdk';
-
-// React 컴포넌트 예제
-function AdBanner({ adType = 'banner', options = {} }) {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const slotIdRef = useRef<string | null>(null);
-
-  useEffect(() => {
-    if (!containerRef.current) return;
-
-    // SDK 초기화 (한 번만)
-    if (!AdStage.config.isReady()) {
-      AdStage.init({
-        apiKey: process.env.REACT_APP_ADSTAGE_API_KEY!,
-        debug: process.env.NODE_ENV === 'development'
-      });
-    }
-
-    // 광고 생성
-    const containerId = `ad-container-${Date.now()}`;
-    containerRef.current.id = containerId;
-
-    slotIdRef.current = AdStage.ads[adType](containerId, options);
-
-    // 정리
-    return () => {
-      if (slotIdRef.current) {
-        AdStage.ads.destroy(slotIdRef.current);
-      }
-    };
-  }, [adType, options]);
-
-  return <div ref={containerRef} />;
-}
-
-// 사용법
-function App() {
-  return (
-    <div>
-      <AdBanner 
-        adType="banner" 
-        options={{ width: '100%', height: 250 }} 
-      />
-      <AdBanner 
-        adType="text" 
-        options={{ maxLines: 3, style: 'card' }} 
-      />
-    </div>
-  );
-}
-```
-
-## 🏗 아키텍처 & 특징
-
-### 네임스페이스 아키텍처
-모든 기능이 `AdStage` 네임스페이스 하위에 체계적으로 구성되어 다른 라이브러리와의 충돌을 방지합니다.
-
-```typescript
-AdStage.ads.banner()     // 광고 기능
-AdStage.config.update()  // 설정 관리
-AdStage.events.track()   // 이벤트 추적
-```
-
-### 모듈 시스템
-필요한 기능만 선택적으로 로드하여 번들 크기를 최적화할 수 있습니다.
-
-| 모듈 조합 | 크기 | 포함 기능 |
-|-----------|------|-----------|
-| `['ads']` | ~15KB | 광고 표시만 |
-| `['ads', 'config']` | ~20KB | 광고 + 설정 관리 |
-| `['ads', 'events', 'config']` | ~28KB | 모든 기능 |
-
-### TypeScript 완전 지원
-모든 API에 대한 완전한 타입 정의를 제공하여 개발 경험을 향상시킵니다.
-
-```typescript
-interface AdStageConfig {
-  apiKey: string;
-  debug?: boolean;
-  modules?: ModuleName[];
-  baseUrl?: string;
-  timeout?: number;
-}
-
-// 자동완성 및 타입 검사
-AdStage.ads.banner('container', {
-  width: '100%',    // ✅ string | number
-  height: 250,      // ✅ number
-  autoSlide: true   // ✅ boolean
-});
 ```
 
-### 동기 초기화
-`await` 없이 즉시 사용 가능한 동기 API로 설계되어 개발이 간편합니다.
+### Ad Rendering (with options)
 
-```typescript
-// ✅ 동기 - 즉시 사용 가능
-AdStage.init({ apiKey: 'key' });
-const id = AdStage.ads.banner('container');
-
-// ❌ 비동기 - 복잡한 처리 필요
-await AdStage.init({ apiKey: 'key' });
-const id = await AdStage.ads.banner('container');
-```
-
-## 📊 번들 크기 & 성능
-
-### 최적화된 번들 크기
-```
-dist/
-├── index.esm.js     # ES 모듈 (28KB gzipped)
-├── index.cjs.js     # CommonJS (30KB gzipped) 
-├── index.umd.js     # UMD 브라우저 (32KB gzipped)
-└── index.d.ts       # TypeScript 타입 정의
-```
-
-### Tree Shaking 지원
-ES 모듈 형태로 제공되어 번들러의 tree shaking으로 사용하지 않는 코드 제거가 가능합니다.
-
-```typescript
-// 필요한 모듈만 임포트
-import { AdStage } from '@adstage/web-sdk';
-
-// 특정 타입만 임포트
-import type { AdStageConfig, AdOptions } from '@adstage/web-sdk';
-```
-
-### Lazy 로딩 시스템
-광고 콘텐츠는 백그라운드에서 로드되어 사용자 경험을 향상시킵니다.
-
-```typescript
-// 1. 즉시 placeholder 표시
-const id = AdStage.ads.banner('container');
-
-// 2. 백그라운드에서 광고 로드
-// 3. 로드 완료 시 실제 광고로 교체
+```javascript
+AdStage.ads.banner('container-id', { width: '100%', height: 250 });
+AdStage.ads.text('container-id', { maxLines: 3 });
+AdStage.ads.video('container-id', { width: 640, height: 360, autoplay: false });
 ```
 
-## 🔌 브라우저 지원
+### Ad Options Table
 
-- **모던 브라우저**: Chrome 80+, Firefox 80+, Safari 14+, Edge 80+
-- **ES 모듈**: ES2018+ 지원 브라우저
-- **폴리필**: 필요시 별도 제공
-- **SSR 안전**: Next.js, Nuxt.js 등 SSR 프레임워크 지원
+#### Banner
 
-```typescript
-// SSR 환경에서 안전하게 사용
-if (typeof window !== 'undefined') {
-  AdStage.init({ apiKey: 'your-key' });
-}
-```
+| Option         | Type        | Default  | Description                |
+| -------------- | ----------- | -------- | -------------------------- |
+| `width`      | `string     | number`  | `'100%'`                 |
+| `height`     | `number`  | `250`  | Height (px)                |
+| `position`   | `'top'      | 'bottom' | 'center'`                  |
+| `responsive` | `boolean` | `true` | Enable responsive resizing |
 
-## 🚧 개발 상태
-
-### ✅ 완료된 기능
-- [x] **네임스페이스 아키텍처** - 충돌 방지 및 체계적 구조
-- [x] **동기 초기화 시스템** - `await` 없는 즉시 사용 가능
-- [x] **광고 모듈 (AdsModule)** - 5가지 광고 타입 완전 구현
-  - [x] 배너, 텍스트, 비디오, 네이티브, 전면 광고
-  - [x] 자동 슬라이더 및 페이드 효과
-  - [x] Lazy 로딩 시스템
-  - [x] 이벤트 추적 및 중복 방지
-- [x] **설정 모듈 (ConfigModule)** - 동기 설정 관리
-  - [x] 환경 자동 감지
-  - [x] 런타임 설정 변경
-  - [x] 모듈 선택적 로딩
-- [x] **TypeScript 타입 정의** - 완전한 타입 안전성
-- [x] **다중 빌드 타겟** - ESM/CJS/UMD 지원
-- [x] **SSR 지원** - Next.js, Nuxt.js 등 호환
-
-### 🚧 기본 구조 완성 (향후 구현)
-- [ ] **이벤트 모듈 (EventsModule)** - Q1 2025 구현 예정
-  - [x] 기본 인터페이스 및 메소드 구조
-  - [ ] 실제 서버 통신 로직
-  - [ ] 배치 처리 시스템
-  - [ ] 오프라인 지원
-
-### 📋 다음 단계
-1. **Q1 2025**: EventsModule 완전 구현
-2. **Q2 2025**: 성능 최적화 및 고급 타겟팅
-3. **Q3 2025**: A/B 테스트 및 개인화 기능
-
-## 🛠 개발 가이드
-
-### 프로젝트 구조
-```
-src/
-├── core/
-│   └── AdStage.ts              # 메인 네임스페이스 클래스
-├── modules/
-│   ├── ads/                    # ✅ 광고 모듈 (완전 구현)
-│   │   └── AdsModule.ts
-│   ├── config/                 # ✅ 설정 모듈 (완전 구현)
-│   │   └── ConfigModule.ts
-│   └── events/                 # 🚧 이벤트 모듈 (기본 구조)
-│       └── EventsModule.ts
-├── managers/                   # 기능별 관리 클래스
-│   ├── event-tracker.ts        # 이벤트 추적
-│   ├── impression-tracker.ts   # 중복 노출 방지
-│   ├── carousel-slider-manager.ts  # 슬라이더 관리
-│   └── text-transition-manager.ts  # 텍스트 전환 효과
-├── types/                      # TypeScript 타입 정의
-│   ├── config.ts               # SDK 설정 타입
-│   ├── advertisement.ts        # 광고 관련 타입
-│   ├── events.ts              # 이벤트 관련 타입
-│   └── api.ts                 # API 응답 타입
-├── utils/                      # 유틸리티 함수
-│   ├── sdk-utils.ts           # SDK 공통 유틸
-│   ├── dom-utils.ts           # DOM 조작 유틸
-│   └── api-headers.ts         # API 헤더 생성
-├── constants/
-│   └── endpoints.ts           # API 엔드포인트 관리
-└── index.ts                   # 메인 익스포트
-```
+#### Text
 
-### 로컬 개발
+| Option        | Type       | Default  | Description       |
+| ------------- | ---------- | -------- | ----------------- |
+| `maxLines`  | `number` | `3`    | Max visible lines |
+| `fontSize`  | `number` | `14`   | Font size (px)    |
+| `textAlign` | `'left'    | 'center' | 'right'`          |
 
-```bash
-# 의존성 설치
-pnpm install
+#### Video
 
-# 개발 모드 (watch)
-pnpm run dev
+| Option       | Type        | Default   | Description                            |
+| ------------ | ----------- | --------- | -------------------------------------- |
+| `width`    | `number`  | `640`   | Video width (px)                       |
+| `height`   | `number`  | `360`   | Video height (px)                      |
+| `autoplay` | `boolean` | `false` | Auto play on load                      |
+| `muted`    | `boolean` | `true`  | Start muted (recommended for autoplay) |
+| `controls` | `boolean` | `true`  | Show native controls                   |
+| `loop`     | `boolean` | `false` | Loop playback                          |
 
-# 타입 체크
-pnpm run lint
+## 📚 API Reference
 
-# 빌드
-pnpm run build
-```
+### Core (Common)
 
-### 네이밍 규칙
-- **클래스/네임스페이스**: PascalCase (`AdStage`, `AdsModule`)
-- **인터페이스/타입**: PascalCase (`AdStageConfig`, `Advertisement`)
-- **함수/변수**: camelCase (`init`, `isReady`)
-- **상수**: UPPER_SNAKE_CASE (`API_ENDPOINTS`, `DEFAULT_CONFIG`)
+| Function      | Description                 | Params                                  | Returns     | Example                             |
+| ------------- | --------------------------- | --------------------------------------- | ----------- | ----------------------------------- |
+| `init()`    | Initialize SDK (required)   | `{ apiKey: string, debug?: boolean }` | `void`    | `AdStage.init({ apiKey: 'key' })` |
+| `isReady()` | Check initialization status | -                                       | `boolean` | `AdStage.isReady()`               |
+| `reset()`   | Reset state (testing)       | -                                       | `void`    | `AdStage.reset()`                 |
 
-### 코딩 스타일
-- **TypeScript strict 모드** 활성화
-- **ESLint + Prettier** 자동 포맷팅
-- **JSDoc 주석** 모든 public API에 필수
-- **에러 처리** 모든 async 함수에 try-catch
+### Ads Module (`AdStage.ads`)
 
-## 🤝 기여하기
+| Function     | Description      | Params                    | Returns           | Example                        |
+| ------------ | ---------------- | ------------------------- | ----------------- | ------------------------------ |
+| `banner()` | Render banner ad | `containerId, options?` | `Promise<void>` | `AdStage.ads.banner('slot')` |
+| `text()`   | Render text ad   | `containerId, options?` | `Promise<void>` | `AdStage.ads.text('slot')`   |
+| `video()`  | Render video ad  | `containerId, options?` | `Promise<void>` | `AdStage.ads.video('slot')`  |
 
-### 버그 리포트
-이슈를 발견하셨다면 다음 정보와 함께 GitHub Issues에 신고해 주세요:
+### Events Module (`AdStage.events`)
 
-- SDK 버전
-- 브라우저 및 버전
-- 재현 단계
-- 예상 동작 vs 실제 동작
-- 최소 재현 코드
+| Function                | Description         | Params                | Returns           | Example                                                 |
+| ----------------------- | ------------------- | --------------------- | ----------------- | ------------------------------------------------------- |
+| `track()`             | Track an event      | `name, properties?` | `Promise<void>` | `AdStage.events.track('click')`                       |
+| `setUserId()`         | Set user ID         | `userId`            | `void`          | `AdStage.events.setUserId('u1')`                      |
+| `getUserId()`         | Get user ID         | -                     | `string           | null`                                                   |
+| `setUserProperties()` | Set user attributes | `UserProperties`    | `void`          | `AdStage.events.setUserProperties({ country: 'KR' })` |
+| `getUserProperties()` | Get user attributes | -                     | `UserProperties   | null`                                                   |
 
-### 기능 요청
-새로운 기능이나 개선사항이 있다면 제안해 주세요:
+#### UserProperties
 
-1. GitHub Issues에서 기능 요청 템플릿 사용
-2. 사용 사례 및 동기 설명
-3. 예상 API 디자인 제안
+| Field        | Type       | Description             | Example     |
+| ------------ | ---------- | ----------------------- | ----------- |
+| `gender`   | `string` | Gender                  | `'male'`  |
+| `country`  | `string` | ISO 3166-1 country code | `'KR'`    |
+| `city`     | `string` | City name               | `'Seoul'` |
+| `age`      | `string` | Age band or value       | `'20-29'` |
+| `language` | `string` | ISO 639-1 language code | `'en'`    |
 
-### 개발 기여
+### Global Helper Functions
 
-```bash
-# 1. 포크 및 클론
-git clone https://github.com/your-username/adstage.git
-cd adstage/sdk
+Firebase‑style named exports. Equivalent to `AdStage.events.*`.
 
-# 2. 의존성 설치
-pnpm install
+| Function                | Description         | Equivalent                             |
+| ----------------------- | ------------------- | -------------------------------------- |
+| `track()`             | Track event         | `AdStage.events.track()`             |
+| `setUserId()`         | Set user ID         | `AdStage.events.setUserId()`         |
+| `getUserId()`         | Get user ID         | `AdStage.events.getUserId()`         |
+| `setUserProperties()` | Set user attributes | `AdStage.events.setUserProperties()` |
+| `getUserProperties()` | Get user attributes | `AdStage.events.getUserProperties()` |
 
-# 3. 기능 브랜치 생성
-git checkout -b feature/amazing-feature
+### React Components & Hooks
 
-# 4. 개발 및 테스트
-pnpm run dev
-pnpm run build
-pnpm run lint
+| Name                   | Type      | Returns                              | Purpose                 |
+| ---------------------- | --------- | ------------------------------------ | ----------------------- |
+| `AdStageProvider`    | Component | -                                    | Provide SDK via context |
+| `useAdStageInstance` | Hook      | `AdStage                             | null`                   |
+| `useAdStageContext`  | Hook      | `{ isInitialized, config, error }` | State / error handling  |
 
-# 5. 커밋 및 푸시
-git commit -m '✨ Add amazing feature'
-git push origin feature/amazing-feature
+#### Hook Usage
 
-# 6. Pull Request 생성
+```jsx
+const adstage = useAdStageInstance();
+adstage?.events.track('click', { button: 'cta' });
 ```
 
-## 📄 라이선스
-
-MIT License © 2024 AdStage
-
-자세한 내용은 [LICENSE](./LICENSE) 파일을 참조하세요.
-
-## 🔗 링크
-
-- [📖 공식 문서](https://docs.adstage.io)
-- [🐛 이슈 신고](https://github.com/nbase-io/adstage/issues)
-- [💬 디스커션](https://github.com/nbase-io/adstage/discussions)
-- [📦 NPM 패키지](https://www.npmjs.com/package/@adstage/web-sdk)
-
----
+## 📄 License
 
-**AdStage Web SDK** - 프로덕션 환경에서 검증된 마케팅 플랫폼 통합 솔루션
+MIT License © 2025 stageUp