Atri AI Logo
SupportSales

How to Integrate AI Search Using Pre-Built Templates

Step-by-step guide to integrate AI search functionality into your application using our pre-built React components and JavaScript widgets.

Choose Your Integration Method

We offer two pre-built template types, each available as React components and JavaScript widgets:

Beacon Template

Inline search component for dedicated search pages and sections

Best for: Dedicated search pages, custom result display, advanced search analytics

Horizon Template

Modal-based search interface with compact trigger variants

Best for: Site-wide search, navigation integration, minimal UI footprint

React Component Integration

For React applications

Step 1: Install the Package

Add the AI Search templates package to your React project.

  • Run the npm install command to add the package
npm install @atri-ai/templates

Step 2: Import Components and Styles

Import the required component and CSS styles in your React file.

  • Import the CSS file first to ensure proper styling
  • Import the specific template component you want to use
  • Both Beacon and Horizon templates are available from the same package
import '@atri-ai/templates/styles.css';
import { SearchTemplateBeacon, SearchTemplateHorizon } from '@atri-ai/templates';

Step 3: Configure Your Component

Add the component to your JSX with required configuration parameters.

  • Provide your project ID (required for all integrations)
  • Add consumer ID and HMAC signature for authenticated users
  • Configure callbacks for Beacon template to handle search results
  • Set display variant for Horizon template (icon or bar)
  • Leave optional parameters empty for anonymous sessions
// Beacon Template - Inline search with callbacks
<SearchTemplateBeacon 
projectId="your-project-id"
consumerId="user_12345"
hmacSignature="hmac-signature-for-the-consumer-id"
onSearchResults={(results) => {
  console.log('Search results:', results);
  // Handle results in your application
}}
onSearchStart={() => {
  console.log('Search started');
  // Show loading state
}}
/>
// Horizon Template - Modal search interface  
<SearchTemplateHorizon 
projectId="your-project-id"
consumerId="user_12345"
hmacSignature="hmac-signature-for-the-consumer-id"
variant="bar"
collapsedBarWidth="250px"
/>
// Anonymous session
<SearchTemplateBeacon 
projectId="your-project-id"
onSearchResults={(results) => {
  // Handle anonymous search results
}}
/>
// Horizon with icon variant
<SearchTemplateHorizon 
projectId="your-project-id"
variant="icon"
/>

Step 4: Generate HMAC Signatures (For Authenticated Users)

Set up server-side HMAC generation for user authentication.

  • Create a server-side API route to generate HMAC signatures
  • Use your project's search API key (never expose this client-side)
  • Call the HMAC generation endpoint before rendering the component
  • Pass the generated signature to the component
// Example: Generate HMAC signature server-side
const response = await fetch('/api/generateHmac', {
method: 'POST',
body: JSON.stringify({ consumerId: 'user_12345' }),
headers: { 'Content-Type': 'application/json' }
});
const { hmacSignature } = await response.json();

// Use in component
<SearchTemplateBeacon 
projectId="your-project-id"
consumerId="user_12345"
hmacSignature={hmacSignature}
onSearchResults={(results) => handleResults(results)}
/>

JavaScript Widget Integration

For any website or web application

Step 1: Choose Your Template Type

Select between Beacon or Horizon widget based on your needs.

  • Beacon widget: Requires a container element - you control the placement and result handling
  • Horizon widget: Requires a container element for the trigger - modal opens automatically
  • Both widgets support the same authentication parameters

Step 2A: Beacon Widget Implementation

Create a container and programmatically mount the Beacon widget.

  • Add a container div with defined dimensions where you want the search interface
  • Load the Beacon widget script dynamically
  • Call the mount function with your configuration
  • Listen for search events to handle results
  • Widget renders inline search interface inside your container
<!-- Container for the widget -->
<div id="search-widget-container" style="width: 100%; min-height: 400px;"></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: '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);
});
</script>

Step 2B: Horizon Widget Implementation

Create a container and programmatically mount the Horizon widget.

  • Add a container element where you want the search trigger to appear
  • Load the Horizon widget script dynamically
  • Call the mount function with your configuration and variant settings
  • Widget renders trigger button/bar that opens modal search interface
<!-- Container for the trigger -->
<div id="search-horizon-container"></div>

<!-- 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: 'optional-consumer-id',
  hmacSignature: 'optional-hmac-signature',
  target: container,
  variant: 'bar',
  collapsedBarWidth: '250px'
});
};
document.head.appendChild(script);

// Optional: Listen for search events
window.addEventListener('atriHorizonSearchResults', (event) => {
console.log('Search results:', event.detail.results);
});
</script>

Step 3: Handle Authentication (For Known Users)

Generate HMAC signatures server-side for authenticated user sessions.

  • Create a backend endpoint that generates HMAC signatures
  • Call this endpoint to get signatures for your users
  • Never generate HMAC signatures client-side
  • Use the signature in your widget configuration
// Example: Fetch HMAC signature and configure widget
fetch('/api/generateHmac', {
method: 'POST',
body: JSON.stringify({ consumerId: 'user_12345' }),
headers: { 'Content-Type': 'application/json' }
})
.then(response => response.json())
.then(data => {
// For Beacon widget
const container = document.getElementById('search-widget-container');
window.AtriSearchBeacon?.mount({
  projectId: 'your-project-id',
  consumerId: 'user_12345',
  hmacSignature: data.hmacSignature,
  target: container
});

// For Horizon widget
const horizonContainer = document.getElementById('search-horizon-container');
window.AtriSearchHorizon?.mount({
  projectId: 'your-project-id',
  consumerId: 'user_12345',
  hmacSignature: data.hmacSignature,
  target: horizonContainer,
  variant: 'bar'
});
});

Authentication Parameters Guide

Understanding when and how to use different authentication parameters:

Authenticated Search Session

For logged-in users with personalized search

Parameters:consumerId + hmacSignature

Provide both parameters to create authenticated search sessions with user context

Anonymous Search Session

For guest users or temporary interactions

Parameters:projectId only

Only provide project ID - system creates temporary anonymous session using cookies

Template Customization Options

Beacon Template Customization

Theme Color

Primary brand color for search interface accents and highlights

Configure in your project dashboard under Template Settings

Placeholder Text

Custom text displayed in the search input when empty

Set in project dashboard Template Settings

Max Autocomplete Suggestions

Number of autocomplete suggestions to display (1-15)

Configure in project dashboard under Template Settings

Horizon Template Customization

Theme Color

Primary brand color for buttons, links, and focus states

Configure in your project dashboard under Template Settings

Placeholder Text

Custom text displayed in the search input when empty

Set in project dashboard Template Settings

Result Field Mappings

Configure which data fields to display in search results

Map category, primary, secondary, metric, and link fields in dashboard

Display Variant

Choose between 'icon' (compact button) or 'bar' (collapsed search bar)

Set via variant parameter in component/widget configuration

Security Best Practices

  • • Never expose your search API key in client-side code
  • • Always generate HMAC signatures server-side using the /hmacSignature API endpoint
  • • Use HTTPS for all API calls and widget deployments
  • • Validate consumer IDs on your backend before generating HMAC signatures

Common Issues and Solutions

Widget not appearing

Check browser console for errors, verify project ID is correct, ensure script loads properly and container exists

Authentication errors

Verify HMAC signature is generated correctly server-side and consumer ID matches the signature

Styles not loading (React)

Ensure you've imported '@atri-ai/templates/styles.css' before using components

Search not working

Ensure your project has a properly configured search index with indexed content

Beacon events not firing

Check that event listeners are attached before widget is mounted and onSearchResults callback is provided

Horizon container issues

Verify container element exists and variant parameter matches expected values ('icon' or 'bar')

Next Steps

After completing the integration, you can:

  • Customize your template appearance and field mappings in the project dashboard
  • Configure search index and content sources for optimal results
  • Explore advanced search features like filters and faceted search
  • Explore the full API reference for advanced features