AI Ad Network Frontend SDK

> 🚀 Zero-config SDK for AI-powered native ads with automatic client info collection
>
> 📦 Dual SDK Support: React + Universal (Framework-Agnostic)
>
> Version: 1.0.7

---

🎯 Quick Start

$3

``bash
npm install @ai-ad-network/frontend-sdk
`

`tsx
// 1. Wrap your app
import { AdProvider } from '@ai-ad-network/frontend-sdk';

// 2. Display ads
import { useAiAds, ActionCardAdV2 } from '@ai-ad-network/frontend-sdk';

function ChatApp() {
const { ads, requestId } = useAiAds(query, response, isFinished);

return ads.map((ad, index) => (
key={ad.id}
ad={ad}
requestId={requestId}
slotId="slot-1"
position={index}
totalAds={ads.length}
/>
));
}
`

$3

`bash
npm install @ai-ad-network/frontend-sdk
`

`javascript
import { AdManager, DOMRenderer } from '@ai-ad-network/frontend-sdk/universal';

const manager = new AdManager({
apiBaseUrl: '/api/v1',
apiKey: 'ak_your_key',
slots: [{ slotId: 'banner', position: 'top', adTypes: ['action-card'] }]
});

const result = await manager.requestAds({ conversationContext: { query } });
DOMRenderer.renderActionCardWithAnalytics(result.slots[0].ads[0], container, {
analytics: { requestId: result.requestId, slotId: 'banner', position: 0, totalAds: 1 },
manager
});
`

---

📚 Documentation

📖 Complete Documentation →

$3

| 文档 | 说明 |
|------|------|
| 快速开始指南 | 3分钟快速集成 |
| 完整使用文档 | 详细 API 说明和最佳实践 |
| 问题排查指南 | 常见问题和解决方案 |

$3

$3

| Guide | Description |
|-------|-------------|
| Installation | Install and configure the SDK |
| React Integration | Step-by-step React setup (3 min) |
| Universal Integration | Vue, Angular, Vanilla JS setup (3 min) |

$3

| Guide | Description |
|-------|-------------|
| Analytics Tracking | Impression & click tracking (V2 API) |
| ClientInfo API | Access device, user, app, geo data |
| Ad Formats | 7 native ad formats explained |

$3

| Reference | Description |
|-----------|-------------|
| React SDK API | Hooks, components, types |
| Universal SDK API | AdManager, renderers, Web Components |

$3

| Guide | Description |
|-------|-------------|
| Troubleshooting | Common issues & solutions |
| Migration Guide | V1 → V2 Analytics API migration |

---

✨ Features

| Feature | Description |
|---------|-------------|
| 🎯 Intent-based Ads | Ads matched to user intent |
| 🎨 7 Native Formats | Action Cards, Suffix, Sponsored Sources, Lead Gen, and more |
| 📊 V2 Analytics API | POST-based impression/click tracking (more reliable) |
| 🌐 OpenRTB Compliant | Zero-config auto-collection of device/app/user/geo data |
| ⚡ Optimized Performance | SWR caching, Intersection Observer, code splitting |
| 🎭 Headless Design | Full customization with CSS variables |
| 🌐 Framework-Agnostic | Works with React, Vue, Angular, Svelte, Vanilla JS, etc. |

---

📦 Package Exports

`json
{
"exports": {
".": {
"import": "./dist/index.esm.js",
"require": "./dist/index.js",
"types": "./dist/index.d.ts"
},
"./universal": {
"import": "./dist/universal/universal.esm.js",
"require": "./dist/universal/universal.cjs.js",
"types": "./dist/universal/universal.d.ts"
}
}
}
`

---

🎨 Available Ad Formats

| Format | React Component | Universal Method | Best For |
|--------|-----------------|------------------|----------|
| Action Card | ActionCardAdV2 | DOMRenderer.renderActionCard() | E-commerce, products |
| Suffix | SuffixAdV2 | DOMRenderer.renderSuffixAd() | Conversational ads |
| Sponsored Source | SponsoredSourceAdV2 | DOMRenderer.renderSponsoredSource() | Content citations |
| Lead Generation | LeadGenAd | DOMRenderer.renderLeadGenAd() | Lead capture, signups |

📖 Ad Formats Reference - Complete format guide

---

🆕 What's New

$3

- ✅ POST-based impression/click tracking (more reliable than pixel tracking)
- ✅ Request-level analytics with requestId
- ✅ Ad coordinates: (requestId, slotId, position, totalAds)
- ✅ Session management for user journey tracking
- ✅ Backward compatible with V1 pixel tracking

New Components: ActionCardAdV2, SuffixAdV2, SponsoredSourceAdV2

New Hooks: useAdTrackingV2

New Methods: AdManager.trackAdImpressionAPI(), AdManager.trackAdClick()

---

⚙️ Configuration

$3

`tsx
config={{
apiBaseUrl: string, // Required: API base URL
apiKey?: string, // Optional: API key (if not using backend proxy)
debug?: boolean, // Optional: Enable debug logging
enabled?: boolean, // Optional: Globally enable/disable ads
defaultFormats?: AdFormat[] // Optional: Default ad formats
}}
>
`

$3

`javascript
const manager = new AdManager({
apiBaseUrl: string, // Required: API base URL
apiKey?: string, // Optional: API key
slots?: AdSlotConfig[], // Optional: Predefined slots
enabled?: boolean // Optional: Enable/disable ads (default: true)
});
`

---

🔐 Security Best Practices

$3

`typescript
// Backend proxy (Node.js/Express)
app.post('/api/ads/request', async (req, res) => {
const AD_API_KEY = process.env.AD_API_KEY; // Server-side only
const response = await fetch('https://api.example.com/v1/ads/request', {
headers: { 'X-API-Key': AD_API_KEY },
body: JSON.stringify(req.body)
});
res.json(await response.json());
});
`

`tsx
// Frontend - No API key exposed



`

📖 Security Guide - Complete security documentation

---

✅ Integration Checklist

- [ ] SDK installed (npm install @ai-ad-network/frontend-sdk)
- [ ] Console shows SDK v1.0.7+
- [ ] React: App wrapped with
- [ ] Universal: AdManager initialized
- [ ] API key configured (or backend proxy set up)
- [ ] Network requests include clientInfo` field
- [ ] Ads are rendering
- [ ] Analytics events firing (check Network tab)

Done? 🎉 Successfully integrated!

---

🆘 Support

- 📧 Email: support@ai-ad-network.com
- 📖 Docs: https://docs.ai-ad-network.com
- 🐛 Issues: https://github.com/ai-ad-network/frontend-sdk/issues

---

📄 License

MIT

---

SDK Version: 1.0.7
Last Updated: 2026-02-04