@adstage/web-sdk 3.0.1 → 3.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.ko.md +508 -0
  2. package/README.md +163 -527
  3. package/dist/index.cjs.js +1 -4714
  4. package/dist/index.d.ts +42 -35
  5. package/dist/index.esm.js +1 -4703
  6. package/dist/index.standalone.js +2 -4767
  7. package/dist/index.umd.js +3 -4785
  8. package/package.json +5 -2
  9. package/src/events/global-events.ts +33 -15
  10. package/src/index.ts +2 -2
  11. package/src/modules/events/events-module.ts +3 -46
  12. package/src/types/events.ts +25 -0
package/README.ko.md ADDED
@@ -0,0 +1,508 @@
1
+ # adstage Web SDK
2
+
3
+ > AdStage 마케팅 플랫폼 웹 SDK
4
+
5
+ [![npm version](https://img.shields.io/npm/v/%40adstage/web-sdk.svg?label=npm)](https://www.npmjs.com/package/@adstage/web-sdk)
6
+ [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8
+
9
+ 광고 표시와 이벤트 추적을 위한 JavaScript/TypeScript 라이브러리입니다.
10
+
11
+ ## ✨ 주요 기능
12
+
13
+ - **광고 표시**: 배너, 텍스트, 비디오 광고
14
+ - **이벤트 추적**: 클릭, 페이지뷰 등 이벤트 기록
15
+
16
+ ## 📦 설치
17
+
18
+ ```bash
19
+ # npm
20
+ npm install @adstage/web-sdk
21
+
22
+ # yarn
23
+ yarn add @adstage/web-sdk
24
+
25
+ # pnpm
26
+ pnpm add @adstage/web-sdk
27
+ ```
28
+
29
+ ## 🚀 빠른 시작
30
+
31
+ ```javascript
32
+ import { AdStage } from '@adstage/web-sdk';
33
+
34
+ // SDK 초기화
35
+ AdStage.init({
36
+ apiKey: 'your-api-key'
37
+ });
38
+
39
+ // 광고 표시
40
+ AdStage.ads.banner('banner-container');
41
+ AdStage.ads.text('text-container');
42
+ AdStage.ads.video('video-container');
43
+ ```
44
+
45
+ ## 📖 사용 예시
46
+
47
+ ### 1. 광고 표시
48
+
49
+ <details>
50
+ <summary><strong>JavaScript (HTML)</strong></summary>
51
+
52
+ ```html
53
+ <!DOCTYPE html>
54
+ <html>
55
+ <body>
56
+ <div id="banner-ad"></div>
57
+ <div id="text-ad"></div>
58
+ <div id="video-ad"></div>
59
+
60
+ <script src="https://unpkg.com/@adstage/web-sdk@3.0.1/dist/index.umd.js"></script>
61
+ <script>
62
+ // 초기화
63
+ AdStage.init({ apiKey: 'your-api-key' });
64
+
65
+ // 광고 표시
66
+ AdStage.ads.banner('banner-ad');
67
+ AdStage.ads.text('text-ad');
68
+ AdStage.ads.video('video-ad');
69
+ </script>
70
+ </body>
71
+ </html>
72
+ ```
73
+ </details>
74
+
75
+ <details>
76
+ <summary><strong>JavaScript (ES Module)</strong></summary>
77
+
78
+ ```javascript
79
+ import { AdStage } from 'https://unpkg.com/@adstage/web-sdk@3.0.1/dist/index.standalone.js';
80
+
81
+ AdStage.init({ apiKey: 'your-api-key' });
82
+ AdStage.ads.banner('banner-ad');
83
+ AdStage.ads.text('text-ad');
84
+ AdStage.ads.video('video-ad');
85
+ ```
86
+ </details>
87
+
88
+ <details>
89
+ <summary><strong>React (기본 방식)</strong></summary>
90
+
91
+ ```jsx
92
+ import React, { useEffect, useRef } from 'react';
93
+ import { AdStage } from '@adstage/web-sdk';
94
+
95
+ function AdBanner() {
96
+ const containerRef = useRef();
97
+
98
+ useEffect(() => {
99
+ AdStage.init({ apiKey: 'your-api-key' });
100
+ AdStage.ads.banner(containerRef.current.id);
101
+ }, []);
102
+
103
+ return <div ref={containerRef} id="banner-ad" />;
104
+ }
105
+ ```
106
+ </details>
107
+
108
+ <details>
109
+ <summary><strong>React (Provider 방식)</strong></summary>
110
+
111
+ ```jsx
112
+ import React, { useEffect, useRef } from 'react';
113
+ import { AdStageProvider, useAdStageInstance } from '@adstage/web-sdk';
114
+
115
+ // App.js - 최상위에서 Provider 설정
116
+ function App() {
117
+ return (
118
+ <AdStageProvider config={{ apiKey: 'your-api-key' }}>
119
+ <AdBanner />
120
+ </AdStageProvider>
121
+ );
122
+ }
123
+
124
+ // AdBanner.js - Provider를 통해 SDK 사용
125
+ function AdBanner() {
126
+ const containerRef = useRef();
127
+ const adstage = useAdStageInstance();
128
+
129
+ useEffect(() => {
130
+ if (adstage && containerRef.current) {
131
+ adstage.ads.banner(containerRef.current.id);
132
+ }
133
+ }, [adstage]);
134
+
135
+ return <div ref={containerRef} id="banner-ad" />;
136
+ }
137
+ ```
138
+ </details>
139
+
140
+ <details>
141
+ <summary><strong>Next.js (기본 방식)</strong></summary>
142
+
143
+ ```jsx
144
+ import { useEffect, useRef } from 'react';
145
+ import { AdStage } from '@adstage/web-sdk';
146
+
147
+ export default function HomePage() {
148
+ const bannerRef = useRef();
149
+
150
+ useEffect(() => {
151
+ if (typeof window !== 'undefined') {
152
+ AdStage.init({ apiKey: 'your-api-key' });
153
+ AdStage.ads.banner('banner-ad');
154
+ }
155
+ }, []);
156
+
157
+ return <div id="banner-ad" />;
158
+ }
159
+ ```
160
+ </details>
161
+
162
+ <details>
163
+ <summary><strong>Next.js (Provider 방식)</strong></summary>
164
+
165
+ ```jsx
166
+ // pages/_app.js - Provider를 최상위에 설정
167
+ import { AdStageProvider } from '@adstage/web-sdk';
168
+
169
+ function MyApp({ Component, pageProps }) {
170
+ return (
171
+ <AdStageProvider config={{ apiKey: 'your-api-key' }}>
172
+ <Component {...pageProps} />
173
+ </AdStageProvider>
174
+ );
175
+ }
176
+
177
+ export default MyApp;
178
+
179
+ // pages/index.js - Provider를 통해 SDK 사용
180
+ import React, { useEffect, useRef } from 'react';
181
+ import { useAdStageInstance } from '@adstage/web-sdk';
182
+
183
+ function HomePage() {
184
+ const containerRef = useRef();
185
+ const adstage = useAdStageInstance();
186
+
187
+ useEffect(() => {
188
+ if (adstage && containerRef.current) {
189
+ adstage.ads.banner(containerRef.current.id);
190
+ }
191
+ }, [adstage]);
192
+
193
+ return <div ref={containerRef} id="banner-ad" />;
194
+ }
195
+
196
+ export default HomePage;
197
+ ```
198
+ </details>
199
+
200
+ ### 2. 이벤트 추적
201
+
202
+ <details>
203
+ <summary><strong>JavaScript (HTML)</strong></summary>
204
+
205
+ ```javascript
206
+ // 클릭 이벤트
207
+ AdStage.events.track('button_click', {
208
+ button_id: 'cta',
209
+ page: '/home'
210
+ });
211
+
212
+ // 페이지뷰 이벤트
213
+ AdStage.events.track('page_view', {
214
+ page: '/products',
215
+ title: 'Products'
216
+ });
217
+ ```
218
+
219
+ </details>
220
+
221
+ <details>
222
+ <summary><strong>JavaScript (ES Module)</strong></summary>
223
+
224
+ ```javascript
225
+ import { AdStage } from 'https://unpkg.com/@adstage/web-sdk@3.0.1/dist/index.standalone.js';
226
+
227
+ // 초기화
228
+ AdStage.init({ apiKey: 'your-api-key' });
229
+
230
+ // 클릭 이벤트
231
+ AdStage.events.track('button_click', {
232
+ button_id: 'cta',
233
+ page: '/home'
234
+ });
235
+
236
+ // 페이지뷰 이벤트
237
+ AdStage.events.track('page_view', {
238
+ page: '/products',
239
+ title: 'Products'
240
+ });
241
+ ```
242
+
243
+ </details>
244
+
245
+ <details>
246
+ <summary><strong>React (기본 방식)</strong></summary>
247
+
248
+ ```jsx
249
+ import { AdStage } from '@adstage/web-sdk';
250
+
251
+ function Button() {
252
+ const handleClick = () => {
253
+ AdStage.events.track('button_click', {
254
+ button_id: 'purchase'
255
+ });
256
+ };
257
+
258
+ return <button onClick={handleClick}>구매하기</button>;
259
+ }
260
+ ```
261
+
262
+ </details>
263
+
264
+ <details>
265
+ <summary><strong>React (Provider 방식)</strong></summary>
266
+
267
+ ```jsx
268
+ import React from 'react';
269
+ import { AdStageProvider, useAdStageInstance } from '@adstage/web-sdk';
270
+
271
+ // App.js - Provider 설정
272
+ function App() {
273
+ return (
274
+ <AdStageProvider config={{ apiKey: 'your-api-key' }}>
275
+ <Button />
276
+ </AdStageProvider>
277
+ );
278
+ }
279
+
280
+ // Button.js - Provider를 통해 이벤트 추적
281
+ function Button() {
282
+ const adstage = useAdStageInstance();
283
+
284
+ const handleClick = () => {
285
+ if (adstage) {
286
+ adstage.events.track('button_click', {
287
+ button_id: 'purchase'
288
+ });
289
+ }
290
+ };
291
+
292
+ return <button onClick={handleClick}>구매하기</button>;
293
+ }
294
+ ```
295
+
296
+ </details>
297
+
298
+ <details>
299
+ <summary><strong>Next.js (기본 방식)</strong></summary>
300
+
301
+ ```jsx
302
+ import { AdStage } from '@adstage/web-sdk';
303
+
304
+ export default function HomePage() {
305
+ const handleClick = () => {
306
+ AdStage.events.track('button_click', {
307
+ button_id: 'cta',
308
+ page: '/home'
309
+ });
310
+ };
311
+
312
+ return <button onClick={handleClick}>클릭하기</button>;
313
+ }
314
+ ```
315
+
316
+ </details>
317
+
318
+ <details>
319
+ <summary><strong>Next.js (Provider 방식)</strong></summary>
320
+
321
+ ```jsx
322
+ // pages/_app.js - Provider 설정
323
+ import { AdStageProvider } from '@adstage/web-sdk';
324
+
325
+ export default function MyApp({ Component, pageProps }) {
326
+ return (
327
+ <AdStageProvider config={{ apiKey: 'your-api-key' }}>
328
+ <Component {...pageProps} />
329
+ </AdStageProvider>
330
+ );
331
+ }
332
+
333
+ // pages/index.js - Provider를 통해 이벤트 추적
334
+ import { useAdStageInstance } from '@adstage/web-sdk';
335
+
336
+ export default function HomePage() {
337
+ const adstage = useAdStageInstance();
338
+
339
+ const handleClick = () => {
340
+ if (adstage) {
341
+ adstage.events.track('button_click', {
342
+ button_id: 'cta',
343
+ page: '/home'
344
+ });
345
+ }
346
+ };
347
+
348
+ return <button onClick={handleClick}>클릭하기</button>;
349
+ }
350
+ ```
351
+
352
+ </details>
353
+
354
+ ## ⚙️ 설정
355
+
356
+ ### 기본 설정
357
+ ```javascript
358
+ AdStage.init({
359
+ apiKey: 'your-api-key', // 필수
360
+ debug: true, // 개발 모드
361
+ });
362
+ ```
363
+
364
+ ### 광고 옵션
365
+ ```javascript
366
+ // 배너 광고
367
+ AdStage.ads.banner('container-id', {
368
+ width: '100%',
369
+ height: 250
370
+ });
371
+
372
+ // 텍스트 광고
373
+ AdStage.ads.text('container-id', {
374
+ maxLines: 3
375
+ });
376
+
377
+ // 비디오 광고
378
+ AdStage.ads.video('container-id', {
379
+ width: 640,
380
+ height: 360,
381
+ autoplay: false
382
+ });
383
+ ```
384
+
385
+ ### 광고 옵션 표
386
+
387
+ #### 배너 광고
388
+
389
+ | 옵션 | 타입 | 기본값 | 설명 |
390
+ |------|------|--------|------|
391
+ | `width` | `string \| number` | `'100%'` | 광고 너비 (px 또는 %) |
392
+ | `height` | `number` | `250` | 광고 높이 (px) |
393
+ | `position` | `'top' \| 'bottom' \| 'center'` | `'center'` | 광고 위치 |
394
+ | `responsive` | `boolean` | `true` | 반응형 여부 |
395
+
396
+ #### 텍스트 광고
397
+
398
+ | 옵션 | 타입 | 기본값 | 설명 |
399
+ |------|------|--------|------|
400
+ | `maxLines` | `number` | `3` | 최대 텍스트 줄 수 |
401
+ | `fontSize` | `number` | `14` | 글자 크기 (px) |
402
+ | `textAlign` | `'left' \| 'center' \| 'right'` | `'left'` | 텍스트 정렬 |
403
+
404
+ #### 비디오 광고
405
+
406
+ | 옵션 | 타입 | 기본값 | 설명 |
407
+ |------|------|--------|------|
408
+ | `width` | `number` | `640` | 비디오 너비 (px) |
409
+ | `height` | `number` | `360` | 비디오 높이 (px) |
410
+ | `autoplay` | `boolean` | `false` | 자동 재생 여부 |
411
+ | `muted` | `boolean` | `true` | 음소거 여부 |
412
+ | `controls` | `boolean` | `true` | 컨트롤 표시 여부 |
413
+ | `loop` | `boolean` | `false` | 반복 재생 여부 |
414
+
415
+ ## 📚 API 레퍼런스
416
+
417
+ ### 🔧 공통 함수
418
+
419
+ SDK 초기화 및 상태 관리를 위한 핵심 함수들입니다.
420
+
421
+ | 함수 | 설명 | 매개변수 | 반환값 | 예시 |
422
+ |------|------|----------|--------|------|
423
+ | `init()` | SDK 초기화 (필수) | `{apiKey: string, debug?: boolean}` | `void` | `AdStage.init({ apiKey: 'key' })` |
424
+ | `isReady()` | 초기화 상태 확인 | - | `boolean` | `AdStage.isReady()` |
425
+ | `reset()` | SDK 리셋 (테스트용) | - | `void` | `AdStage.reset()` |
426
+
427
+ ### 📺 광고 모듈 (AdStage.ads)
428
+
429
+ 다양한 형태의 광고를 표시하기 위한 함수들입니다.
430
+
431
+ | 함수 | 설명 | 매개변수 | 반환값 | 예시 |
432
+ |------|------|----------|--------|------|
433
+ | `banner()` | 배너 광고 표시 | `containerId: string, options?: BannerOptions` | `Promise<void>` | `AdStage.ads.banner('container-id')` |
434
+ | `text()` | 텍스트 광고 표시 | `containerId: string, options?: TextOptions` | `Promise<void>` | `AdStage.ads.text('container-id')` |
435
+ | `video()` | 비디오 광고 표시 | `containerId: string, options?: VideoOptions` | `Promise<void>` | `AdStage.ads.video('container-id')` |
436
+
437
+ ### 📊 이벤트 모듈 (AdStage.events)
438
+
439
+ 사용자 행동 추적 및 분석을 위한 함수들입니다.
440
+
441
+ | 함수 | 설명 | 매개변수 | 반환값 | 예시 |
442
+ |------|------|----------|--------|------|
443
+ | `track()` | 이벤트 추적 | `eventName: string, properties?: object` | `Promise<void>` | `AdStage.events.track('click', { id: 'btn1' })` |
444
+ | `setUserId()` | 사용자 ID 설정 | `userId: string` | `void` | `AdStage.events.setUserId('user123')` |
445
+ | `getUserId()` | 사용자 ID 조회 | - | `string \| null` | `AdStage.events.getUserId()` |
446
+ | `setUserProperties()` | 사용자 속성 설정 | `properties: UserProperties` | `void` | `AdStage.events.setUserProperties({ gender: 'male' })` |
447
+ | `getUserProperties()` | 사용자 속성 조회 | - | `UserProperties \| null` | `AdStage.events.getUserProperties()` |
448
+
449
+ #### 📋 사용자 속성 (UserProperties)
450
+
451
+ `setUserProperties()`에서 지원하는 속성들입니다.
452
+
453
+ | 속성 | 타입 | 설명 | 예시 값 |
454
+ |------|------|------|--------|
455
+ | `gender` | `string` | 성별 | `'male'`, `'female'` |
456
+ | `country` | `string` | 국가 코드 (ISO 3166-1) | `'KR'`, `'US'`, `'JP'` |
457
+ | `city` | `string` | 도시명 | `'Seoul'`, `'New York'` |
458
+ | `age` | `string` | 연령대 | `'20-29'`, `'30-39', '20', 30, 40` |
459
+ | `language` | `string` | 언어 코드 (ISO 639-1) | `'ko'`, `'en'`, `'ja'` |
460
+
461
+ ### 전역 함수
462
+
463
+ 간편하게 사용할 수 있는 전역 함수들입니다. `AdStage.events.*` 대신 직접 import해서 사용할 수 있습니다.
464
+
465
+ ```javascript
466
+ import { track, setUserId, setUserProperties } from '@adstage/web-sdk';
467
+
468
+ // 이벤트 추적
469
+ track('purchase', { value: 99 });
470
+
471
+ // 사용자 설정
472
+ setUserId('user123');
473
+ setUserProperties({ gender: 'male', country: 'KR' });
474
+ ```
475
+
476
+ | 함수 | 설명 | 동일한 기능 |
477
+ |------|------|-----------|
478
+ | `track()` | 이벤트 추적 | `AdStage.events.track()` |
479
+ | `setUserId()` | 사용자 ID 설정 | `AdStage.events.setUserId()` |
480
+ | `getUserId()` | 사용자 ID 조회 | `AdStage.events.getUserId()` |
481
+ | `setUserProperties()` | 사용자 속성 설정 | `AdStage.events.setUserProperties()` |
482
+ | `getUserProperties()` | 사용자 속성 조회 | `AdStage.events.getUserProperties()` |
483
+
484
+ ### React 컴포넌트 및 훅
485
+
486
+ | 컴포넌트/훅 | 설명 | 반환값 | 사용 목적 |
487
+ |-------------|------|-------|----------|
488
+ | `AdStageProvider` | React Context Provider | - | SDK 초기화 및 Context 제공 |
489
+ | `useAdStageInstance` | SDK 인스턴스 직접 반환 | `AdStage \| null` | 간편한 SDK 사용 (권장) |
490
+ | `useAdStageContext` | Provider 상태 정보 반환 | `{isInitialized, config, error}` | 고급 상태 관리 |
491
+
492
+ #### React 훅 사용 가이드
493
+
494
+ - **`useAdStageInstance`** (권장): SDK의 메서드를 바로 사용하고 싶을 때
495
+ ```jsx
496
+ const adstage = useAdStageInstance();
497
+ adstage?.events.track('click', { button: 'cta' });
498
+ ```
499
+
500
+ - **`useAdStageContext`**: 초기화 상태나 에러를 체크하고 싶을 때
501
+ ```jsx
502
+ const { isInitialized, error } = useAdStageContext();
503
+ if (!isInitialized) return <div>Loading...</div>;
504
+ ```
505
+
506
+ ## 📄 라이선스
507
+
508
+ MIT License © 2025 stageUp