@action-x/ad-sdk 0.1.0

package/README.md

@@ -0,0 +1,678 @@
+# @action-x/ad-sdk
+
+零框架依赖的广告 SDK，适用于任何 JavaScript / TypeScript 项目。
+支持原生 JS、Vue、Angular、Svelte、React 等所有框架。
+
+---
+
+## 目录
+
+- [特性](#特性)
+- [安装](#安装)
+- [快速上手](#快速上手)
+- [核心概念](#核心概念)
+- [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
+
+---
+
+## 安装
+
+```bash
+npm install @action-x/ad-sdk
+# 或
+yarn add @action-x/ad-sdk
+# 或
+pnpm add @action-x/ad-sdk
+```
+
+**引入样式（必须）：**
+
+```js
+// 在你的入口文件或组件中引入
+import '@action-x/ad-sdk/dist/style.css';
+```
+
+或在 HTML 中：
+
+```html
+<link rel="stylesheet" href="node_modules/@action-x/ad-sdk/dist/style.css" />
+```
+
+---
+
+## 快速上手
+
+### 方式一：AdManager（推荐）
+
+适合需要统一管理多个广告位、自动处理 Analytics 的场景。
+
+```typescript
+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' },
+});
+
+// 渲染到 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),
+    });
+  });
+});
+```
+
+---
+
+### 方式三：HTMLRenderer（纯字符串，适合 SSR）
+
+```typescript
+import { HTMLRenderer } from '@action-x/ad-sdk';
+
+const html = HTMLRenderer.renderActionCard(ad, { variant: 'horizontal' });
+document.getElementById('ad-container').innerHTML = html;
+```
+
+---
+
+## 核心概念
+
+### 广告请求流程
+
+```
+用户发起对话
+    ↓
+调用 requestAds() / fetchAds()
+    ↓
+SDK 自动采集 ClientInfo（设备、系统、地理位置）
+    ↓
+POST /api/v1/ads/request（conversationContext + slots + clientInfo）
+    ↓
+后端返回 AdResponseBatch（requestId + 各广告位广告列表）
+    ↓
+调用 render() / DOMRenderer.renderXxx()
+    ↓
+DOM 绑定点击事件 → 点击追踪（异步）+ 打开目标 URL
+IntersectionObserver → 50% 可见 + 1s 延迟 → 曝光追踪
+```
+
+### Analytics 追踪机制
+
+| 事件 | 触发时机 | 端点 |
+|------|---------|------|
+| 曝光（impression）| 50% 可见 + 持续 1000ms | `POST /api/v1/ads/impression` |
+| 点击（click）| 用户点击 CTA 按钮 | `POST /api/v1/ads/click` |
+| 可视性（viewability）| 全程监测，批量上报 | `POST /api/v1/ads/viewability/batch` |
+
+### API Key 传递
+
+```ts
+// 方式 1：构造函数传入（推荐）
+new AdManager({ apiKey: 'ak_xxx', ... })
+fetchAds(params, { apiKey: 'ak_xxx' })
+
+// 方式 2：全局变量（适合动态配置场景）
+window.__AD_CONFIG__ = { apiKey: 'ak_xxx', apiBaseUrl: '...' };
+```
+
+---
+
+## API 参考
+
+### AdManager
+
+主控类，管理广告请求、缓存、渲染和事件。
+
+#### 构造函数
+
+```typescript
+new AdManager(config: AdManagerConfig)
+
+interface AdManagerConfig {
+  apiBaseUrl: string;       // 必填：API 基础地址
+  apiKey?: string;          // 推荐：API 认证密钥
+  slots: AdSlotRequest[];   // 必填：广告位配置列表
+  enabled?: boolean;        // 是否启用，默认 true
+  debug?: boolean;          // 调试日志，默认 false
+}
+```
+
+#### `requestAds(context): Promise<AdResponseBatch>`
+
+```typescript
+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;
+  },
+});
+```
+
+#### `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;
+  }
+)
+```
+
+#### 事件
+
+```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);
+```
+
+#### 其他方法
+
+| 方法 | 说明 |
+|------|------|
+| `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()` | 销毁实例，清理监听器 |
+
+---
+
+### fetchAds / adaptAdToKoahAd
+
+```typescript
+import { fetchAds, adaptAdToKoahAd } from '@action-x/ad-sdk';
+
+// 请求广告（自动注入 ClientInfo）
+const result: AdResponseBatch = await fetchAds(
+  {
+    conversationContext: { query: '...', response?: '...' },
+    userContext?: { sessionId: '...' },
+    slots: AdSlotRequest[],
+  },
+  { apiBaseUrl?: string, apiKey?: string }
+);
+
+// 转换 AdaptedAdContent → KoahAd
+const koahAd: KoahAd = adaptAdToKoahAd(adaptedAdContent);
+```
+
+---
+
+### HTMLRenderer
+
+生成广告 HTML 字符串，适合 SSR 或自行控制 DOM。
+
+```typescript
+import { HTMLRenderer } from '@action-x/ad-sdk';
+
+// Action Card
+HTMLRenderer.renderActionCard(ad, { variant?: 'horizontal' | 'vertical' | 'compact', includeWrapper?: boolean })
+
+// Suffix Ad
+HTMLRenderer.renderSuffixAd(ad)
+
+// Sponsored Source
+HTMLRenderer.renderSponsoredSource(ad)
+
+// Lead Gen
+HTMLRenderer.renderLeadGenAd(ad)
+
+// 批量渲染
+HTMLRenderer.renderAds(ads, renderFn?)
+```
+
+---
+
+### DOMRenderer
+
+创建真实 DOM 并绑定事件追踪，不依赖 AdManager。
+
+```typescript
+import { DOMRenderer } from '@action-x/ad-sdk';
+
+// Action Card（click 绑定 .ax-ad-cta）
+DOMRenderer.renderActionCard(ad, container, {
+  variant?: 'horizontal' | 'vertical' | 'compact',
+  analytics?: AdAnalyticsInfo,
+  onClick?: (ad) => void,
+  onImpression?: (ad) => void,
+})
+
+// Suffix Ad（click 绑定 .ax-ad-suffix-link）
+DOMRenderer.renderSuffixAd(ad, container, {
+  variant?: 'block' | 'inline' | 'minimal',  // 默认 'block'
+  analytics?, onClick?, onImpression?,
+})
+
+// Sponsored Source（click 绑定 .ax-ad-source-link）
+DOMRenderer.renderSponsoredSource(ad, container, {
+  variant?: 'card' | 'list-item' | 'minimal',  // 默认 'card'
+  analytics?, onClick?, onImpression?,
+})
+
+// Lead Gen（click 绑定 .ax-ad-leadgen-cta）
+DOMRenderer.renderLeadGenAd(ad, container, {
+  analytics?, onClick?, onImpression?,
+})
+
+// 批量渲染
+DOMRenderer.renderAds(ads, container, renderFn?, options?)
+```
+
+**点击流程**：异步发送 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);
+
+// 批量
+await trackImpressionsBatch([event1, event2]);
+await trackClicksBatch([event1, event2]);
+
+// 自定义实例
+const analytics = createAnalytics({ baseUrl: '...', timeout: 5000, debug: true });
+const session   = createSession({ storage: 'memory' });
+```
+
+#### SessionManager
+
+```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,
+})
+```
+
+---
+
+### ViewabilityTracker
+
+IAB/MRC 标准可视性追踪（>50% 可见 + >1 秒 = 达标）。
+
+```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,
+  },
+  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 },
+});
+```
+
+---
+
+### EventEmitter
+
+```typescript
+import { EventEmitter } from '@action-x/ad-sdk';
+
+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 展示 | 固定位置 |
+
+---
+
+## 高级用法
+
+### 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';
+
+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>
+```
+
+---
+
+## 依赖 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