React - AdMesh Documentation

Looking for Flutter?

Use the AdMesh Flutter UI SDK for native recommendation rendering, tracking, and theming.

Quick Start

Get started with AdMesh in 3 simple steps:

Install the Package

npm install admesh-ui-sdk@latest

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.

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:

Format	Use Case	Component
Tail	Inline tails with product links	`AdMeshRecommendations`
Product	Product cards with details	`AdMeshRecommendations`
Weave	Embedded links in LLM responses	`WeaveAdFormatContainer`

Flutter SDK Guide

See the native Flutter integration guide for AdMeshSdk, AdMeshProvider, AdMeshRecommendations, tracking, and theming.

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

npm (recommended)

npm install admesh-ui-sdk@latest

Yarn

yarn add admesh-ui-sdk@latest

pnpm

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

Recommendations not showing

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

TypeScript errors

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"

Weave Ad Format not detecting links

Check:

You’re dispatching streamingStart and streamingComplete events
Events use the assistant message ID (from backend), not user message ID
Links are in the correct format (AdMesh tracking URLs)
See the Weave Ad Format troubleshooting guide

Tracking not working

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

Property	Type	Default	Description
`mode`	`'light' \| 'dark'`	`'light'`	Color scheme mode
`primaryColor`	`string`	`'#3b82f6'`	Primary brand color
`accentColor`	`string`	`'#8b5cf6'`	Accent color for highlights
`backgroundColor`	`string`	`'#ffffff'`	Background color
`textColor`	`string`	`'#1f2937'`	Primary text color
`borderRadius`	`string`	`'0.5rem'`	Border radius for components
`fontFamily`	`string`	`'system-ui'`	Font family
`shadowMd`	`string`	`'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

Dark Theme

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

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

Brand Theme

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

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

Minimal Theme

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

Looking for Flutter?

​Quick Start

​Core Concepts

​Session Management

​Available Formats

Flutter SDK Guide

​Core Components

​AdMeshProvider

​AdMeshRecommendations

Tail & Product Format Guide

​WeaveAdFormatContainer

Weave Ad Format Guide

​Streaming Event Utilities

​Installation Methods

​Requirements

React 16.8+

API Key

TypeScript

Modern Browser

​TypeScript Support

​Troubleshooting

​Styling & Customization

​Key Features

Style Isolation

Consistent Look

Custom Themes

Light & Dark Modes

​Default Styling

​Custom Theming

​Theme Options

​CSS Variables

​Example Themes

​Framework Integration

​Next.js + Tailwind

​React + Bootstrap

​Styling Best Practices

​Next Steps

Tail & Product Format

Weave Ad Format

Quick Start

Core Concepts

Session Management

Available Formats

Core Components

AdMeshProvider

AdMeshRecommendations

WeaveAdFormatContainer

Streaming Event Utilities

Installation Methods

Requirements

TypeScript Support

Troubleshooting

Styling & Customization

Key Features

Default Styling

Custom Theming

Theme Options

CSS Variables

Example Themes

Framework Integration

Next.js + Tailwind

React + Bootstrap

Styling Best Practices

Next Steps