@adstage/web-sdk
Version:
AdStage Web SDK - Production-ready marketing platform SDK with React Provider support for seamless integration
263 lines (196 loc) • 9.16 kB
Markdown
# adstage Web SDK
> JavaScript/TypeScript SDK for AdStage marketing platform
[](https://www.npmjs.com/package/@adstage/web-sdk)
[](http://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
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
npm install @adstage/web-sdk
# yarn
yarn add @adstage/web-sdk
# pnpm
pnpm add @adstage/web-sdk
```
## 🚀 Quick Start
```javascript
import { AdStage } from '@adstage/web-sdk';
AdStage.init({
apiKey: 'your-api-key'
});
AdStage.ads.banner('banner-container');
AdStage.ads.text('text-container');
AdStage.ads.video('video-container');
```
## 📖 Usage Examples
### 1. Ad Rendering
#### Plain HTML (UMD)
```html
<!DOCTYPE html>
<html>
<body>
<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-ad');
AdStage.ads.text('text-ad');
AdStage.ads.video('video-ad');
</script>
</body>
</html>
```
#### ES Module (Standalone build)
```javascript
import { AdStage } from 'https://unpkg.com/@adstage/web-sdk/dist/index.standalone.js';
AdStage.init({ apiKey: 'your-api-key' });
AdStage.ads.banner('banner-ad');
AdStage.ads.text('text-ad');
AdStage.ads.video('video-ad');
```
#### React (Basic)
```jsx
import { useEffect, useRef } from 'react';
import { AdStage } from '@adstage/web-sdk';
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} />;
}
```
#### React (Provider + Hook)
```jsx
import { AdStageProvider, useAdStageInstance } from '@adstage/web-sdk';
import { useEffect, useRef } from 'react';
export function App() {
return (
<AdStageProvider config={{ apiKey: 'your-api-key' }}>
<Banner />
</AdStageProvider>
);
}
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} />;
}
```
### 2. Event Tracking
#### Plain JS
```javascript
AdStage.events.track('button_click', {
button_id: 'cta',
page: '/home'
});
AdStage.events.track('page_view', {
page: '/products',
title: 'Products'
});
```
#### Using Global Helpers
```javascript
import { track, setUserId, setUserProperties } from '@adstage/web-sdk';
track('purchase', { value: 99 });
setUserId('user123');
setUserProperties({ country: 'KR', gender: 'male' });
```
## ⚙️ Configuration
### Basic Initialization
```javascript
AdStage.init({
apiKey: 'your-api-key',
debug: true
});
```
### Ad Rendering (with options)
```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
#### Banner
| Option | Type | Default | Description |
| -------------- | ----------- | -------- | -------------------------- |
| `width` | `string | number` | `'100%'` |
| `height` | `number` | `250` | Height (px) |
| `position` | `'top' | 'bottom' | 'center'` |
| `responsive` | `boolean` | `true` | Enable responsive resizing |
#### Text
| Option | Type | Default | Description |
| ------------- | ---------- | -------- | ----------------- |
| `maxLines` | `number` | `3` | Max visible lines |
| `fontSize` | `number` | `14` | Font size (px) |
| `textAlign` | `'left' | 'center' | 'right'` |
#### Video
| 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 |
## 📚 API Reference
### Core (Common)
| 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()` |
### 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')` |
### Events Module (`AdStage.events`)
| 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
| 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
Firebase‑style named exports. Equivalent to `AdStage.events.*`.
| 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()` |
### React Components & Hooks
| Name | Type | Returns | Purpose |
| ---------------------- | --------- | ------------------------------------ | ----------------------- |
| `AdStageProvider` | Component | - | Provide SDK via context |
| `useAdStageInstance` | Hook | `AdStage | null` |
| `useAdStageContext` | Hook | `{ isInitialized, config, error }` | State / error handling |
#### Hook Usage
```jsx
const adstage = useAdStageInstance();
adstage?.events.track('click', { button: 'cta' });
```
## 📄 License
MIT License © 2025 stageUp