@adstage/web-sdk

v3.0.14

Published

a month ago

AdStage Web SDK - Production-ready marketing platform SDK with React Provider support for seamless integration

Downloads

939

0High
0Medium
0Low

nbase

adstage advertisement ads banner text video native interstitial sdk web typescript namespace marketing tracking deeplink analytics

adstage Web SDK

JavaScript/TypeScript SDK for AdStage marketing platform

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

# npm
npm install @adstage/web-sdk

# yarn
yarn add @adstage/web-sdk

# pnpm
pnpm add @adstage/web-sdk

🚀 Quick Start

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)

<!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)

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)

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)

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

AdStage.events.track('button_click', {
  button_id: 'cta',
  page: '/home'
});

AdStage.events.track('page_view', {
  page: '/products',
  title: 'Products'
});

Using Global Helpers

import { track, setUserId, setUserProperties } from '@adstage/web-sdk';

track('purchase', { value: 99 });
setUserId('user123');
setUserProperties({ country: 'KR', gender: 'male' });

⚙️ Configuration

Basic Initialization

AdStage.init({
  apiKey: 'your-api-key',
  debug: true
});

Ad Rendering (with options)

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

const adstage = useAdStageInstance();
adstage?.events.track('click', { button: 'cta' });