Skip to main content

​
Quick Start

Get started with AdMesh in 3 simple steps:
1

Install the Package

npm install admesh-ui-sdk@latest
2

Wrap Your App with AdMeshProvider

import { AdMeshProvider } from 'admesh-ui-sdk';

<AdMeshProvider apiKey="your-api-key" sessionId={sessionId}>
  <YourApp />
</AdMeshProvider>
The provider initializes the SDK and manages your session context.
3

Choose Your Integration Format

Select the format that matches your use case:Tail & Product Format - Separate recommendations panel
import { AdMeshRecommendations } from 'admesh-ui-sdk';

{messages.map((msg) => (
  msg.role === 'assistant' && msg.userQuery && msg.userMessageId && (
    <AdMeshRecommendations
      key={msg.messageId}
      messageId={msg.userMessageId}  // Required: User message ID (not assistant message ID)
      query={msg.userQuery}  // Required: User's original query
    />
  )
))}
Weave Ad Format - Embedded links in LLM responses
import { WeaveAdFormatContainer } from 'admesh-ui-sdk';

<WeaveAdFormatContainer
  messageId={message.messageId}
  query={userQuery}
  fallbackFormat="tail"
>
  <YourLLMResponse />
</WeaveAdFormatContainer>

​
Core Concepts

​
Session Management

AdMesh uses sessions to track user interactions across multiple messages:
  • Session ID: Unique identifier for a user’s conversation session
  • Message ID: Unique identifier for each individual message/query
// Generate a session ID when user starts a conversation
const sessionId = crypto.randomBytes(16).toString('hex');

// Generate a message ID for each query
const messageId = crypto.randomBytes(7).toString('hex');
Your application is responsible for generating and managing session and message IDs. The SDK accepts these IDs but does not generate them.

​
Available Formats

AdMesh supports three recommendation formats:
FormatUse CaseComponent
TailInline tails with product linksAdMeshRecommendations
ProductProduct cards with detailsAdMeshRecommendations
WeaveEmbedded links in LLM responsesWeaveAdFormatContainer

​
Core Components

​
AdMeshProvider

Context provider that initializes the SDK and manages session state. Required - wrap your entire app with this component. 
interface AdMeshProviderProps {
  apiKey: string;            // Your AdMesh API key (required)
  sessionId: string;         // Current session ID (required)
  theme?: AdMeshTheme;       // Optional: Custom theme
  apiBaseUrl?: string;       // Optional: API base URL (defaults to production)
  language?: string;         // Optional: User language in BCP 47 format (e.g., "en-US")
  geo_country?: string;      // Optional: User country code in ISO 3166-1 alpha-2 format (e.g., "US")
  userId?: string;           // Optional: Anonymous hashed user ID
  model?: string;            // Optional: AI model identifier (e.g., "gpt-4o")
  messages?: Array<{ role: string; content: string; id?: string }>;  // Optional: Conversation history
  children: React.ReactNode; // Your app components
}
Example: 
import { AdMeshProvider } from 'admesh-ui-sdk';

<AdMeshProvider apiKey="your-api-key" sessionId={sessionId}>
  <ChatInterface />
</AdMeshProvider>

​
AdMeshRecommendations

Displays recommendations in a separate panel. Use for Tail or Product format. 
interface AdMeshRecommendationsProps {
  messageId: string;                      // Required: Message ID (user message ID, not assistant message ID)
  query: string;                          // Required: User's original query
  onRecommendationsShown?: (messageId: string) => void;  // Optional: Callback when recommendations shown
  onError?: (error: Error) => void;       // Optional: Error handler
  onPasteToInput?: (content: string) => void;  // Optional: For bridge format CTA button
  followups_container_id?: string;        // Optional: Container ID for follow-up suggestions
  onExecuteQuery?: (query: string) => void | Promise<void>;  // Optional: Handler for follow-up queries
  onFollowupDetected?: (followupQuery: string, followupEngagementUrl: string, recommendationId: string) => void;  // Optional: Callback when follow-up detected
  isContainerReady?: boolean;             // Optional: Signal when follow-up container is ready
}
Example: 
import { AdMeshRecommendations } from 'admesh-ui-sdk';

{messages.map((msg) => (
  msg.role === 'assistant' && msg.userQuery && msg.userMessageId && (
    <AdMeshRecommendations
      key={msg.messageId}
      messageId={msg.userMessageId}  // Required: User message ID (not assistant message ID)
      query={msg.userQuery}  // Required: User's original query
      followups_container_id={`admesh-followups-${msg.messageId}`}
      onExecuteQuery={(query) => sendMessage(query)}
    />
  )
))}

Tail & Product Format Guide

Complete integration guide for Tail & Product Format

​
WeaveAdFormatContainer

Wraps LLM response content and detects embedded AdMesh links. Use for Weave Ad Format. 
interface WeaveAdFormatContainerProps {
  messageId: string;                      // Required: Assistant message ID
  query?: string;                         // Optional: User's query (for fallback recommendations)
  fallbackFormat?: 'tail' | 'product';   // Optional: Fallback format if no links found (default: 'tail')
  children: React.ReactNode;              // Required: LLM response content
  onLinksDetected?: (count: number) => void;  // Optional: Callback when links detected
  onNoLinksDetected?: () => void;        // Optional: Callback when no links detected
  onError?: (error: Error) => void;      // Optional: Error handler
  onFallbackChange?: (shouldFallback: boolean) => void;  // Optional: Callback when fallback state changes
  onWeaveAttempt?: (messageId: string) => void;  // Optional: Callback when weave injection attempted
  onWeaveOutcome?: (messageId: string, success: boolean, reason?: string) => void;  // Optional: Callback when weave outcome determined
  followups_container_id?: string;       // Optional: Container ID for follow-up suggestions
  onExecuteQuery?: (query: string) => void | Promise<void>;  // Optional: Handler for follow-up queries
  onFollowupDetected?: (followupQuery: string, followupEngagementUrl: string, recommendationId: string) => void;  // Optional: Callback when follow-up detected
  isContainerReady?: boolean;            // Optional: Signal when follow-up container is ready
  className?: string;                     // Optional: CSS class for container
}
Example: 
import { WeaveAdFormatContainer } from 'admesh-ui-sdk';

<WeaveAdFormatContainer
  messageId={message.messageId}
  query={userQuery}
  fallbackFormat="tail"
>
  <Markdown>{message.content}</Markdown>
</WeaveAdFormatContainer>

Weave Ad Format Guide

Complete integration guide for Weave Ad Format with event-driven architecture

​
Streaming Event Utilities

For Weave Ad Format only - dispatch events to coordinate link detection with streaming responses. 
// Dispatch when streaming starts
dispatchStreamingStartEvent(messageId: string, sessionId: string): void

// Dispatch when streaming completes
dispatchStreamingCompleteEvent(messageId: string, sessionId: string, metadata?: object): void
Example: 
import {
  dispatchStreamingStartEvent,
  dispatchStreamingCompleteEvent
} from 'admesh-ui-sdk';

// When assistant message ID received from backend
dispatchStreamingStartEvent(assistantMessageId, sessionId);

// When streaming completes
dispatchStreamingCompleteEvent(assistantMessageId, sessionId);
These utilities are only needed for Weave Ad Format. See the Weave Ad Format guide for complete integration details.

​
Installation Methods

yarn add admesh-ui-sdk@latest

pnpm add admesh-ui-sdk@latest

​
Requirements

React 16.8+

Requires React with Hooks support

API Key

Get your API key from the AdMesh dashboard

TypeScript

Full TypeScript support included

Modern Browser

Supports all modern browsers (Chrome, Firefox, Safari, Edge)

​
TypeScript Support

The SDK is written in TypeScript and includes full type definitions: 
import type {
  AdMeshProviderProps,
  AdMeshRecommendationsProps,
  WeaveAdFormatContainerProps,
  Message
} from 'admesh-ui-sdk';
All components and utilities are fully typed for the best developer experience.

​
Troubleshooting

Check:
  • API key is valid and provided to AdMeshProvider
  • sessionId is provided to AdMeshProvider
  • Component is wrapped inside AdMeshProvider
  • Messages array is not empty (for AdMeshRecommendations)
  • Network requests are not blocked by CORS or ad blockers
Solution:
  • Ensure you’re using TypeScript 4.0 or higher
  • Import types explicitly: import type { Message } from 'admesh-ui-sdk'
  • Check that your tsconfig.json includes "moduleResolution": "node"
Note: Tracking is fully automatic. Do NOT:
  • Manually fire tracking pixels
  • Modify tracking URLs
  • Implement custom tracking logic
The SDK handles all tracking internally.

​
Styling & Customization

The AdMesh UI SDK includes a simple, framework-agnostic styling system that ensures your components look clean and consistent—no matter where they’re embedded (Next.js, React, Vite, or custom platforms).

​
Key Features

Style Isolation

Prevents CSS conflicts with host frameworks like Tailwind or Bootstrap.

Consistent Look

Same visual quality across all environments.

Custom Themes

Easily adjust colors, borders, and typography.

Light & Dark Modes

Built-in theme switching with simple configuration.

​
Default Styling

By default, the SDK injects its own scoped styles automatically. No CSS import is needed. 
import { AdMeshProvider, AdMeshRecommendations } from 'admesh-ui-sdk';

<AdMeshProvider apiKey="your-api-key" sessionId={sessionId}>
  <AdMeshRecommendations
    messageId={messageId}
    query={userQuery}
    format="tail"
  />
</AdMeshProvider>

​
Custom Theming

You can customize the appearance by passing a theme to the AdMeshProvider: 
import { AdMeshProvider } from 'admesh-ui-sdk';

const customTheme = {
  mode: 'dark',
  primaryColor: '#3b82f6',
  accentColor: '#ffffff',
  borderRadius: '0.5rem',
  fontFamily: 'Inter, sans-serif'
};

<AdMeshProvider
  apiKey="your-api-key"
  sessionId={sessionId}
  theme={customTheme}
>
  <YourApp />
</AdMeshProvider>

​
Theme Options

PropertyTypeDefaultDescription
mode'light' | 'dark''light'Color scheme mode
primaryColorstring'#3b82f6'Primary brand color
accentColorstring'#8b5cf6'Accent color for highlights
backgroundColorstring'#ffffff'Background color
textColorstring'#1f2937'Primary text color
borderRadiusstring'0.5rem'Border radius for components
fontFamilystring'system-ui'Font family
shadowMdstring'0 4px 12px rgba(0,0,0,0.08)'Medium shadow

​
CSS Variables

You can also override AdMesh styling with standard CSS variables: 
:root {
  --admesh-primary-color: #3b82f6;
  --admesh-border-radius: 10px;
  --admesh-font-family: 'Inter', sans-serif;
  --admesh-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.08);
}

​
Example Themes

const darkTheme = {
  mode: 'dark',
  primaryColor: '#0ea5e9',
  backgroundColor: '#1f2937',
  textColor: '#f9fafb'
};

<AdMeshProvider theme={darkTheme} apiKey="..." sessionId="...">
  <YourApp />
</AdMeshProvider>

const brandTheme = {
  primaryColor: '#6366f1',
  accentColor: '#8b5cf6',
  borderRadius: '0.75rem',
  fontFamily: 'Poppins, sans-serif'
};

<AdMeshProvider theme={brandTheme} apiKey="..." sessionId="...">
  <YourApp />
</AdMeshProvider>

const minimalTheme = {
  primaryColor: '#000',
  backgroundColor: '#fff',
  borderRadius: '0px',
  shadowMd: 'none'
};

<AdMeshProvider theme={minimalTheme} apiKey="..." sessionId="...">
  <YourApp />
</AdMeshProvider>

​
Framework Integration

​
Next.js + Tailwind

AdMesh styles are isolated from Tailwind classes, so you can safely use both: 
import { AdMeshProvider, AdMeshRecommendations } from 'admesh-ui-sdk';

export default function Recommendations() {
  return (
    <AdMeshProvider apiKey={process.env.NEXT_PUBLIC_ADMESH_API_KEY} sessionId={sessionId}>
      <div className="p-4 bg-white rounded-lg">
        <AdMeshRecommendations
          messageId={messageId}
          query={userQuery}
          format="tail"
        />
      </div>
    </AdMeshProvider>
  );
}

​
React + Bootstrap

import { AdMeshProvider, AdMeshRecommendations } from 'admesh-ui-sdk';

export default function App() {
  return (
    <AdMeshProvider apiKey={process.env.REACT_APP_ADMESH_API_KEY} sessionId={sessionId}>
      <div className="container">
        <AdMeshRecommendations
          messageId={messageId}
          query={userQuery}
          format="tail"
        />
      </div>
    </AdMeshProvider>
  );
}

​
Styling Best Practices

✅ DO:
  • Use the theme prop on AdMeshProvider for global styling
  • Leverage CSS variables for fine-grained control
  • Test your theme in both light and dark modes
  • Keep styles consistent with your brand
❌ DON’T:
  • Directly modify AdMesh component classes (they may change)
  • Override internal styles with !important (use theme API instead)
  • Mix multiple theming approaches (choose one method)

​
Next Steps

Choose your integration format and follow the detailed guide:

Tail & Product Format

Display recommendations in a separate panelBest for: Separate recommendations UI, simple integrationSetup time: 5-10 minutes

Weave Ad Format

Embed recommendations directly in LLM responsesBest for: Natural integration, conversational adsSetup time: 15-20 minutes