Platform FAQ

Getting Started

What is AdMesh?

AdMesh is a conversational advertising platform that enables platforms (like AI assistants, search engines, and chat applications) to monetize through contextually relevant product recommendations. AdMesh provides two SDKs for integration:

React SDK (admesh-ui-sdk): For frontend integration with citation format and product card layouts
AdMesh Weave Node SDK (admesh-weave-node): For backend Node.js integration with weave format

How do I choose between weave format and citation format?

Aspect	Weave Format	Citation Format
What it is	Inline product cards embedded in conversation	Clickable links within conversational text
Best for	Visual-heavy platforms, mobile apps	Text-based platforms, chat interfaces
Integration	AdMesh Weave Node SDK (backend)	React SDK (frontend)
User Experience	Rich, interactive cards	Minimal, non-intrusive links
Implementation	Backend Node.js integration	Frontend React integration
Performance	Requires more bandwidth	Lightweight

Choose Weave if:

Your platform supports rich media/cards
You want a visual, interactive experience
You have sufficient bandwidth

Choose Citation if:

Your platform is text-based
You want minimal UI changes
You want lightweight integration

For detailed comparison, see Choose Integration.

When should I use the React SDK vs. AdMesh Weave Node SDK?

Aspect	React SDK	AdMesh Weave Node SDK
Supported Formats	Citation, Product Cards	Weave Format
Best for	Frontend React applications	Backend Node.js applications
Setup Time	5-10 minutes	15-30 minutes
Customization	Limited (UI components)	Full control (backend logic)
Maintenance	Automatic updates	Manual updates
Language	JavaScript/TypeScript (React)	Node.js (JavaScript/TypeScript)
Deployment	Frontend (browser)	Backend (server)

Use React SDK if:

Your platform is built with React
You want citation or product card format
You want quick frontend integration
You need UI components for recommendations

Use AdMesh Weave Node SDK if:

You need weave format (inline product cards)
Your backend is built with Node.js
You want to embed recommendations in LLM responses
You need backend-side recommendation logic

For details, see React SDK or AdMesh Weave Node SDK.

React SDK Integration

How do I install the React SDK?

Install via npm:

npm install admesh-ui-sdk

Or with yarn:

yarn add admesh-ui-sdk

For detailed instructions, see Installation.

What formats does the React SDK support?

The React SDK supports:

Citation Format - Clickable links within conversational text
Product Card Layouts - Individual product recommendation cards

Not supported: Weave Format (use AdMesh Weave Node SDK instead)

How do I use the React SDK in my application?

Basic usage with AdMeshProvider:

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

export const MyApp = () => {
  const sessionId = 'user-session-123';

  return (
    <AdMeshProvider
      apiKey={process.env.REACT_APP_ADMESH_API_KEY}
      sessionId={sessionId}
    >
      <YourChatComponent />
    </AdMeshProvider>
  );
};

export const YourChatComponent = () => {
  const messages = [
    { messageId: 'msg_1', role: 'user', content: 'Show me laptops' },
    { messageId: 'msg_2', role: 'assistant', content: 'Here are some options...' }
  ];

  return (
    <div>
      {messages.map(msg => <div key={msg.messageId}>{msg.content}</div>)}
      <AdMeshRecommendations messages={messages} format="citation" />
    </div>
  );
};

Key points:

Wrap your app with <AdMeshProvider> and pass sessionId
Use <AdMeshRecommendations> to display recommendations
The SDK handles message deduplication and recommendation fetching automatically

For more examples, see Installation.

What is the sessionId parameter?

The sessionId parameter identifies a unique user session in AdMesh:

Purpose: Track recommendations across a conversation
Format: Any string (e.g., 'user-session-123')
Scope: Should be unique per user session
Lifetime: Persists for the duration of the conversation

Example:

// Generate a unique session ID for each user
const sessionId = `user-${Date.now()}`;

<AdMeshProvider apiKey={apiKey} sessionId={sessionId}>
  <App />
</AdMeshProvider>

Best Practices:

Generate a new sessionId for each user session
Store it in state or context
Pass the same sessionId throughout the conversation
Don’t change sessionId mid-conversation

Note: This is different from your platform’s chat ID. For example, in Perplexica:

chatId = Perplexica’s internal chat identifier
sessionId = AdMesh session identifier (passed to AdMeshProvider)

How do I customize the React SDK styling?

Use the theming API:

import {
  AdMeshLayout,
  mergeTheme,
  injectCustomTheme
} from 'admesh-ui-sdk';

const theme = mergeTheme({
  mode: 'dark',
  primaryColor: '#3b82f6',
  accentColor: '#ffffff'
});

injectCustomTheme(theme);

<AdMeshLayout recommendations={recommendations} theme={theme} />

For detailed styling options, see Styling System.

Does the React SDK work with my CSS framework?

Yes! The React SDK is platform-agnostic and works with:

Tailwind CSS
Bootstrap
Material-UI
Chakra UI
Styled Components
Emotion

The SDK’s styles are isolated and won’t conflict with your framework.

Weave Format Integration

How do I integrate weave format?

Weave format requires the AdMesh Weave Node SDK for backend Node.js integration:

Install SDK: npm install admesh-weave-node
Initialize SDK: Set up with your API key
Call Recommendation API: Get recommendations for user query
Embed in LLM Response: Integrate recommendations into your LLM response
Track Interactions: Fire exposure, click, and conversion pixels

Note: Weave format is a backend integration for Node.js applications. It embeds product recommendations directly in LLM responses.For step-by-step guide, see AdMesh Weave Node SDK.

What's the weave format API flow?

Backend (Node.js) Flow:

1. User Query (frontend)
   ↓
2. Backend receives query
   ↓
3. Backend calls AdMesh /recommend endpoint
   ↓
4. Backend receives recommendations with signed URLs
   ↓
5. Backend embeds recommendations in LLM response
   ↓
6. Frontend receives response with embedded ads
   ↓
7. Frontend fires exposure pixel when ad is shown
   ↓
8. Frontend fires click pixel when user clicks
   ↓
9. Conversions tracked via tracking pixels

Key Point: Weave format integration happens on the backend (Node.js) using the AdMesh Weave Node SDK. The frontend receives the response with recommendations already embedded.

How do I render weave format cards?

Backend (Node.js) generates the cards:The AdMesh Weave Node SDK returns product data that your backend embeds in the LLM response:

{
  "recommendations": [
    {
      "id": "rec_123",
      "title": "Product Name",
      "description": "Product description",
      "image_url": "https://...",
      "price": "$99.99",
      "click_url": "https://track.useadmesh.com/click?...",
      "exposure_pixel": "https://track.useadmesh.com/exposure?..."
    }
  ]
}

Backend responsibility:

Call AdMesh Weave Node SDK to get recommendations
Format recommendations as product cards
Embed cards in LLM response text
Return complete response to frontend

Frontend responsibility:

Display the LLM response with embedded cards
Fire exposure pixel when card is shown
Fire click pixel when user clicks
Handle card interactions

How do I track weave format interactions?

Frontend tracking (JavaScript):

// Fire exposure pixel when card is shown
const exposurePixel = new Image();
exposurePixel.src = recommendation.exposure_pixel;

// Fire click pixel when user clicks
window.open(recommendation.click_url, '_blank');

// Conversions are tracked brand-side via localStorage and tracking pixels
// See brand integration guide for conversion tracking implementation

Backend tracking (Node.js):The AdMesh Weave Node SDK handles backend-side tracking:

Exposure tracking when recommendations are generated
Click tracking via signed URLs
Conversion tracking via tracking pixels

For detailed tracking implementation, see AdMesh Weave Node SDK.

Citation Format Integration

How do I integrate citation format?

Citation format can be integrated via:

React SDK (recommended for React apps)
Direct API (for any platform)

Using React SDK:

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

<AdMeshLayout
  recommendations={recommendations}
  layout="citation"
/>

Using Direct API: See Citation Format for API details.

What does citation format look like?

Citation format displays recommendations as clickable links within conversational text:

Here are some great options for you:
- [Ad] Product Name (https://...)
- [Ad] Another Product (https://...)

Each link is tracked for clicks and conversions.

How do I customize citation format styling?

With React SDK:

const theme = mergeTheme({
  primaryColor: '#3b82f6',
  customCSS: `
    .admesh-link {
      color: #3b82f6;
      text-decoration: underline;
    }
  `
});

injectCustomTheme(theme);

API Integration

How do I get an API key?

Log in to your AdMesh Dashboard
Go to Settings → API Keys
Click Generate New Key
Copy your API key (format: admesh_prod_xxx)
Store securely (never commit to version control)

How do I authenticate API requests?

Include your API key in the Authorization header:

curl -H "Authorization: Bearer admesh_prod_xxx" \
  https://api.useadmesh.com/recommend

Or in your code:

const response = await fetch('https://api.useadmesh.com/recommend', {
  headers: {
    'Authorization': 'Bearer admesh_prod_xxx'
  }
});

What's the /recommend endpoint?

The /recommend endpoint returns recommendations for a user query:

POST /recommend
Content-Type: application/json
Authorization: Bearer admesh_prod_xxx

{
  "query": "best laptop for programming",
  "user_id": "user_123",
  "session_id": "session_456"
}

Response:

{
  "recommendations": [
    {
      "id": "rec_123",
      "title": "Product Name",
      "description": "...",
      "click_url": "https://...",
      "exposure_pixel": "https://..."
    }
  ]
}

What are tracking URLs?

Tracking URLs are cryptographically signed URLs for tracking interactions:

exposure_pixel: Fire when recommendation is shown
click_url: Redirect when user clicks

All URLs include:

HMAC-SHA256 signature
TTL (time-to-live, default 300 seconds)
Nonce for idempotency

Conversions are tracked brand-side via localStorage and tracking pixels, not through pre-generated URLs.Never modify these URLs - they’re signed and will fail if altered.

Performance & Optimization

What are the performance requirements?

Minimum requirements:

API Response Time: < 500ms
Recommendation Latency: < 1 second
Pixel Firing: < 100ms
SDK Bundle Size: ~25KB gzipped

Recommended:

API Response Time: < 200ms
Recommendation Latency: < 500ms
Pixel Firing: < 50ms

How can I optimize performance?

Best practices:

Cache Recommendations: Cache results for 5-10 minutes
Lazy Load SDK: Load SDK only when needed
Batch Requests: Combine multiple requests when possible
Use CDN: Serve SDK from CDN for faster delivery
Monitor Latency: Track API response times

What's the rate limit?

Rate limits:

Free Tier: 100 requests/minute
Pro Tier: 1,000 requests/minute
Enterprise: Custom limits

If you exceed limits, you’ll receive a 429 (Too Many Requests) response.

How do I handle rate limiting?

Implement exponential backoff:

async function callAPI(url, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url);
      if (response.status === 429) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      return response;
    } catch (error) {
      console.error('API error:', error);
    }
  }
}

Contextual Relevance

What is contextual relevance scoring?

Contextual relevance scoring measures how well a recommendation matches a user’s query. Scores range from 0-100:

90-100: Highly relevant
70-89: Relevant
50-69: Somewhat relevant
< 50: Not relevant

Higher scores mean better recommendations.

How is relevance calculated?

Relevance is calculated using:

Semantic Matching: Compare query embeddings with product embeddings
Keyword Matching: Match query keywords with product keywords
Category Matching: Match query intent with product categories
User History: Consider user’s past interactions

For details, see Contextual Relevance Score.

How can I improve relevance scores?

To improve scores:

Better Product Data: Provide detailed titles, descriptions, keywords
Accurate Categories: Assign correct product categories
Rich Metadata: Include price, brand, ratings, etc.
Update Regularly: Keep product data current

Testing & Debugging

How do I test my integration?

Testing steps:

Test API Key: Verify API key is valid
Test Endpoint: Call /recommend with test query
Test Rendering: Verify recommendations display correctly
Test Tracking: Verify pixels fire correctly
Test Edge Cases: Test with no results, errors, etc.

How do I debug integration issues?

Debugging tips:

Check Console: Look for JavaScript errors
Check Network: Verify API requests are successful
Check Pixels: Verify tracking pixels are firing
Check Logs: Review server logs for errors
Enable Debug Mode: Add debug=true to API requests

What should I test before going live?

Pre-launch checklist:

How do I report bugs?

To report bugs:

Email: [email protected]
Dashboard: Click Help → Report Bug
GitHub: Open issue in AdMesh repository

Include:

Description of the issue
Steps to reproduce
Expected vs. actual behavior
Screenshots/logs if applicable

Common Issues

My API requests are failing

Check:

API Key: Verify key is correct and not expired
Authorization Header: Ensure header format is correct
Endpoint URL: Verify you’re using correct endpoint
Request Body: Validate JSON is properly formatted
Network: Check internet connection

Recommendations aren't showing up

Troubleshoot:

API Response: Verify API returns recommendations
Rendering: Check if recommendations are being rendered
Styling: Verify CSS isn’t hiding recommendations
JavaScript: Check for JavaScript errors in console
Permissions: Verify API key has correct permissions

Tracking pixels aren't firing

Check:

Pixel URL: Verify pixel URL is correct
Network: Check if pixel request is being sent
Ad Blockers: Disable ad blockers and test
CORS: Verify CORS headers are correct
Timing: Ensure pixel fires at correct time

Performance is slow

Optimize:

Cache Results: Cache recommendations for 5-10 minutes
Lazy Load: Load SDK only when needed
Compress: Enable gzip compression
CDN: Use CDN for static assets
Monitor: Track API response times

Additional Resources

Choose Integration

Compare weave and citation formats

React SDK

React SDK installation and setup

Weave Format

Weave format integration guide

Citation Format

Citation format integration guide

Styling System

Customize component styling

API Playground

Test API endpoints interactively

Getting Started

For Advertisers

Platforms

SDKs

Core Concepts

Policies

FAQ

Getting Started

React SDK Integration

Example:

Best Practices:

Weave Format Integration

Citation Format Integration

API Integration

Performance & Optimization

Contextual Relevance

Testing & Debugging

Common Issues

Additional Resources

Choose Integration

React SDK

Weave Format

Citation Format

Styling System

API Playground

Getting Started

For Advertisers

Platforms

SDKs

Core Concepts

Policies

FAQ

​Getting Started

​React SDK Integration

​Example:

​Best Practices:

​Weave Format Integration

​Citation Format Integration

​API Integration

​Performance & Optimization

​Contextual Relevance

​Testing & Debugging

​Common Issues

​Additional Resources

Choose Integration

React SDK

Weave Format

Citation Format

Styling System

API Playground

Getting Started

React SDK Integration

Example:

Best Practices:

Weave Format Integration

Citation Format Integration

API Integration

Performance & Optimization

Contextual Relevance

Testing & Debugging

Common Issues

Additional Resources