@action-x/ad-sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,678 +1,250 @@
 # @action-x/ad-sdk
 
-零框架依赖的广告 SDK，适用于任何 JavaScript / TypeScript 项目。
-支持原生 JS、Vue、Angular、Svelte、React 等所有框架。
+An ad SDK for AI conversation experiences, with zero framework dependencies. Works with Vanilla JS, Vue, React, Angular, Svelte, and more.
 
 ---
 
-## 目录
-
-- [特性](#特性)
-- [安装](#安装)
-- [快速上手](#快速上手)
-- [核心概念](#核心概念)
-- [API 参考](#api-参考)
-  - [AdManager](#admanager)
-  - [fetchAds / adaptAdToKoahAd](#fetchads--adaptadtokoahad)
-  - [HTMLRenderer](#htmlrenderer)
-  - [DOMRenderer](#domrenderer)
-  - [Analytics](#analytics)
-  - [ViewabilityTracker](#viewabilitytracker)
-  - [ClientInfo](#clientinfo)
-  - [EventEmitter](#eventemitter)
-- [类型定义](#类型定义)
-- [CSS 样式](#css-样式)
-- [广告格式说明](#广告格式说明)
-- [高级用法](#高级用法)
-- [依赖 API 端点](#依赖-api-端点)
-
----
-
-## 特性
-
-- **零运行时依赖** — 无 React、无 swr、无任何第三方运行时库
-- **框架无关** — 兼容原生 JS、Vue、React、Angular、Svelte 等所有框架
-- **OpenRTB 兼容** — 自动采集设备信息，符合 OpenRTB 2.5/2.6 规范
-- **完整追踪** — IAB/MRC 标准可视性追踪 + 曝光/点击事件上报，自动重试
-- **TypeScript 优先** — 完整类型声明，开箱即用，无需额外 `@types`
-- **多格式输出** — ESM / CommonJS / UMD，适配所有构建工具和 CDN
-
----
-
-## 安装
+## Installation
 
 ```bash
 npm install @action-x/ad-sdk
-# 或
+# or
 yarn add @action-x/ad-sdk
-# 或
+# or
 pnpm add @action-x/ad-sdk
 ```
 
-**引入样式（必须）：**
+**Import styles (required):**
 
 ```js
-// 在你的入口文件或组件中引入
 import '@action-x/ad-sdk/dist/style.css';
 ```
 
-或在 HTML 中：
-
-```html
-<link rel="stylesheet" href="node_modules/@action-x/ad-sdk/dist/style.css" />
-```
-
 ---
 
-## 快速上手
+## AdCard Component
 
-### 方式一：AdManager（推荐）
+Below are AdCard wrapper examples for different frameworks. The component takes `query` and `response` from the AI conversation, then automatically requests and renders an ad card after the response is complete.
 
-适合需要统一管理多个广告位、自动处理 Analytics 的场景。
+### Vue 3
+
+```vue
+<!-- AdCard.vue -->
+<template>
+  <div ref="adEl" />
+</template>
 
-```typescript
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue';
 import { AdManager } from '@action-x/ad-sdk';
 import '@action-x/ad-sdk/dist/style.css';
 
-const manager = new AdManager({
-  apiBaseUrl: 'https://your-api.example.com/api/v1',
-  apiKey: 'ak_your_api_key',
-  slots: [
-    {
-      slotId: 'banner-top',
-      slotName: '顶部横幅',
-      format: 'action_card',
-      variant: 'horizontal',
-      size: { width: 400, height: 120, aspectRatio: '3.3:1' },
-      count: 1,
-      placement: { position: 'above_fold', context: 'Chat response top' },
-    },
-    {
-      slotId: 'suffix-ad',
-      slotName: '底部追加广告',
-      format: 'suffix',
-      size: { width: 600, height: 60 },
-      count: 1,
-      placement: { position: 'below_fold', context: 'After AI response' },
-    },
-  ],
-});
-
-// 监听事件
-manager.on('adsUpdated', (slots) => console.log('广告更新:', Object.keys(slots)));
-manager.on('adsError', (err) => console.error('广告请求失败:', err.message));
-
-// 请求广告（在 AI 回复完成后调用）
-await manager.requestAds({
-  conversationContext: {
-    query: '推荐一款蓝牙耳机',
-    response: '以下是几款热门蓝牙耳机推荐...',
-  },
-  userContext: { sessionId: 'session-abc-123' },
-});
+const props = defineProps(['query', 'response']);
+const adEl = ref(null);
+let manager;
 
-// 渲染到 DOM
-manager.render('banner-top', document.getElementById('ad-banner'));
-manager.render('suffix-ad', document.getElementById('ad-suffix'));
-```
-
----
-
-### 方式二：fetchAds + DOMRenderer（更灵活）
-
-适合需要自行控制渲染时机的场景。
-
-```typescript
-import { fetchAds, DOMRenderer } from '@action-x/ad-sdk';
-import '@action-x/ad-sdk/dist/style.css';
-
-const result = await fetchAds(
-  {
-    conversationContext: { query: '推荐一款笔记本电脑' },
-    slots: [{
-      slotId: 'card-1',
-      slotName: '产品推荐卡片',
-      format: 'action_card',
-      size: { width: 280, height: 100 },
-      placement: { position: 'inline', context: 'product recommendation' },
-    }],
-  },
-  { apiBaseUrl: 'https://your-api.example.com/api/v1', apiKey: 'ak_xxx' }
-);
-
-result.slots.forEach((slot) => {
-  if (slot.status !== 'filled') return;
-  slot.ads.forEach((ad, index) => {
-    const container = document.createElement('div');
-    document.getElementById('ad-area').appendChild(container);
-    DOMRenderer.renderActionCard(ad, container, {
-      analytics: {
-        requestId: result.requestId,
-        slotId: slot.slotId,
-        position: index,
-        totalAds: slot.ads.length,
-      },
-      onClick: (ad) => console.log('点击:', ad.original.id),
-    });
+onMounted(async () => {
+  manager = new AdManager({
+    apiBaseUrl: 'https://your-api.example.com/api/v1',
+    apiKey: 'ak_your_api_key',
   });
-});
-```
-
----
 
-### 方式三：HTMLRenderer（纯字符串，适合 SSR）
+  await manager.requestAds({ query: props.query, response: props.response });
 
-```typescript
-import { HTMLRenderer } from '@action-x/ad-sdk';
+  manager.render(adEl.value);
+});
 
-const html = HTMLRenderer.renderActionCard(ad, { variant: 'horizontal' });
-document.getElementById('ad-container').innerHTML = html;
+onUnmounted(() => manager?.destroy());
+</script>
 ```
 
----
-
-## 核心概念
+### React
 
-### 广告请求流程
+```tsx
+// components/AdCard.tsx
+import { useEffect, useRef } from 'react';
+import { AdManager } from '@action-x/ad-sdk';
+import '@action-x/ad-sdk/dist/style.css';
 
-```
-用户发起对话
-    ↓
-调用 requestAds() / fetchAds()
-    ↓
-SDK 自动采集 ClientInfo（设备、系统、地理位置）
-    ↓
-POST /api/v1/ads/request（conversationContext + slots + clientInfo）
-    ↓
-后端返回 AdResponseBatch（requestId + 各广告位广告列表）
-    ↓
-调用 render() / DOMRenderer.renderXxx()
-    ↓
-DOM 绑定点击事件 → 点击追踪（异步）+ 打开目标 URL
-IntersectionObserver → 50% 可见 + 1s 延迟 → 曝光追踪
-```
+interface Props {
+  query: string;
+  response: string;
+}
 
-### Analytics 追踪机制
+export function AdCard({ query, response }: Props) {
+  const containerRef = useRef<HTMLDivElement>(null);
 
-| 事件 | 触发时机 | 端点 |
-|------|---------|------|
-| 曝光（impression）| 50% 可见 + 持续 1000ms | `POST /api/v1/ads/impression` |
-| 点击（click）| 用户点击 CTA 按钮 | `POST /api/v1/ads/click` |
-| 可视性（viewability）| 全程监测，批量上报 | `POST /api/v1/ads/viewability/batch` |
+  useEffect(() => {
+    const manager = new AdManager({
+      apiBaseUrl: 'https://your-api.example.com/api/v1',
+      apiKey: 'ak_your_api_key',
+    });
 
-### API Key 传递
+    manager
+      .requestAds({ query, response })
+      .then(() => {
+        if (containerRef.current) {
+          manager.render(containerRef.current);
+        }
+      });
 
-```ts
-// 方式 1：构造函数传入（推荐）
-new AdManager({ apiKey: 'ak_xxx', ... })
-fetchAds(params, { apiKey: 'ak_xxx' })
+    return () => manager.destroy();
+  }, [query, response]);
 
-// 方式 2：全局变量（适合动态配置场景）
-window.__AD_CONFIG__ = { apiKey: 'ak_xxx', apiBaseUrl: '...' };
+  return <div ref={containerRef} />;
+}
 ```
 
----
-
-## API 参考
-
-### AdManager
-
-主控类，管理广告请求、缓存、渲染和事件。
-
-#### 构造函数
+### Vanilla JavaScript
 
-```typescript
-new AdManager(config: AdManagerConfig)
-
-interface AdManagerConfig {
-  apiBaseUrl: string;       // 必填：API 基础地址
-  apiKey?: string;          // 推荐：API 认证密钥
-  slots: AdSlotRequest[];   // 必填：广告位配置列表
-  enabled?: boolean;        // 是否启用，默认 true
-  debug?: boolean;          // 调试日志，默认 false
-}
-```
+```js
+import { AdManager } from '@action-x/ad-sdk';
+import '@action-x/ad-sdk/dist/style.css';
 
-#### `requestAds(context): Promise<AdResponseBatch>`
+const manager = new AdManager({
+  apiBaseUrl: 'https://your-api.example.com/api/v1',
+  apiKey: 'ak_your_api_key',
+});
 
-```typescript
+// Request and render ads after the AI response is complete
 await manager.requestAds({
-  conversationContext: {
-    query: string;                          // 必填：用户查询
-    response?: string;                      // AI 回复（post-response 阶段）
-    intent?: IntentResult;
-    conversationHistory?: ConversationMessage[];
-  },
-  userContext?: {
-    sessionId: string;                      // 必填
-    userId?: string;
-    demographics?: { country?: string; language?: string };
-    profile?: UserProfile;
-  },
+  query: 'Recommend a Bluetooth headset',
+  response: 'Here are several popular Bluetooth headset options...',
 });
-```
 
-#### `render(slotId, container, options?): HTMLElement | null`
-
-```typescript
-manager.render(
-  slotId: string,
-  container: HTMLElement,
-  options?: {
-    adIndex?: number;             // 渲染第几条广告，默认 0
-    variant?: string;             // 'horizontal' | 'block' | 'card' 等
-    onClick?: (ad) => void;
-    onImpression?: (ad) => void;
-  }
-)
+manager.render(document.getElementById('ad-card'));
 ```
 
-#### 事件
-
-```typescript
-manager.on('adsUpdated',   (slots: Record<string, AdSlotResponse>) => void);
-manager.on('adsLoading',   () => void);
-manager.on('adsError',     (error: Error) => void);
-manager.on('adClicked',    (adId: string, slotId: string) => void);
-manager.on('adImpression', (adId: string, slotId: string) => void);
-```
+### CDN (No Build Tool)
 
-#### 其他方法
-
-| 方法 | 说明 |
-|------|------|
-| `getSlots(slotId?)` | 获取广告位数据 |
-| `hasAds(slotId)` | 广告位是否有广告 |
-| `getAds(slotId)` | 获取广告数组 |
-| `getLoadingStatus()` | 是否请求中 |
-| `setEnabled(enabled)` | 启用/禁用广告 |
-| `updateConfig(config)` | 动态更新配置 |
-| `clearSlots()` | 清空广告数据 |
-| `getCurrentRequestId()` | 获取最近 requestId |
-| `getAdAnalytics(adId)` | 获取广告 Analytics 信息 |
-| `trackAdClick(adId, url, adData?)` | 手动触发点击追踪 |
-| `trackAdImpressionAPI(adId, adData?)` | 手动触发曝光追踪 |
-| `destroy()` | 销毁实例，清理监听器 |
-
----
+```html
+<link rel="stylesheet" href="https://unpkg.com/@action-x/ad-sdk/dist/style.css" />
+<script src="https://unpkg.com/@action-x/ad-sdk/dist/index.umd.js"></script>
 
-### fetchAds / adaptAdToKoahAd
+<div id="ad-card"></div>
 
-```typescript
-import { fetchAds, adaptAdToKoahAd } from '@action-x/ad-sdk';
+<script>
+  const { AdManager } = ActionXAdSDK;
 
-// 请求广告（自动注入 ClientInfo）
-const result: AdResponseBatch = await fetchAds(
-  {
-    conversationContext: { query: '...', response?: '...' },
-    userContext?: { sessionId: '...' },
-    slots: AdSlotRequest[],
-  },
-  { apiBaseUrl?: string, apiKey?: string }
-);
+  const manager = new AdManager({
+    apiBaseUrl: 'https://your-api.example.com/api/v1',
+    apiKey: 'ak_your_api_key',
+  });
 
-// 转换 AdaptedAdContent → KoahAd
-const koahAd: KoahAd = adaptAdToKoahAd(adaptedAdContent);
+  manager
+    .requestAds({ query: 'User question', response: 'AI response' })
+    .then(() => {
+      manager.render(document.getElementById('ad-card'));
+    });
+</script>
 ```
 
 ---
 
-### HTMLRenderer
-
-生成广告 HTML 字符串，适合 SSR 或自行控制 DOM。
-
-```typescript
-import { HTMLRenderer } from '@action-x/ad-sdk';
-
-// Action Card
-HTMLRenderer.renderActionCard(ad, { variant?: 'horizontal' | 'vertical' | 'compact', includeWrapper?: boolean })
+## Usage Example
 
-// Suffix Ad
-HTMLRenderer.renderSuffixAd(ad)
+### Render an Ad Card After AI Response Completes
 
-// Sponsored Source
-HTMLRenderer.renderSponsoredSource(ad)
+Using React as an example, render AdCard after streaming output finishes:
 
-// Lead Gen
-HTMLRenderer.renderLeadGenAd(ad)
+```tsx
+import { useState } from 'react';
+import { AdCard } from './components/AdCard';
 
-// 批量渲染
-HTMLRenderer.renderAds(ads, renderFn?)
-```
-
----
-
-### DOMRenderer
-
-创建真实 DOM 并绑定事件追踪，不依赖 AdManager。
-
-```typescript
-import { DOMRenderer } from '@action-x/ad-sdk';
+export function ChatMessage() {
+  const [query, setQuery] = useState('');
+  const [response, setResponse] = useState('');
+  const [isStreaming, setIsStreaming] = useState(false);
 
-// Action Card（click 绑定 .ax-ad-cta）
-DOMRenderer.renderActionCard(ad, container, {
-  variant?: 'horizontal' | 'vertical' | 'compact',
-  analytics?: AdAnalyticsInfo,
-  onClick?: (ad) => void,
-  onImpression?: (ad) => void,
-})
+  async function handleSend(userQuery: string) {
+    setQuery(userQuery);
+    setIsStreaming(true);
+    setResponse('');
 
-// Suffix Ad（click 绑定 .ax-ad-suffix-link）
-DOMRenderer.renderSuffixAd(ad, container, {
-  variant?: 'block' | 'inline' | 'minimal',  // 默认 'block'
-  analytics?, onClick?, onImpression?,
-})
+    // Receive AI response as a stream
+    const stream = await fetchAIResponse(userQuery);
+    let fullResponse = '';
+    for await (const chunk of stream) {
+      fullResponse += chunk;
+      setResponse(fullResponse);
+    }
 
-// Sponsored Source（click 绑定 .ax-ad-source-link）
-DOMRenderer.renderSponsoredSource(ad, container, {
-  variant?: 'card' | 'list-item' | 'minimal',  // 默认 'card'
-  analytics?, onClick?, onImpression?,
-})
+    setIsStreaming(false);
+    // After response completes, AdCard will request and render automatically
+  }
 
-// Lead Gen（click 绑定 .ax-ad-leadgen-cta）
-DOMRenderer.renderLeadGenAd(ad, container, {
-  analytics?, onClick?, onImpression?,
-})
+  return (
+    <div>
+      <div className="response">{response}</div>
 
-// 批量渲染
-DOMRenderer.renderAds(ads, container, renderFn?, options?)
+      {/* Show ad card after response streaming ends */}
+      {!isStreaming && response && (
+        <AdCard query={query} response={response} />
+      )}
+    </div>
+  );
+}
 ```
 
-**点击流程**：异步发送 Analytics click 事件（不阻塞跳转）→ `window.open(clickUrl, '_blank')`
-
-**曝光流程**：IntersectionObserver 监听 → 50% 可见 + 1000ms → Analytics impression 事件
-
 ---
 
-### Analytics
-
-```typescript
-import {
-  trackAdImpression, trackAdClick,
-  getSessionId, generateViewToken,
-  trackImpressionsBatch, trackClicksBatch,
-  SessionManager, AnalyticsSender,
-  createAnalytics, createSession,
-} from '@action-x/ad-sdk';
-
-// 快捷追踪
-await trackAdImpression({
-  requestId, adId, position, totalAds, sessionId: getSessionId(),
-  slotId?, adTitle?, format?,
-});
-
-await trackAdClick({
-  requestId, adId, sessionId: getSessionId(), destinationUrl,
-  slotId?, adTitle?, format?,
-});
-
-// View Token
-const token = generateViewToken(adId, sessionId);
+## Configuration
 
-// 批量
-await trackImpressionsBatch([event1, event2]);
-await trackClicksBatch([event1, event2]);
+### `new AdManager(config)`
 
-// 自定义实例
-const analytics = createAnalytics({ baseUrl: '...', timeout: 5000, debug: true });
-const session   = createSession({ storage: 'memory' });
-```
-
-#### SessionManager
+| Parameter | Type | Required | Description |
+|------|------|------|------|
+| `apiBaseUrl` | `string` | Yes | API base URL, e.g. `https://your-api.example.com/api/v1` |
+| `apiKey` | `string` | Yes | API authentication key |
+| `cardOption` | `CardOption` | No | Card options with sensible defaults |
 
-```typescript
-new SessionManager({ sessionKey?: string, storage?: 'sessionStorage' | 'memory' })
-// .getSessionId()        获取或创建 session ID
-// .regenerateSessionId() 强制生成新 ID
-// .clearSessionId()      清除 ID
-```
-
-#### AnalyticsSender
-
-```typescript
-new AnalyticsSender({
-  baseUrl?: string,       // 默认 '/api/v1/ads'
-  timeout?: number,       // 默认 10000ms
-  retryAttempts?: number, // 默认 2
-  retryDelay?: number,    // 默认 1000ms（指数退避）
-  debug?: boolean,
-})
-```
-
----
+### Card Options `cardOption`
 
-### ViewabilityTracker
+| Parameter | Type | Default | Description |
+|------|------|--------|------|
+| `variant` | `'horizontal' \| 'vertical' \| 'compact'` | `'horizontal'` | Layout style |
+| `count` | `number` | `1` | Number of ads to request |
 
-IAB/MRC 标准可视性追踪（>50% 可见 + >1 秒 = 达标）。
+**Customization example:**
 
-```typescript
-import { getViewabilityTracker } from '@action-x/ad-sdk';
-
-// 推荐：使用单例，自动注册 beforeunload
-const tracker = getViewabilityTracker(
-  {
-    minVisiblePercentage?: 50,    // 默认 50
-    minViewableDuration?: 1000,   // 默认 1000ms
-    maxTrackingDuration?: 60000,  // 默认 60000ms
-    batchConfig?: { maxBatchSize?: 5, maxBatchWaitMs?: 10000 },
-    debug?: false,
+```js
+new AdManager({
+  apiBaseUrl: '...',
+  apiKey: '...',
+  cardOption: {
+    variant: 'vertical',
+    count: 2,
   },
-  baseUrl?: string  // 默认 '/api/v1'
-);
-
-tracker.startTracking(adId, element, sessionId, requestId?, viewToken?);
-tracker.getMetrics(adId);   // ViewabilityMetrics
-tracker.stopTracking(adId);
-tracker.stopAll();
-```
-
----
-
-### ClientInfo
-
-零配置，自动采集 OpenRTB 2.5/2.6 规范的客户端信息。
-
-```typescript
-import {
-  getClientInfo, getDeviceInfo, getUserInfo,
-  getAppInfo, getGeoInfo, getUserId,
-  clearClientInfoCache, getClientInfoJSON, getClientInfoSummary,
-} from '@action-x/ad-sdk';
-
-const info = getClientInfo();
-// info.device.os        → 'macOS'
-// info.device.model     → 'iPhone14,2'
-// info.user.id          → 'uuid-xxx'（localStorage 持久化）
-// info.geo.country      → 'CN'（从时区/语言推断）
-// info.app.bundle       → 'example.com'
-
-// 覆盖默认值
-const info = getClientInfo({
-  device: { ifa: 'your-idfa', lmt: 0 },
-  app:    { bundle: 'com.your.app', ver: '2.1.0' },
-  geo:    { lat: 39.9, lon: 116.4 },
 });
 ```
 
----
+### `requestAds(context)`
 
-### EventEmitter
+| Parameter | Type | Required | Description |
+|------|------|------|------|
+| `query` | `string` | Yes | User question |
+| `response` | `string` | Yes | AI response text |
 
-```typescript
-import { EventEmitter } from '@action-x/ad-sdk';
+### `render(container, options?)`
 
-const emitter = new EventEmitter();
-emitter.on('event', handler);
-emitter.emit('event', data);
-emitter.off('event', handler);
-emitter.removeAllListeners('event');
-emitter.listenerCount('event');
-```
-
----
-
-## 类型定义
-
-```typescript
-// 广告格式
-type AdFormat = 'action_card' | 'suffix' | 'followup' | 'source' | 'static' | 'lead_gen' | 'entity_link';
-
-// 广告位请求
-interface AdSlotRequest {
-  slotId: string;
-  slotName: string;
-  format: AdFormat;
-  variant?: string;
-  size: { width: number; height: number; aspectRatio?: string };
-  count?: number;
-  preferences?: { maxTitleLength?: number; requireImage?: boolean; showPrice?: boolean };
-  placement: { position: 'above_fold' | 'below_fold' | 'sidebar' | 'inline'; context: string };
-}
-
-// 广告响应批次
-interface AdResponseBatch {
-  requestId: string;
-  timestamp: number;
-  intent: IntentResult;
-  slots: AdSlotResponse[];
-}
-
-// 广告位响应
-interface AdSlotResponse {
-  slotId: string;
-  status: 'filled' | 'no_fill' | 'error';
-  ads: AdaptedAdContent[];
-}
-
-// 适配后的广告内容
-interface AdaptedAdContent {
-  original: { id: string; type: AdFormat; score: number };
-  adapted: { title: string; body: string; ctaText: string; image?; price?; rating?; brand? };
-  tracking: { impressionUrl: string; clickUrl: string; viewToken: string };
-}
-
-// Analytics 信息（传给 DOMRenderer）
-interface AdAnalyticsInfo {
-  requestId: string;
-  slotId: string;
-  position: number;
-  totalAds: number;
-}
-```
-
-完整类型定义参见 `dist/index.d.ts`。
-
----
-
-## CSS 样式
-
-所有样式使用 `ax-ad-*` 命名空间，不污染全局。
-
-| CSS 类 | 用途 |
-|-------|------|
-| `.ax-ad-card` | Action Card 基础容器 |
-| `.ax-ad-card-horizontal/vertical/compact` | 布局变体 |
-| `.ax-ad-cta` | CTA 按钮（蓝色 #3b82f6） |
-| `.ax-ad-suffix` | Suffix 广告容器 |
-| `.ax-ad-suffix-link` | Suffix 链接 |
-| `.ax-ad-variant-block/inline/minimal` | Suffix 变体 |
-| `.ax-ad-source-link` | Source 广告链接 |
-| `.ax-ad-variant-card/list-item/minimal` | Source 变体 |
-| `.ax-ad-leadgen-cta` | LeadGen CTA |
-| `.ax-ad-sponsored-badge` | 赞助商标识 |
-| `.ax-ads-container` | 多广告外层容器 |
-
-**自定义样式：**
-
-```css
-/* 覆盖 CTA 颜色 */
-.ax-ad-cta { background: #7c3aed; }
-.ax-ad-cta:hover { background: #6d28d9; }
-
-/* 覆盖卡片圆角 */
-.ax-ad-card { border-radius: 12px; }
-```
-
----
-
-## 广告格式说明
-
-| 格式 | 说明 | 典型位置 |
-|------|------|---------|
-| `action_card` | 产品卡片，含图片/价格/评分/CTA | AI 回复下方 |
-| `suffix` | 低干扰追加文本，append 在回复末尾 | AI 回复末尾 |
-| `source` | 混入引用来源列表的赞助链接 | 引用/来源区域 |
-| `lead_gen` | 线索收集，引导留资 / 注册 | 侧边栏 / 对话末尾 |
-| `followup` | 混入相关问题建议 | 问题推荐区域 |
-| `static` | 静态 Banner 展示 | 固定位置 |
+| Parameter | Type | Description |
+|------|------|------|
+| `container` | `HTMLElement` | Mount container |
+| `options.onClick` | `(ad) => void` | Click callback |
+| `options.onImpression` | `(ad) => void` | Impression callback |
 
 ---
 
-## 高级用法
-
-### Vue 3
-
-```typescript
-// composables/useAds.ts
-import { ref, onUnmounted } from 'vue';
-import { AdManager } from '@action-x/ad-sdk';
-
-export function useAds(slots) {
-  const isLoading = ref(false);
-  const manager = new AdManager({
-    apiBaseUrl: import.meta.env.VITE_AD_API_URL,
-    apiKey: import.meta.env.VITE_AD_API_KEY,
-    slots,
-  });
-  manager.on('adsLoading', () => (isLoading.value = true));
-  manager.on('adsUpdated', () => (isLoading.value = false));
-  onUnmounted(() => manager.destroy());
-  return { manager, isLoading };
-}
-```
-
-### React
-
-```typescript
-// hooks/useAdManager.ts
-import { useEffect, useRef } from 'react';
-import { AdManager } from '@action-x/ad-sdk';
+## Event Listeners
 
-export function useAdManager(slots) {
-  const ref = useRef(new AdManager({
-    apiBaseUrl: process.env.NEXT_PUBLIC_AD_API_URL,
-    apiKey: process.env.NEXT_PUBLIC_AD_API_KEY,
-    slots,
-  }));
-  useEffect(() => () => ref.current.destroy(), []);
-  return ref.current;
-}
-```
-
-### CDN / 无构建工具
-
-```html
-<link rel="stylesheet" href="https://unpkg.com/@action-x/ad-sdk/dist/style.css" />
-<script src="https://unpkg.com/@action-x/ad-sdk/dist/index.umd.js"></script>
-<script>
-  const { AdManager } = ActionXAdSDK;
-  const manager = new AdManager({ apiBaseUrl: '...', apiKey: '...', slots: [...] });
-</script>
+```js
+manager.on('adsUpdated',   (slots) => { /* ad data ready */ });
+manager.on('adsLoading',   ()      => { /* requesting */ });
+manager.on('adsError',     (err)   => { /* request failed */ });
+manager.on('adClicked',    (adId, slotId) => { });
+manager.on('adImpression', (adId, slotId) => { });
 ```
 
 ---
 
-## 依赖 API 端点
-
-| 端点 | 方法 | 用途 |
-|------|------|------|
-| `/api/v1/ads/request` | POST | 请求广告批次 |
-| `/api/v1/ads/impression` | POST | 曝光事件上报 |
-| `/api/v1/ads/click` | POST | 点击事件上报 |
-| `/api/v1/ads/viewability/batch` | POST | 可视性事件批量上报 |
-
-所有请求若配置了 `apiKey`，均自动携带 `X-API-Key` 请求头。
-
----
-
-**版本**：`0.1.0` | **许可证**：MIT
+**Version**: `0.1.0` | **License**: MIT