> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useadmesh.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform FAQ

> Frequently asked questions from platform integrators about format selection, SDK usage, API integration, and implementation

## Getting Started

<AccordionGroup data-faq-section="Getting Started">
  <Accordion title="What is AdMesh?" data-faq-item="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 tail format and product card layouts
    * **AdMesh Weave Node SDK** (`admesh-weave-node`): For backend Node.js integration with weave format
  </Accordion>

  <Accordion title="How do I choose between weave format and tail format?" data-faq-item="How do I choose between weave format and tail format?">
    | Aspect              | Weave Format                                  | Tail 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 Tail if:**

    * Your platform is text-based
    * You want minimal UI changes
    * You want lightweight integration
  </Accordion>

  <Accordion title="When should I use the React SDK vs. AdMesh Weave Node SDK?" data-faq-item="When should I use the React SDK vs. AdMesh Weave Node SDK?">
    | Aspect                | React SDK                     | AdMesh Weave Node SDK           |
    | --------------------- | ----------------------------- | ------------------------------- |
    | **Supported Formats** | Tail, 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 tail 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
  </Accordion>
</AccordionGroup>

***

## React SDK Integration

<AccordionGroup data-faq-section="React SDK Integration">
  <Accordion title="How do I install the React SDK?" data-faq-item="How do I install the React SDK?">
    Install via npm:

    ```bash theme={null}
    npm install admesh-ui-sdk
    ```

    Or with yarn:

    ```bash theme={null}
    yarn add admesh-ui-sdk
    ```

    For detailed instructions, see [Installation](/ui-sdk/installation).
  </Accordion>

  <Accordion title="What formats does the React SDK support?" data-faq-item="What formats does the React SDK support?">
    The React SDK supports:

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

    **Not supported:** Weave Format (use AdMesh Weave Node SDK instead)
  </Accordion>

  <Accordion title="How do I use the React SDK in my application?" data-faq-item="How do I use the React SDK in my application?">
    Basic usage with AdMeshProvider:

    ```tsx theme={null}
    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="tail" />
        </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](/ui-sdk/installation).
  </Accordion>

  <Accordion title="What is the sessionId parameter?" data-faq-item="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:

    ```tsx theme={null}
    // 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)
  </Accordion>

  <Accordion title="How do I customize the React SDK styling?" data-faq-item="How do I customize the React SDK styling?">
    Use the theming API:

    ```tsx theme={null}
    import {
      AdMeshLayout,
      mergeTheme,
      injectCustomTheme
    } from 'admesh-ui-sdk';

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

    injectCustomTheme(theme);

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

  <Accordion title="Does the React SDK work with my CSS framework?" data-faq-item="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.
  </Accordion>
</AccordionGroup>

***

## Weave Format Integration

<AccordionGroup data-faq-section="Weave Format Integration">
  <Accordion title="How do I integrate weave format?" data-faq-item="How do I integrate weave format?">
    Weave format requires the **AdMesh Weave Node SDK** for backend Node.js integration:

    1. **Install SDK**: `npm install admesh-weave-node`
    2. **Initialize SDK**: Set up with your API key
    3. **Call Recommendation API**: Get recommendations for user query
    4. **Embed in LLM Response**: Integrate recommendations into your LLM response
    5. **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.
  </Accordion>

  <Accordion title="What's the weave format API flow?" data-faq-item="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.
  </Accordion>

  <Accordion title="How do I render weave format cards?" data-faq-item="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:

    ```json theme={null}
    {
      "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
  </Accordion>

  <Accordion title="How do I track weave format interactions?" data-faq-item="How do I track weave format interactions?">
    **Frontend tracking (JavaScript):**

    ```javascript theme={null}
    // 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
  </Accordion>
</AccordionGroup>

***

## Tail Format Integration

<AccordionGroup data-faq-section="Tail Format Integration">
  <Accordion title="How do I integrate tail format?" data-faq-item="How do I integrate tail format?">
    Tail format can be integrated via:

    1. **React SDK** (recommended for React apps)
    2. **Direct API** (for any platform)

    **Using React SDK:**

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

    <AdMeshLayout
      recommendations={recommendations}
      layout="tail"
    />
    ```

    **Using Direct API:**
    See [Tail Format](/platforms/tail-format) for API details.
  </Accordion>

  <Accordion title="What does tail format look like?" data-faq-item="What does tail format look like?">
    Tail 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.
  </Accordion>

  <Accordion title="How do I customize tail format styling?" data-faq-item="How do I customize tail format styling?">
    With React SDK:

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

    injectCustomTheme(theme);
    ```
  </Accordion>
</AccordionGroup>

***

## API Integration

<AccordionGroup data-faq-section="API Integration">
  <Accordion title="How do I get an API key?" data-faq-item="How do I get an API key?">
    1. Log in to your [AdMesh Dashboard](https://useadmesh.com)
    2. Go to **Settings** → **API Keys**
    3. Click **Generate New Key**
    4. Copy your API key (format: `admesh_prod_xxx`)
    5. Store securely (never commit to version control)
  </Accordion>

  <Accordion title="How do I authenticate API requests?" data-faq-item="How do I authenticate API requests?">
    Include your API key in the Authorization header:

    ```bash theme={null}
    curl -H "Authorization: Bearer admesh_prod_xxx" \
      https://api.useadmesh.com/recommend
    ```

    Or in your code:

    ```javascript theme={null}
    const response = await fetch('https://api.useadmesh.com/recommend', {
      headers: {
        'Authorization': 'Bearer admesh_prod_xxx'
      }
    });
    ```
  </Accordion>

  <Accordion title="What's the /recommend endpoint?" data-faq-item="What's the /recommend endpoint?">
    The `/recommend` endpoint returns recommendations for a user query:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "recommendations": [
        {
          "id": "rec_123",
          "title": "Product Name",
          "description": "...",
          "click_url": "https://...",
          "exposure_pixel": "https://..."
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="What are tracking URLs?" data-faq-item="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.
  </Accordion>
</AccordionGroup>

***

## Performance & Optimization

<AccordionGroup data-faq-section="Performance & Optimization">
  <Accordion title="What are the performance requirements?" data-faq-item="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
  </Accordion>

  <Accordion title="How can I optimize performance?" data-faq-item="How can I optimize performance?">
    Best practices:

    1. **Cache Recommendations**: Cache results for 5-10 minutes
    2. **Lazy Load SDK**: Load SDK only when needed
    3. **Batch Requests**: Combine multiple requests when possible
    4. **Use CDN**: Serve SDK from CDN for faster delivery
    5. **Monitor Latency**: Track API response times
  </Accordion>

  <Accordion title="What's the rate limit?" data-faq-item="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.
  </Accordion>

  <Accordion title="How do I handle rate limiting?" data-faq-item="How do I handle rate limiting?">
    Implement exponential backoff:

    ```javascript theme={null}
    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);
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Contextual Relevance

<AccordionGroup data-faq-section="Contextual Relevance">
  <Accordion title="What is contextual relevance scoring?" data-faq-item="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.
  </Accordion>

  <Accordion title="How is relevance calculated?" data-faq-item="How is relevance calculated?">
    Relevance is calculated using:

    1. **Semantic Matching**: Compare query embeddings with product embeddings
    2. **Keyword Matching**: Match query keywords with product keywords
    3. **Category Matching**: Match query intent with product categories
    4. **User History**: Consider user's past interactions

    For details, see [Contextual Relevance Score](/contextual-relevance-score).
  </Accordion>

  <Accordion title="How can I improve relevance scores?" data-faq-item="How can I improve relevance scores?">
    To improve scores:

    1. **Better Product Data**: Provide detailed titles, descriptions, keywords
    2. **Accurate Categories**: Assign correct product categories
    3. **Rich Metadata**: Include price, brand, ratings, etc.
    4. **Update Regularly**: Keep product data current
  </Accordion>
</AccordionGroup>

***

## Testing & Debugging

<AccordionGroup data-faq-section="Testing & Debugging">
  <Accordion title="How do I test my integration?" data-faq-item="How do I test my integration?">
    Testing steps:

    1. **Test API Key**: Verify API key is valid
    2. **Test Endpoint**: Call `/recommend` with test query
    3. **Test Rendering**: Verify recommendations display correctly
    4. **Test Tracking**: Verify pixels fire correctly
    5. **Test Edge Cases**: Test with no results, errors, etc.
  </Accordion>

  <Accordion title="How do I debug integration issues?" data-faq-item="How do I debug integration issues?">
    Debugging tips:

    1. **Check Console**: Look for JavaScript errors
    2. **Check Network**: Verify API requests are successful
    3. **Check Pixels**: Verify tracking pixels are firing
    4. **Check Logs**: Review server logs for errors
    5. **Enable Debug Mode**: Add `debug=true` to API requests
  </Accordion>

  <Accordion title="What should I test before going live?" data-faq-item="What should I test before going live?">
    Pre-launch checklist:

    * [ ] API key is valid and secure
    * [ ] Recommendations display correctly
    * [ ] Tracking pixels fire correctly
    * [ ] Error handling works
    * [ ] Performance meets requirements
    * [ ] Mobile responsiveness works
    * [ ] Accessibility is compliant
    * [ ] Security is verified
  </Accordion>

  <Accordion title="How do I report bugs?" data-faq-item="How do I report bugs?">
    To report bugs:

    1. **Email**: [mani@useadmesh.com](mailto:mani@useadmesh.com)
    2. **Dashboard**: Click **Help** → **Report Bug**
    3. **GitHub**: Open issue in AdMesh repository

    Include:

    * Description of the issue
    * Steps to reproduce
    * Expected vs. actual behavior
    * Screenshots/logs if applicable
  </Accordion>
</AccordionGroup>

***

## Common Issues

<AccordionGroup data-faq-section="Common Issues">
  <Accordion title="My API requests are failing" data-faq-item="My API requests are failing">
    Check:

    1. **API Key**: Verify key is correct and not expired
    2. **Authorization Header**: Ensure header format is correct
    3. **Endpoint URL**: Verify you're using correct endpoint
    4. **Request Body**: Validate JSON is properly formatted
    5. **Network**: Check internet connection
  </Accordion>

  <Accordion title="Recommendations aren't showing up" data-faq-item="Recommendations aren't showing up">
    Troubleshoot:

    1. **API Response**: Verify API returns recommendations
    2. **Rendering**: Check if recommendations are being rendered
    3. **Styling**: Verify CSS isn't hiding recommendations
    4. **JavaScript**: Check for JavaScript errors in console
    5. **Permissions**: Verify API key has correct permissions
  </Accordion>

  <Accordion title="Tracking pixels aren't firing" data-faq-item="Tracking pixels aren't firing">
    Check:

    1. **Pixel URL**: Verify pixel URL is correct
    2. **Network**: Check if pixel request is being sent
    3. **Ad Blockers**: Disable ad blockers and test
    4. **CORS**: Verify CORS headers are correct
    5. **Timing**: Ensure pixel fires at correct time
  </Accordion>

  <Accordion title="Performance is slow" data-faq-item="Performance is slow">
    Optimize:

    1. **Cache Results**: Cache recommendations for 5-10 minutes
    2. **Lazy Load**: Load SDK only when needed
    3. **Compress**: Enable gzip compression
    4. **CDN**: Use CDN for static assets
    5. **Monitor**: Track API response times
  </Accordion>
</AccordionGroup>

***

## Additional Resources

<CardGroup cols={2}>
  <Card title="React SDK" icon="react" href="/ui-sdk/installation">
    React SDK installation and setup
  </Card>

  <Card title="Weave Format" icon="layout-grid" href="/platforms/weave-ad-format">
    Weave format integration guide
  </Card>

  <Card title="Tail Format" icon="link" href="/platforms/tail-format">
    Tail format integration guide
  </Card>
</CardGroup>