@adstage/web-sdk 2.6.1 → 2.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adstage/web-sdk",
-  "version": "2.6.1",
+  "version": "2.6.3",
   "description": "AdStage Web SDK - Production-ready marketing platform SDK with React Provider support for seamless integration",
   "type": "module",
   "main": "dist/index.cjs.js",
@@ -11,7 +11,9 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.esm.js",
       "require": "./dist/index.cjs.js"
-    }
+    },
+    "./standalone": "./dist/index.standalone.js",
+    "./umd": "./dist/index.umd.js"
   },
   "files": [
     "dist",

package/src/constants/endpoints.ts

@@ -33,7 +33,6 @@ export const API_PATHS = {
   /** 이벤트 관련 */
   events: {
     track: '/events/track',
-    batch: '/events/batch'
   }
 } as const;
 
@@ -77,7 +76,6 @@ export class EndpointBuilder {
    */
   events = {
     track: () => `${this.baseUrl}${API_PATHS.events.track}`,
-    batch: () => `${this.baseUrl}${API_PATHS.events.batch}`
   };
 
   /**

package/src/events/global-events.ts

@@ -0,0 +1,72 @@
+/**
+ * AdStage SDK - 전역 이벤트 함수들
+ * Firebase Analytics와 유사한 간단한 API 제공
+ */
+
+import AdStage from '../core/adstage';
+import type { EventProperties, PageData } from '../modules/events/events-module';
+
+/**
+ * 이벤트 추적 (메인 함수)
+ * @param eventName 이벤트 이름
+ * @param properties 이벤트 속성
+ * 
+ * @example
+ * track('purchase', {
+ *   transaction_id: 'T123',
+ *   value: 99.99,
+ *   currency: 'USD'
+ * });
+ */
+export function track(eventName: string, properties?: EventProperties): Promise<void> {
+  if (!AdStage.isReady()) {
+    console.warn('AdStage not initialized. Call AdStage.init() first.');
+    return Promise.resolve();
+  }
+  
+  return AdStage.events.track(eventName, properties);
+}
+
+/**
+ * 페이지 뷰 추적
+ * @param pageData 페이지 정보
+ * 
+ * @example
+ * pageView({ page: '/products', title: 'Products Page' });
+ */
+export function pageView(pageData?: PageData): Promise<void> {
+  if (!AdStage.isReady()) {
+    console.warn('AdStage not initialized. Call AdStage.init() first.');
+    return Promise.resolve();
+  }
+  
+  return AdStage.events.pageView(pageData);
+}
+
+/**
+ * 사용자 ID 설정
+ * @param userId 사용자 ID
+ * 
+ * @example
+ * setUserId('user123');
+ */
+export function setUserId(userId: string): void {
+  if (!AdStage.isReady()) {
+    console.warn('AdStage not initialized. Call AdStage.init() first.');
+    return;
+  }
+  
+  AdStage.events.setUserId(userId);
+}
+
+/**
+ * 현재 사용자 ID 반환
+ */
+export function getUserId(): string | undefined {
+  if (!AdStage.isReady()) {
+    console.warn('AdStage not initialized. Call AdStage.init() first.');
+    return undefined;
+  }
+  
+  return AdStage.events.getUserId();
+}

package/src/example/events/README.md

@@ -0,0 +1,125 @@
+# AdStage SDK - 이벤트 추적 예시
+
+EventLogGenerator의 파라미터를 참고하여 만든 간단한 이벤트 추적 예시들입니다.
+
+## 📁 폴더 구조
+
+```
+events/
+├── javascript/     # Vanilla JS 예시
+├── react/         # React 예시  
+└── nextjs/        # Next.js 예시
+```
+
+## 🚀 실행 방법
+
+### JavaScript (Vanilla JS)
+```bash
+# 브라우저에서 직접 열기 (NPM CDN 사용)
+open javascript/index.html
+```
+
+### React
+```bash
+cd react
+npm install  # @adstage/web-sdk@^2.6.1 설치됨
+npm start
+# http://localhost:3000
+```
+
+### Next.js
+```bash
+cd nextjs
+npm install  # @adstage/web-sdk@^2.6.1 설치됨
+npm run dev
+# http://localhost:3000
+```
+
+## 📊 구현된 이벤트 타입
+
+### JavaScript 예시
+- `purchase` - 구매 이벤트
+- `signup_complete` - 회원가입 이벤트
+- `page_view` - 페이지뷰 이벤트
+
+### React 예시  
+- `purchase` - 구매 이벤트
+- `signup_complete` - 회원가입 이벤트
+- `view_item` - 상품조회 이벤트
+
+### Next.js 예시
+- `add_to_cart` - 장바구니 추가 이벤트
+- `first_open` - 앱 설치 이벤트
+- `search` - 검색 이벤트
+
+## 🎯 공통 특징
+
+- **흰 바탕에 간단한 버튼 3개**
+- **각 버튼마다 다른 이벤트 전송**
+- **EventLogGenerator 파라미터 구조 참고**
+- **실시간 결과 표시**
+- **자동 페이지뷰 추적**
+
+## 📋 이벤트 파라미터 예시
+
+모든 예시는 EventLogGenerator에서 사용하는 실제 파라미터 구조를 따릅니다:
+
+```javascript
+// 구매 이벤트
+{
+  transaction_id: "tx_1725123456789",
+  value: 99000,
+  currency: "KRW", 
+  payment_method: "card",
+  items: 2,
+  category: "electronics",
+  brand: "Samsung"
+}
+
+// 회원가입 이벤트
+{
+  user_id: "user_1725123456789",
+  signup_method: "email",
+  email_verified: true,
+  time_to_complete: 120,
+  form_version: "v2",
+  utm_source: "google_ads",
+  utm_medium: "cpc"
+}
+
+// 페이지뷰 이벤트
+{
+  page: "/",
+  title: "Home Page",
+  referrer: "direct",
+  utm_source: "organic"
+}
+```
+
+## 🔧 SDK 설정
+
+모든 예시에서 동일한 SDK 설정을 사용합니다:
+
+```javascript
+AdStage.init({
+  apiKey: '7dfddcfda637fbb73225bac3731688b80b90675942fe9f2057a88e2379aba2a4',
+  debug: true,
+  appVersion: '1.2.3' // 각 플랫폼별로 다른 버전
+});
+```
+
+## 📦 SDK 로드 방법
+
+### JavaScript (CDN)
+```html
+<script src="https://unpkg.com/@adstage/web-sdk@latest/dist/index.standalone.js"></script>
+```
+
+### React/Next.js (NPM)
+```json
+{
+  "dependencies": {
+    "@adstage/web-sdk": "^2.6.1"
+  }
+}
+```

package/src/example/events/javascript/index-esm.html

@@ -0,0 +1,159 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>AdStage SDK - 이벤트 추적 예시 (ESM)</title>
+    <style>
+        body {
+            font-family: Arial, sans-serif;
+            padding: 20px;
+            background-color: white;
+        }
+        
+        button {
+            padding: 12px 24px;
+            margin: 10px;
+            font-size: 16px;
+            border: 1px solid #ccc;
+            border-radius: 4px;
+            background-color: #f8f9fa;
+            cursor: pointer;
+        }
+        
+        button:hover {
+            background-color: #e9ecef;
+        }
+        
+        button:active {
+            background-color: #dee2e6;
+        }
+        
+        .result {
+            margin-top: 20px;
+            padding: 15px;
+            border: 1px solid #ddd;
+            border-radius: 4px;
+            background-color: #f8f9fa;
+            white-space: pre-wrap;
+            font-family: monospace;
+        }
+
+        .note {
+            background: #e3f2fd;
+            padding: 15px;
+            border-left: 4px solid #2196f3;
+            margin: 20px 0;
+        }
+    </style>
+</head>
+<body>
+    <h1>AdStage SDK - 이벤트 추적 예시 (ESM 방식)</h1>
+    
+    <div class="note">
+        <strong>📋 ESM 방식:</strong><br>
+        • ES Module을 지원하는 모던 브라우저에서 사용<br>
+        • 번들러 없이 직접 import 가능<br>
+        • Tree-shaking 최적화 지원
+    </div>
+
+    <div>
+        <button id="purchaseBtn">구매 이벤트 전송</button>
+        <button id="signupBtn">회원가입 이벤트 전송</button>
+        <button id="pageViewBtn">페이지뷰 이벤트 전송</button>
+    </div>
+
+    <div id="result" class="result">이벤트 결과가 여기에 표시됩니다.</div>
+
+    <!-- ESM 방식: ES Module import -->
+    <script type="module">
+        // ESM 방식으로 SDK import
+        import { AdStage, track } from 'https://unpkg.com/@adstage/web-sdk@2.6.2/dist/index.standalone.js';
+
+        // SDK 초기화
+        AdStage.init({
+            apiKey: 'c06e2bc7c7244e111d90e530227274898de66ac9f3b5dbeae10e7615c1c616de',
+            debug: true,
+            baseUrl: 'https://beta-api.adstage.app',
+            appVersion: '1.2.3',
+        });
+
+        // 결과 표시 함수
+        function showResult(message) {
+            document.getElementById('result').textContent = message;
+        }
+
+        // 구매 이벤트
+        async function trackPurchase() {
+            try {
+                showResult('구매 이벤트 전송 중...');
+                
+                await track('purchase', {
+                    currency: 'KRW',
+                    value: 29900,
+                    item_id: 'premium_plan_001',
+                    item_name: '프리미엄 플랜',
+                    item_category: 'subscription',
+                    quantity: 1,
+                    payment_type: 'credit_card',
+                    transaction_id: 'txn_' + Date.now()
+                });
+                
+                showResult('✅ 구매 이벤트가 성공적으로 전송되었습니다!');
+            } catch (error) {
+                showResult('❌ 구매 이벤트 전송 실패: ' + error.message);
+            }
+        }
+
+        // 회원가입 이벤트
+        async function trackSignup() {
+            try {
+                showResult('회원가입 이벤트 전송 중...');
+                
+                await track('sign_up', {
+                    method: 'email',
+                    user_type: 'advertiser',
+                    signup_source: 'landing_page',
+                    utm_source: 'google',
+                    utm_medium: 'cpc',
+                    utm_campaign: 'brand_keywords'
+                });
+                
+                showResult('✅ 회원가입 이벤트가 성공적으로 전송되었습니다!');
+            } catch (error) {
+                showResult('❌ 회원가입 이벤트 전송 실패: ' + error.message);
+            }
+        }
+
+        // 페이지뷰 이벤트
+        async function trackPageView() {
+            try {
+                showResult('페이지뷰 이벤트 전송 중...');
+                
+                await track('page_view', {
+                    page_title: document.title,
+                    page_location: window.location.href,
+                    page_referrer: document.referrer || '직접 접속',
+                    content_group1: 'example',
+                    content_group2: 'events',
+                    session_id: 'sess_' + Date.now()
+                });
+                
+                showResult('✅ 페이지뷰 이벤트가 성공적으로 전송되었습니다!');
+            } catch (error) {
+                showResult('❌ 페이지뷰 이벤트 전송 실패: ' + error.message);
+            }
+        }
+
+        // 이벤트 리스너 등록
+        document.getElementById('purchaseBtn').addEventListener('click', trackPurchase);
+        document.getElementById('signupBtn').addEventListener('click', trackSignup);
+        document.getElementById('pageViewBtn').addEventListener('click', trackPageView);
+
+        // 페이지 로드 시 자동으로 페이지뷰 이벤트 전송
+        window.addEventListener('load', () => {
+            setTimeout(() => {
+                trackPageView();
+            }, 1000);
+        });
+    </script>
+</body>
+</html>

package/src/example/events/javascript/index.html

@@ -0,0 +1,151 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>AdStage SDK - 이벤트 추적 예시</title>
+    <style>
+        body {
+            font-family: Arial, sans-serif;
+            padding: 20px;
+            background-color: white;
+        }
+        
+        button {
+            padding: 12px 24px;
+            margin: 10px;
+            font-size: 16px;
+            border: 1px solid #ccc;
+            border-radius: 4px;
+            background-color: #f8f9fa;
+            cursor: pointer;
+        }
+        
+        button:hover {
+            background-color: #e9ecef;
+        }
+        
+        button:active {
+            background-color: #dee2e6;
+        }
+        
+        .result {
+            margin-top: 20px;
+            padding: 15px;
+            border: 1px solid #ddd;
+            border-radius: 4px;
+            background-color: #f8f9fa;
+            white-space: pre-wrap;
+            font-family: monospace;
+        }
+    </style>
+</head>
+<body>
+    <h1>AdStage SDK - 이벤트 추적 예시</h1>
+    
+    <div>
+        <button onclick="trackPurchase()">구매 이벤트 전송</button>
+        <button onclick="trackSignup()">회원가입 이벤트 전송</button>
+        <button onclick="trackPageView()">페이지뷰 이벤트 전송</button>
+    </div>
+    
+    <div id="result" class="result">이벤트 결과가 여기에 표시됩니다.</div>
+
+    <!-- AdStage SDK - UMD 방식 (브라우저 호환성을 위한 UMD 포맷) -->
+    <script src="https://unpkg.com/@adstage/web-sdk@2.6.2/dist/index.umd.js"></script>
+    <script>
+        // SDK 초기화
+        AdStage.init({
+            apiKey: 'c06e2bc7c7244e111d90e530227274898de66ac9f3b5dbeae10e7615c1c616de',
+            debug: true,
+            baseUrl: 'https://beta-api.adstage.app',
+            appVersion: '1.2.3',
+        });
+
+        // 사용자 ID 설정
+        AdStage.events.setUserId('gunny1234');
+
+        // 사용자 속성 설정
+        AdStage.events.setUserProperties({
+            age: '28',
+            city: 'Seoul', 
+            gender: 'male',
+            country: 'KR',
+            occupation: 'developer',
+            interests: ['technology', 'gaming', 'travel']
+        });
+
+        function showResult(eventName, params, success = true) {
+            const result = document.getElementById('result');
+            const timestamp = new Date().toLocaleString();
+            result.textContent = `[${timestamp}] ${eventName} 이벤트 ${success ? '전송됨' : '실패'}\n\n파라미터:\n${JSON.stringify(params, null, 2)}`;
+        }
+
+        // 구매 이벤트
+        function trackPurchase() {
+            const params = {
+                transaction_id: `tx_${Date.now()}`,
+                value: 99000,
+                currency: 'KRW',
+                payment_method: 'card',
+                items: 2,
+                category: 'electronics',
+                brand: 'Samsung'
+            };
+            
+            try {
+                AdStage.events.track('purchase', params);
+                showResult('purchase', params);
+            } catch (error) {
+                showResult('purchase', params, false);
+                console.error('Purchase event failed:', error);
+            }
+        }
+
+        // 회원가입 이벤트
+        function trackSignup() {
+            const params = {
+                user_id: `user_${Date.now()}`,
+                signup_method: 'email',
+                email_verified: true,
+                time_to_complete: 120,
+                form_version: 'v2',
+                utm_source: 'google_ads',
+                utm_medium: 'cpc'
+            };
+            
+            try {
+                AdStage.events.track('signup_complete', params);
+                showResult('signup_complete', params);
+            } catch (error) {
+                showResult('signup_complete', params, false);
+                console.error('Signup event failed:', error);
+            }
+        }
+
+        // 페이지뷰 이벤트
+        function trackPageView() {
+            const params = {
+                page: window.location.pathname,
+                title: document.title,
+                referrer: document.referrer || 'direct',
+                utm_source: 'organic',
+                user_engagement: Math.floor(Math.random() * 300) + 30
+            };
+            
+            try {
+                AdStage.events.pageView(params);
+                showResult('page_view', params);
+            } catch (error) {
+                showResult('page_view', params, false);
+                console.error('PageView event failed:', error);
+            }
+        }
+
+        // 페이지 로드 시 자동 페이지뷰 추적
+        window.addEventListener('load', () => {
+            setTimeout(() => {
+                trackPageView();
+            }, 1000);
+        });
+    </script>
+</body>
+</html>

package/src/example/events/nextjs/README.md

@@ -0,0 +1,54 @@
+# AdStage SDK - Next.js 이벤트 추적 예시
+
+## 설치 및 실행
+
+```bash
+cd /Users/gunny/Documents/workspace/adstage/sdk/src/example/events/nextjs
+npm install  # @adstage/web-sdk@^2.6.1 설치됨
+npm run dev
+```
+
+서버: http://localhost:3000
+
+## 기능
+
+- 장바구니 추가 이벤트
+- 앱 설치 이벤트  
+- 검색 이벤트
+- 자동 페이지뷰 추적
+
+## 이벤트 파라미터 예시
+
+### 장바구니 추가 (add_to_cart)
+```javascript
+{
+  item_id: "prod_1234",
+  quantity: 2,
+  cart_value: 125000,
+  category: "home",
+  brand: "IKEA",
+  source: "product_page"
+}
+```
+
+### 앱 설치 (first_open)
+```javascript
+{
+  install_source: "google_play",
+  campaign: "summer_2024", 
+  days_since_click: 3,
+  organic: false,
+  referrer: "google_ads"
+}
+```
+
+### 검색 (search)
+```javascript
+{
+  search_term: "iPhone",
+  results_count: 42,
+  category: "electronics",
+  filters_applied: true,
+  sort_by: "price"
+}
+```

package/src/example/events/nextjs/next.config.js

@@ -0,0 +1,8 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    appDir: false
+  }
+}
+
+module.exports = nextConfig

package/src/example/events/nextjs/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "adstage-events-nextjs-example",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@adstage/web-sdk": "^2.6.1",
+    "next": "14.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  }
+}

package/src/example/events/nextjs/pages/_app.js

@@ -0,0 +1,15 @@
+import { AdStageProvider } from '@adstage/web-sdk';
+
+export default function App({ Component, pageProps }) {
+  return (
+    <AdStageProvider
+      config={{
+        apiKey: '7dfddcfda637fbb73225bac3731688b80b90675942fe9f2057a88e2379aba2a4',
+        debug: true,
+        appVersion: '3.0.1'
+      }}
+    >
+      <Component {...pageProps} />
+    </AdStageProvider>
+  );
+}