AdMesh UI SDK


A comprehensive React + TypeScript component library for displaying AdMesh product recommendations across all ad unit formats with built-in tracking, theming, and accessibility support.

📦 Install from npm: npm install admesh-ui-sdk

🌐 Live Sites

- 🎭 Interactive Storybook: https://storybook.useadmesh.com/ - Explore all components and ad formats
- 📚 Complete Documentation: https://docs.useadmesh.com/ - Full SDK documentation and guides
- 🚀 AdMesh Dashboard: https://useadmesh.com - Get your API keys and manage campaigns
- 📦 npm Package: https://www.npmjs.com/package/admesh-ui-sdk - Install from npm registry

> 🎨 Component Showcase: This repository contains the UI SDK components with an interactive Storybook for exploring all ad formats and components.

🚀 Features

- Complete Ad Unit Library - All AdMesh ad formats in one unified SDK
- Citation-Based Conversation Ads - Display recommendations as numbered references within text
- Conversational Ad Units - Perfect for chat interfaces, AI assistants, and conversational experiences
- Floating & Auto Widgets - Non-intrusive recommendation displays
- Expandable Units - Rich, interactive product showcases
- Built-in Tracking - Automatic click, view, and conversion tracking
- Intelligent Layouts - Auto-selects optimal layout based on intent and data
- Advanced Customization - Complete freedom over colors, icons, fonts, and styling
- Theme System - Enhanced theming with presets, dark mode, and component overrides
- TypeScript First - Full type safety and IntelliSense support
- Framework Agnostic - React core, but designed for easy embedding
- Responsive Design - Mobile-first responsive components
- Accessibility - WCAG 2.1 AA compliant
- Weave Mode - Automatic link detection and enhancement for organic LLM responses
- Performance Optimized - 97% faster link detection with CSS selector optimization
- Multi-Domain Support - Works with api.useadmesh.com and *.useadmesh.com domains

📦 Installation

``bash
npm install admesh-ui-sdk
`

$3

The SDK automatically detects and enhances links from:
- api.useadmesh.com/click/* - Standard AdMesh domain
- .useadmesh.com/click/ - Any subdomain (e.g., tracking.useadmesh.com, custom.useadmesh.com)

$3

- Node.js: 16.0.0 or higher
- npm: 8.0.0 or higher
- React: 18.0.0 or 19.0.0
- React DOM: 18.0.0 or 19.0.0

🚀 Zero-Code Integration (Recommended for Platforms)

The AdMesh SDK provides a zero-code integration experience that handles everything automatically. Perfect for platforms that want to add monetized recommendations without writing custom code.

$3

Step 1: Install the SDK
`bash
npm install admesh-ui-sdk
`

Step 2: Add a container element
`html



Step 3: Initialize and fetch recommendations
`typescript
import { AdMeshSDK } from 'admesh-ui-sdk';

// Initialize once with your API key
const admesh = new AdMeshSDK({
apiKey: 'your-api-key-here'
});

// Generate session ID on your platform
const sessionId = AdMeshSDK.createSession();

// Fetch and render recommendations automatically
await admesh.showRecommendations({
query: userQuery,
containerId: 'admesh-recommendations',
session_id: sessionId
});
`

$3

`typescript
import { AdMeshSDK } from 'admesh-ui-sdk';

const admesh = new AdMeshSDK({
apiKey: 'admesh_prod_your_key_here'
});

// When user searches or asks a question
async function handleUserQuery(query: string, sessionId: string, messageId: string) {
try {
await admesh.showRecommendations({
query: query,
containerId: 'admesh-recommendations',
format: 'auto',
session_id: sessionId,
message_id: messageId
});
} catch (error) {
console.error('Failed to fetch recommendations:', error);
}
}

// Initialize session when conversation starts
const sessionId = AdMeshSDK.createSession();

// Generate message ID for each query
const messageId = AdMeshSDK.createMessageId(sessionId);

// Handle user query
await handleUserQuery('best CRM for small business', sessionId, messageId);
`

$3

The SDK is stateless regarding session management. Your platform is responsible for:

- Creating Sessions: Use AdMeshSDK.createSession() to generate a session ID
- Creating Message IDs: Use AdMeshSDK.createMessageId(sessionId) to generate message IDs
- Storing Sessions: Store session IDs in your platform's storage (localStorage, database, etc.)
- Passing IDs to SDK: Provide session_id and message_id when calling showRecommendations()

`typescript
// Generate IDs on your platform
const sessionId = AdMeshSDK.createSession();
const messageId = AdMeshSDK.createMessageId(sessionId);

// Store in your platform's storage
localStorage.setItem('admesh_session_id', sessionId);

// Pass to SDK when fetching recommendations
await admesh.showRecommendations({
query: userQuery,
containerId: 'admesh-recommendations',
session_id: sessionId,
message_id: messageId
});
`

$3

`typescript
const admesh = new AdMeshSDK({
apiKey: 'your-api-key', // Required
theme: { // Optional: customize appearance
mode: 'light',
primaryColor: '#3b82f6',
borderRadius: '8px'
}
});
`

$3

- ✅ API authentication with your API key
- ✅ Recommendation fetching from /aip/context endpoint (auction-based)
- ✅ Automatic rendering with appropriate UI components
- ✅ Exposure tracking (when recommendations are shown)
- ✅ Click tracking (when users click recommendations)
- ✅ Conversion tracking (when users complete actions)
- ✅ Error handling and logging
- ✅ Responsive design and theming

The /aip/context endpoint returns a recommendation object with:
- Full creative_input with all format fields (weave, tail, product_card)
- Complete billing information (CPX, CPC, CPA values)
- Tracking URLs (exposure_url, click_url, admesh_link)
- Format metadata (allowed_formats, preferred_format, fallback_formats)

$3

- ✅ Session creation and storage (use AdMeshSDK.createSession())
- ✅ Session persistence across page reloads
- ✅ Session lifecycle management (when to create new sessions)

$3

For custom styling needs, use the showRecommendations() method with the theme option:

`typescript
await admesh.showRecommendations({
query: 'best CRM for small business',
containerId: 'recommendations',
format: 'product',
session_id: sessionId,
message_id: messageId,
theme: {
mode: 'dark',
colors: {
primary: '#007bff',
secondary: '#6c757d'
}
}
});
`

🔍 Advanced: Inline Weave Exposure Tracking

When working directly with WeaveResponseProcessor you now receive richer context for exposure tracking. The optional onExposurePixel callback passed to scanAndProcessLinks() is invoked with { exposureUrl, adId, linkElement }, enabling you to plug the DOM node into your own IntersectionObserver logic (or the SDK’s helper).

`typescript
import {
WeaveResponseProcessor,
createInlineExposureTracker
} from 'admesh-ui-sdk';

const processor = new WeaveResponseProcessor();
const inlineTracker = createInlineExposureTracker();

processor.scanAndProcessLinks(container, recommendations, ({ exposureUrl, adId, linkElement }) => {
inlineTracker.startTracking({
exposureUrl,
adId,
linkElement,
sessionId: currentSessionId,
logPrefix: '[CustomInlineTracking]'
});
});
`

This guarantees inline/weave ads also respect the MRC requirement (50 % visible for 1 s) before firing pixels, and keeps exposure deduplication tied to your sessionId.

✨ Self-Contained Design

Zero configuration required! The AdMesh UI SDK is completely self-contained and works like Google Ads or any professional SDK:

- ✅ No Tailwind CSS setup needed - All styles are automatically injected
- ✅ No external CSS imports required - Works out of the box in any React app
- ✅ No build configuration changes - Just install and use
- ✅ Platform independent - Consistent appearance across all applications
- ✅ Zero dependencies - Only requires React and ReactDOM as peer dependencies

The SDK automatically injects all necessary styles when components are rendered, ensuring consistent appearance regardless of your application's CSS framework, Tailwind configuration, or styling approach.

🎯 Quick Start

$3

// Grid layout for recommendation cards
recommendations={recommendations}
layout="grid"
columns={3}
spacing="lg"
title="Recommended Solutions"
/>
`

📋 Component Comparison

Choose the right component for your use case:

| Component | Best For | Display Style | Integration Complexity | Mobile Optimized |
|-----------|----------|---------------|----------------------|------------------|
| AdMeshLayout | All use cases | Auto-adaptive | ⭐ Easy | ✅ Yes |
| AdMeshProductCard | Individual products | Single card | ⭐ Easy | ✅ Yes |
| AdMeshEcommerceCards | Product carousels | Horizontal scroll | ⭐ Easy | ✅ Yes |

🎯 AdMeshLayout

AdMeshLayout is the recommended component that automatically combines and optimizes all other components:

- Auto-Detection: Automatically chooses the best layout based on your content
- Multiple Layouts: Citation, ecommerce, grid, list, and mixed layouts
- Single API: One component handles all recommendation types
- Smart Optimization: Automatically limits items and optimizes for mobile
- Customizable: Full control over layout, spacing, and component behavior
- FTC Compliance: Includes proper "Sponsored", "Sponsored", and "" disclosures

$3

- Default numberOfItems: 1 for layout components, 3 for ecommerce
- Single Item Layout: When numberOfItems is 1, card displays at 100% width
- Disclosure Handling: Only AdMeshLayout shows disclosures - individual components are disclosure-free

The AdMeshLayout component is the recommended way to display AdMesh recommendations. It automatically detects the best layout based on your content and provides a single API for all recommendation types.

`tsx
import { AdMeshLayout } from 'admesh-ui-sdk';

// Auto-detection (recommended) - defaults to 1 item for layout, 3 for ecommerce
recommendations={recommendations}
ecommerceProducts={products}
conversationText="Based on your needs..."
layout="auto"
// maxItems defaults: 1 for layout, 3 for ecommerce
/>

// Specific layouts with custom maxItems





`

Layout Types:
- auto: Automatically detects best layout based on content
- citation: Direct links within conversation text
- ecommerce: Horizontal scrolling product grid
- grid: Responsive grid of recommendation cards
- list: Vertical list of simplified cards
- mixed: Combines multiple component types

Key Features:
- Smart Auto-Detection: Chooses optimal layout automatically
- Responsive Design: Adapts to all screen sizes
- Customizable: Control columns, spacing, titles, and behavior
- Component Props: Pass props to underlying components
- Event Handling: Unified click and hover handlers

📋 Individual Components

> Note: Individual components no longer display disclosure elements (Match Score, "Sponsored", ""). Only AdMeshLayout includes FTC-compliant disclosures. Use AdMeshLayout for platform integration.

$3

#### AdMeshProductCard
Individual product recommendation card with rich information display.

`tsx
// Default clean minimal design (recommended)
recommendation={recommendation}
showMatchScore={false} // Deprecated - Match Score removed from UI
showBadges={true}
showFeatures={false} // Default: clean minimal design
onClick={(adId, admeshLink) => window.open(admeshLink)}
/>

// With features for detailed showcases
recommendation={recommendation}
showFeatures={true} // Show key features section
onClick={(adId, admeshLink) => window.open(admeshLink)}
/>
`

Props:
- showFeatures (boolean, default: false) - Whether to display the key features section. Default is clean minimal design.
- showBadges (boolean, default: true) - Whether to show product badges
- showMatchScore (boolean, default: false) - Deprecated, match score removed from UI

#### AdMeshEcommerceCards
Horizontal scrolling product cards for ecommerce recommendations, similar to Google product search results.

`tsx
products={ecommerceProducts}
title="Recommended Laptops"
showPricing={true}
showRatings={true}
showBrand={true}
cardWidth="md"
maxCards={10}
onProductClick={(product) => window.open(product.admesh_link || product.url)}
/>
`

Perfect for:
- Product search results
- Ecommerce recommendations
- Mixed AdMesh + Walmart/Amazon products
- Google-style product carousels
- Shopping comparison displays

$3

#### AdMeshSummaryUnit
Display recommendations with summary text and follow-up suggestions.

`tsx
recommendations={recommendations}
summary="Here are the best CRM tools for your needs"
followupSuggestions={[
{ label: "Compare pricing", query: "CRM pricing comparison" },
{ label: "Free trials", query: "CRM free trial options" }
]}
onRecommendationClick={(adId, link) => window.open(link)}
onFollowupClick={(query) => console.log('Follow-up:', query)}
/>
`

#### AdMeshSummaryLayout
Layout component for displaying summary-style recommendations.

`tsx
recommendations={recommendations}
summary="Based on your requirements, here are the top recommendations"
layout="grid" // 'grid' | 'list'
showFollowups={true}
/>
`

Perfect for:
- AI assistant responses
- Conversation summaries
- Follow-up suggestions
- End-of-conversation recommendations

$3

#### AdMeshProductCard - Simple Variation
Simple, clean ad format for minimal integration.

`tsx
recommendation={recommendation}
variation="simple" // Creates inline ad format
onClick={(adId, admeshLink) => window.open(admeshLink)}
/>
`

$3

#### AdMeshBadge
Reusable badge component for highlighting features.

#### AdMeshLinkTracker
Wrapper for tracking any clickable element with built-in analytics.

`tsx
adId={recommendation.ad_id}
admeshLink={recommendation.admesh_link}
productId={recommendation.product_id}
onClick={() => handleClick()}
trackingData={{ title: recommendation.title }}
>


`

🎨 Advanced Customization & Theming

The AdMesh UI SDK provides complete freedom for AI platforms to customize colors, icons, fonts, and styling to match their brand perfectly.

$3

The AdMesh UI SDK ensures consistent styling across all components:

- 🎨 Unified Colors & Themes: All components share the same color palette and theme system
- 📝 Consistent Fonts: All components use the same font family for visual consistency
- 📐 Standardized Width: 100% width for all components except ecommerce cards (which maintain horizontal scrolling)
- 📱 Responsive Design: Mobile-friendly and adaptive across all screen sizes
- 🌙 Dark Mode Support: Seamless light/dark mode transitions with consistent styling

$3

`tsx
import { createAdMeshTheme, themePresets } from 'admesh-ui-sdk';

// Custom brand colors with automatic consistency
const customTheme = createAdMeshTheme({
mode: 'light',
primaryColor: '#ff6b6b', // Your brand color
secondaryColor: '#4ecdc4', // Secondary brand color
accentColor: '#45b7d1', // Accent color
borderRadius: '16px', // Custom border radius
fontFamily: '"Poppins", sans-serif', // Applied consistently across all components

// Custom icons (emoji or React components)
icons: {
starIcon: '🌟',
expandIcon: '▼',
collapseIcon: '▲'
},

// Component-specific overrides (width settings are automatically applied)
components: {
button: {
backgroundColor: '#custom-color',
borderRadius: '12px'
}
// Width settings are automatically applied:
// - productCard: { width: '100%' }
// - citationUnit: { width: '100%' }
// - inlineRecommendation: { width: '100%' }
// - ecommerce cards maintain auto width for horizontal scrolling
}
});

recommendations={recommendations}
theme={customTheme}
/>
`

$3

`tsx
// Use built-in presets



`

$3

`tsx
import { createDarkTheme } from 'admesh-ui-sdk';

const darkTheme = createDarkTheme({
primaryColor: '#a78bfa',
secondaryColor: '#34d399'
});
`

📊 Unified Recommendation JSON Response

All AdMesh ad units use the same unified recommendation response structure. This ensures consistency across all components and makes integration seamless.

$3

`typescript
interface AdMeshRecommendation {
// Core required fields
title: string; // Product/service title
reason: string; // Why this is recommended
intent_match_score: number; // 0-1 normalized match score
admesh_link: string; // Tracking URL for clicks
ad_id: string; // Unique ad identifier
product_id: string; // Unique product identifier

// Core product/offer fields
url?: string; // Direct product URL
redirect_url?: string; // Alternative redirect URL
description?: string; // Product description
pricing?: string; // Pricing information
reward_note?: string | null; // Special offers/rewards
keywords?: string[]; // Product keywords
categories?: string[]; // Product categories
features?: string[]; // Key features list
integrations?: string[]; // Integration capabilities
has_free_tier?: boolean; // Free tier availability
trial_days?: number; // Trial period length
audience_segment?: string; // Target audience
is_ai_powered?: boolean; // AI-powered product flag
is_open_source?: boolean; // Open source flag
offer_trust_score?: number; // Offer trust rating (0-1)
brand_trust_score?: number; // Brand trust rating (0-1)

// Marketing content fields (for rich ad units)
recommendation_title?: string; // Marketing-optimized title
recommendation_description?: string; // Marketing-optimized description
offer_images?: Array<{ // Promotional images
url: string;
storage_path: string;
filename: string;
content_type: string;
dimensions: {
width: number;
height: number;
};
}>;
product_logo?: { // Product logo
url: string;
storage_path: string;
filename: string;
content_type: string;
dimensions: {
width: number;
height: number;
};
};
feature_sections?: Array<{ // Feature sections for expandable units
title: string;
description: string;
icon: string;
}>;

// Extended compatibility fields
reviews_summary?: string; // User reviews summary
security?: string[]; // Security features
support?: string[]; // Support options
badges?: string[]; // Display badges
}
`

$3

`typescript
interface AgentRecommendationResponse {
session_id: string;
intent: {
goal: string;
intent_group: string;
purchase_intent: string;
intent_type: string;
layout_type: string;
categories: string[];
};
response: {
summary: string;
recommendations: AdMeshRecommendation[];
followup_suggestions: Array<{
label: string;
query: string;
}>;
layout_type: string;
};
tokens_used: number;
model_used: string;
}
`

$3

The same recommendation object works seamlessly across all ad unit types:

`tsx
// Same recommendations for all components
const recommendations: AdMeshRecommendation[] = [
{
title: "HubSpot CRM",
reason: "Perfect for remote teams with excellent collaboration features",
intent_match_score: 0.92,
admesh_link: "https://useadmesh.com/track?ad_id=hubspot-123",
ad_id: "hubspot-123",
product_id: "hubspot-crm",
has_free_tier: true,
trial_days: 14,
keywords: ["CRM", "Sales", "Marketing"],
pricing: "Free tier available, paid plans from $45/month",
// ... additional fields as needed
}
];

// Use with any ad unit
{recommendations.map(rec => )}


`

🎯 Layout-Based Integration

The AdMeshLayout component automatically adapts to different contexts and use cases.

$3

`tsx
import React from 'react';
import { AdMeshLayout } from 'admesh-ui-sdk';

const recommendations = [
{
product_id: "hubspot-crm",
title: "HubSpot CRM",
recommendation_description: "Perfect for remote teams with excellent collaboration features",
admesh_link: "https://useadmesh.com/track?ad_id=hubspot-123",
categories: ["CRM", "Sales", "Marketing"],
trust_score: 95.0,
meta: {
ad_id: "hubspot-123",
intent_match_score: 92.0,
reason: "Perfect for remote teams with excellent collaboration features"
}
}
];

function RecommendationDisplay() {
return (


#### Auto Layout
Automatically selects the best layout based on content and context:
`tsx
recommendations={recommendations}
layout="auto"
/>
`

#### Grid Layout
Displays recommendations in a responsive grid format:
`tsx
recommendations={recommendations}
layout="grid"
/>
`

#### List Layout
Displays recommendations in a vertical list format:
`tsx
recommendations={recommendations}
layout="list"
/>
`

#### Citation Layout
Displays recommendations as inline citations within text:
`tsx
recommendations={recommendations}
layout="citation"
/>
`

$3

#### AdMeshBadge
Reusable badge component for highlighting features and trust indicators:

`tsx
import { AdMeshBadge } from 'admesh-ui-sdk';

type="trust" // 'trust' | 'feature' | 'promotion'
variant="primary" // 'primary' | 'secondary' | 'success'
size="small" // 'small' | 'medium' | 'large'
text="Highly Trusted"
/>
`

#### AdMeshLinkTracker
Wrapper component for tracking clicks on any element:

`tsx
import { AdMeshLinkTracker } from 'admesh-ui-sdk';

adId={recommendation.meta.ad_id}
admeshLink={recommendation.admesh_link}
productId={recommendation.product_id}
onClick={() => handleClick()}
trackingData={{ title: recommendation.title }}
>


`

Key Features:
- Automatic Tracking: Built-in click and view tracking
- Custom Elements: Wrap any component for tracking
- Analytics Integration: Seamless data collection
- Performance Optimized: Minimal overhead

🎨 Theming and Customization

The AdMesh UI SDK provides comprehensive theming capabilities for all components.

$3

`tsx
import { createAdMeshTheme } from 'admesh-ui-sdk';

const customTheme = createAdMeshTheme({
mode: 'light', // 'light' | 'dark'
accentColor: '#2563eb',
borderRadius: '8px',
fontFamily: 'Inter, sans-serif'
});

recommendations={recommendations}
theme={customTheme}
/>
`

$3

`tsx
import { createDarkTheme } from 'admesh-ui-sdk';

const darkTheme = createDarkTheme({
accentColor: '#3b82f6'
});

recommendations={recommendations}
theme={darkTheme}
/>
`

$3

All components support custom styling through className and style props:

`tsx
recommendations={recommendations}
className="my-custom-recommendations"
style={{
backgroundColor: '#f8f9fa',
borderRadius: '12px',
padding: '16px'
}}
/>
`
`

$3

#### Chat Application
`tsx
function ChatApp() {
const [messages, setMessages] = useState([]);
const [recommendations, setRecommendations] = useState([]);

const handleUserMessage = async (message) => {
// Add user message
setMessages(prev => [...prev, { role: 'user', content: message }]);

// Get AI response and recommendations
const response = await getAIResponse(message);
setMessages(prev => [...prev, { role: 'assistant', content: response.text }]);

// Show recommendations if available
if (response.recommendations) {
setRecommendations(response.recommendations);
}
};

return (