Atri AI Documentation

Overview

Our embeddable search widgets provide the fastest way to add AI-powered search to any website. Using simple script tags, you can deploy professional search interfaces without any complex setup or framework dependencies. Choose between Beacon and Horizon templates to match your site's search needs.

Configuration Parameters

Both search widgets support the same core set of parameters for consistent configuration across deployment methods.

Required Parameters

data-project-id / projectIdstring

Your project-specific identifier for the AI Search service. Required for all widget functionality.

Optional Parameters

data-consumer-id / consumerIdstring

Unique identifier for the user. Used for authenticated search requests and maintaining user context across sessions.

data-hmac-signature / hmacSignaturestring

HMAC signature for secure consumer authentication. Generated server-side using your project's search API key.

Horizon-Specific Parameters

data-variant / variant'icon' | 'bar'

Display variant for the Horizon widget. 'icon' shows a compact search button, 'bar' shows a collapsed search bar.

data-collapsed-bar-width / collapsedBarWidthstring

Width of the collapsed search bar when using 'bar' variant. Default is '200px'.

Parameter Notes

• For authenticated search requests, provide both consumerId and hmacSignature.
• If the consumerId and hmacSignature are not provided, cookies are used to create a temporary anonymous consumerId.
• The HMAC signature is needed to verify the identity of the consumer. It should be generated in the backend by passing the consumer ID and your project's search API key to the API route /hmacSignature.
• Never expose your API key in client-side requests. Always generate HMAC signatures server-side.
• Both search widgets support keyword-based and AI-powered hybrid search modes that users can toggle between.

Implementation Guide

Beacon Widget Implementation

The Beacon widget requires a container element and programmatic mounting. It provides inline search with event callbacks using which you can handle search results as per your application requirements:

Step 1: Create a Container

Add a container element where you want the search interface to appear:

<div id="search-widget-container" style="width: 100%; min-height: 400px;"></div>

Step 2: Load and Mount the Widget

Add the script to load and mount the Beacon widget:

<script>
const script = document.createElement('script');
script.src = 'https://unpkg.com/atri-ai-search-widget-beacon@latest/dist/widget.js';
script.onload = () => {
  const container = document.getElementById('search-widget-container');
  window.AtriSearchBeacon?.mount({
    projectId: 'your-project-id',
    consumerId: 'optional-consumer-id',
    hmacSignature: 'optional-hmac-signature',
    target: container
  });
};
document.head.appendChild(script);

// Listen for search events
window.addEventListener('atriSearchResults', (event) => {
  console.log('Search results:', event.detail.results);
  console.log('Project ID:', event.detail.projectId);
});

window.addEventListener('atriSearchStart', (event) => {
  console.log('Search started at:', event.detail.timestamp);
  console.log('Project ID:', event.detail.projectId);
});
</script>

Complete Implementation Example

Here's a complete HTML page example with Beacon widget:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>AI Search Integration - Beacon</title>
</head>
<body>
    <h1>My Website with AI Search</h1>
    
    <!-- Container for the Beacon widget -->
    <div id="search-widget-container" style="width: 100%; min-height: 400px; border: 1px solid #ccc;"></div>
    
    <!-- Load and mount the widget -->
    <script>
    const script = document.createElement('script');
    script.src = 'https://unpkg.com/atri-ai-search-widget-beacon@latest/dist/widget.js';
    script.onload = () => {
      const container = document.getElementById('search-widget-container');
      window.AtriSearchBeacon?.mount({
        projectId: 'your-project-id',
        consumerId: 'user_12345',
        hmacSignature: 'generated-hmac-signature',
        target: container
      });
    };
    document.head.appendChild(script);
    </script>
</body>
</html>

Horizon Widget Implementation

The Horizon widget requires a container element and programmatic mounting. It provides modal-based search with configurable display variants:

Step 1: Create a Container

Add a container element where you want the search trigger to appear:

<div id="search-horizon-container" style="width: fit-content;"></div>

Step 2: Load and Mount the Widget

Add the script to load and mount the Horizon widget:

<script>
const script = document.createElement('script');
script.src = 'https://unpkg.com/atri-ai-search-template-horizon@latest/dist/widget.js';
script.onload = () => {
  const container = document.getElementById('search-horizon-container');
  window.AtriSearchHorizon?.mount({
    projectId: 'your-project-id',
    consumerId: 'optional-consumer-id',
    hmacSignature: 'optional-hmac-signature',
    target: container,
    variant: 'bar',
    collapsedBarWidth: '250px'
  });
};
document.head.appendChild(script);

// Optionally: Listen for search events
window.addEventListener('atriHorizonSearchResults', (event) => {
  console.log('Search results:', event.detail.results);
  console.log('Project ID:', event.detail.projectId);
});

window.addEventListener('atriHorizonSearchStart', (event) => {
  console.log('Search started at:', event.detail.timestamp);
  console.log('Project ID:', event.detail.projectId);
});
</script>

Complete Implementation Example

Here's a complete HTML page example with Horizon widget:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>AI Search Integration - Horizon</title>
</head>
<body>
    <header style="display: flex; justify-content: space-between; align-items: center; padding: 1rem;">
        <h1>My Website</h1>
        
        <!-- Container for the Horizon widget in header -->
        <div id="search-horizon-container"></div>
    </header>
    
    <main>
        <p>Your website content here...</p>
    </main>
    
    <!-- Load and mount the widget -->
    <script>
    const script = document.createElement('script');
    script.src = 'https://unpkg.com/atri-ai-search-template-horizon@latest/dist/widget.js';
    script.onload = () => {
      const container = document.getElementById('search-horizon-container');
      window.AtriSearchHorizon?.mount({
        projectId: 'your-project-id',
        consumerId: 'user_12345',
        hmacSignature: 'generated-hmac-signature',
        target: container,
        variant: 'bar',
        collapsedBarWidth: '200px'
      });
    };
    document.head.appendChild(script);
    </script>
</body>
</html>

Alternative: Data Attributes Implementation

For simpler integration, the Horizon widget supports auto-mounting with data attributes:

Horizon Auto-Mount

<div id="my-horizon-container"></div>

<script 
  src="https://unpkg.com/atri-ai-search-template-horizon@latest/dist/widget.js"
  data-project-id="your-project-id"
  data-consumer-id="optional-consumer-id"
  data-hmac-signature="optional-hmac-signature"
  data-target="#my-horizon-container"
  data-variant="bar"
  data-collapsed-bar-width="200px">
</script>

Note: The Beacon widget can also be auto-mounted but it is not recommended for production use since the consuming application will need to handle search events separately.

Implementation Best Practices

• Loading Performance: Use the async attribute on script tags
• Error Handling: Always check if window.AtriSearchBeacon or window.AtriSearchHorizon exists before calling methods
• User Identification: Use consistent consumerId values to maintain user search context and analytics
• Container Sizing: Ensure Beacon widget containers have adequate space (minimum 300px width recommended)
• Event Management: Remove event listeners when widgets are unmounted to prevent memory leaks

Security Best Practices

• Never expose your Search API key in client-side code or browser requests
• Generate HMAC signatures server-side only using your secure API key
• Use HTTPS for all API calls and widget deployments
• Validate consumer IDs on your backend before generating HMAC signatures

Platform-Specific Integration

WordPress

Add widget scripts to your theme's footer.php file or use a custom HTML block. Consider using a plugin to manage HMAC generation for authenticated users.

Shopify

Add scripts to your theme's theme.liquid file. Use Shopify's customer ID as consumerId for authenticated search. Horizon widget works well in header areas.

Squarespace

Use Code Injection in Settings to add scripts. Beacon widget works well for dedicated search pages, while Horizon is ideal for site-wide search.

Static HTML

Add scripts directly to your HTML files. For dynamic users, pair with a backend service for HMAC generation. Both widgets work seamlessly.

Widget Configuration Guide

When to Use Beacon Widget

• Dedicated search pages or sections
• When you need custom result display logic
• Integration with existing result components
• Advanced search analytics requirements
• Custom autocomplete handling

When to Use Horizon Widget

• Site-wide search functionality
• Header or navigation integration
• Minimal UI footprint required
• Self-contained search experience
• Quick deployment without custom logic

Troubleshooting

Widget not appearing: Check browser console for errors, verify projectId is correct, and ensure scripts are loaded properly.

Authentication errors: Verify HMAC signature is generated correctly server-side and consumerId matches the signature.

Search not working: Ensure your project has a properly configured search index with indexed content.

Events not firing: Check that event listeners are attached before the widget is mounted and used.

Beacon container issues: Verify container element exists and has adequate dimensions before mounting.

Horizon variant issues: Ensure variant parameter matches expected values ('icon' or 'bar') and collapsedBarWidth is valid CSS.

Embeddable Widget Integration

Overview

Configuration Parameters

Required Parameters

Optional Parameters

Horizon-Specific Parameters

Parameter Notes

Implementation Guide

Beacon Widget Implementation

Step 1: Create a Container

Step 2: Load and Mount the Widget

Complete Implementation Example

Horizon Widget Implementation

Step 1: Create a Container

Step 2: Load and Mount the Widget

Complete Implementation Example

Alternative: Data Attributes Implementation

Horizon Auto-Mount

Implementation Best Practices

Security Best Practices

Platform-Specific Integration

WordPress

Shopify

Squarespace

Static HTML

Widget Configuration Guide

When to Use Beacon Widget

When to Use Horizon Widget

Troubleshooting