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

React Projects

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

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

<AdProvider config={{ apiBaseUrl: '/api/v1', apiKey: 'ak_your_key' }}>
  <App />
</AdProvider>

// 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) => (
    <ActionCardAdV2
      key={ad.id}
      ad={ad}
      requestId={requestId}
      slotId="slot-1"
      position={index}
      totalAds={ads.length}
    />
  ));
}

Other Frameworks (Vue, Angular, Vanilla JS)

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

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 →

中文文档 | Chinese Docs

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

English Documentation

Getting Started

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

Core Features

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

API Reference

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

Support

| 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

{
  "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

V2 Analytics API (Current Version)

• ✅ 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

AdProvider Config (React)

<AdProvider
  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
  }}
>

AdManager Config (Universal)

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

Recommended: Backend Proxy Mode

// 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());
});

// Frontend - No API key exposed
<AdProvider config={{ apiBaseUrl: '/api/ads' }}>
  <App />
</AdProvider>

📖 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 <AdProvider>
• [ ] 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: [email protected]
• 📖 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