Skip to main content
DocSearch integrates with Algolia Insights to provide powerful analytics on search behavior, click patterns, and user interactions.

​
Overview

Algolia Insights enables you to:
  • Track search queries and click-through rates
  • Measure search relevance and effectiveness
  • Understand which results users interact with
  • Optimize your search experience based on user behavior
  • Send custom analytics events
Algolia Insights is built on the autocomplete-plugin-algolia-insights package, which integrates seamlessly with DocSearch.

​
Setup

To enable analytics, pass the insights configuration to DocSearch: 
import { DocSearch } from '@docsearch/react';
import { createInsightsClient } from '@algolia/autocomplete-plugin-algolia-insights';
import insightsClient from 'search-insights';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      insights={true}
    />
  );
}
Setting insights={true} enables basic click analytics. For advanced use cases, you can pass a custom insights configuration.

​
How It Works

When insights are enabled, DocSearch automatically:
  1. Adds clickAnalytics parameter to search requests
  2. Includes userToken to identify anonymous users
  3. Tracks clickedObjectIDsAfterSearch events when users select results
  4. Sends events to Algolia Insights API

​
Search Request Changes

With insights enabled, search parameters include: 
{
  query: 'search term',
  clickAnalytics: true,
  userToken: 'anonymous-user-id',
  // ... other parameters
}

​
Click Event Tracking

When a user clicks a search result: 
const insightsClickParams = {
  eventName: 'Item Selected',
  index: 'YOUR_INDEX_NAME',
  items: [hit],
  positions: [position],
  queryID: hit.__autocomplete_queryID,
};

state.context.algoliaInsightsPlugin.insights
  .clickedObjectIDsAfterSearch(insightsClickParams);

​
Advanced Configuration

For more control over insights tracking, pass a custom configuration: 
import { DocSearch } from '@docsearch/react';
import aa from 'search-insights';

// Initialize insights client
aa('init', {
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_API_KEY',
  useCookie: true,
});

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      insights={{
        insightsClient: aa,
        onSelect: (event) => {
          const { item, state } = event;
          
          // Custom analytics logic
          console.log('User selected:', item);
          
          // Send to your own analytics
          gtag('event', 'search_result_click', {
            search_term: state.query,
            result_url: item.url,
          });
        },
      }}
    />
  );
}

​
Event Types

DocSearch tracks these Algolia Insights events:

​
Click Events

Event Name: Item Selected Triggered when a user clicks on a search result. 
{
  eventName: 'Item Selected',
  index: 'docs',
  objectIDs: ['unique-hit-id'],
  positions: [1],
  queryID: 'query-id-from-algolia',
}

​
Search Events

Automatically tracked with clickAnalytics: true in search parameters.

​
User Token Management

Algolia Insights uses user tokens to track individual users across sessions: 
import aa from 'search-insights';

// Set a custom user token
aa('setUserToken', 'user-12345');

// Or use anonymous token (default)
aa('setUserToken', aa.getAnonymousUserToken());

​
Custom User Token

If you have authenticated users, set their user ID: 
import { DocSearch } from '@docsearch/react';
import aa from 'search-insights';
import { useEffect } from 'react';

function App({ user }) {
  useEffect(() => {
    if (user?.id) {
      aa('setUserToken', user.id);
    }
  }, [user]);

  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      insights={true}
    />
  );
}

​
Custom Analytics Integration

Combine Algolia Insights with your existing analytics platform:

​
Google Analytics 4

import { DocSearch } from '@docsearch/react';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      insights={{
        onSelect: ({ item, state }) => {
          // Send to GA4
          gtag('event', 'search_result_click', {
            search_term: state.query,
            item_id: item.objectID,
            item_name: item.hierarchy.lvl1,
            item_url: item.url,
          });
        },
        onActive: ({ item, state }) => {
          // Track result hover/keyboard navigation
          gtag('event', 'search_result_view', {
            search_term: state.query,
            item_id: item.objectID,
          });
        },
      }}
    />
  );
}

​
Mixpanel

import mixpanel from 'mixpanel-browser';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      insights={{
        onSelect: ({ item, state }) => {
          mixpanel.track('Search Result Clicked', {
            query: state.query,
            resultId: item.objectID,
            resultTitle: item.hierarchy.lvl1,
            resultUrl: item.url,
            position: item.__autocomplete_id,
          });
        },
      }}
    />
  );
}

​
Segment

import analytics from '@segment/analytics-next';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      insights={{
        onSelect: ({ item, state }) => {
          analytics.track('Search Result Selected', {
            query: state.query,
            objectID: item.objectID,
            title: item.hierarchy.lvl1,
            url: item.url,
          });
        },
      }}
    />
  );
}

​
Implementation Details

Here’s how DocSearch implements insights tracking internally:

​
Enable Click Analytics

const insightsActive = insights;

if (insightsActive) {
  searchParams = {
    ...searchParams,
    clickAnalytics: true,
  };
}

​
Track Click Events

const onItemClick = React.useCallback(
  (item: InternalDocSearchHit) => {
    if (!state.context.algoliaInsightsPlugin || !item.__autocomplete_id) {
      return;
    }

    const insightsItem = item as AlgoliaInsightsHit;

    const insightsClickParams = {
      eventName: 'Item Selected',
      index: insightsItem.__autocomplete_indexName,
      items: [insightsItem],
      positions: [item.__autocomplete_id],
      queryID: insightsItem.__autocomplete_queryID,
    };

    state.context.algoliaInsightsPlugin.insights
      .clickedObjectIDsAfterSearch(insightsClickParams);
  },
  [state.context.algoliaInsightsPlugin],
);

​
Initialize Autocomplete with Insights

const autocomplete = createAutocomplete({
  id: 'docsearch',
  insights: Boolean(insights),
  // ... other options
});

​
Viewing Analytics Data

Access your search analytics in the Algolia dashboard:
1

Navigate to Analytics

Go to your Algolia dashboard and select your index
2

View Search Analytics

Click on “Analytics” in the sidebar to see:
  • Top searches
  • Search with no results
  • Click-through rates
  • Popular results
3

Enable Click Analytics

Make sure “Click Analytics” is enabled in your index settings

​
Privacy Considerations

When using insights, consider privacy regulations like GDPR and CCPA:
  • User tokens should be anonymized or hashed
  • Provide opt-out mechanisms for tracking
  • Include analytics disclosure in your privacy policy
  • Consider cookie consent requirements
import aa from 'search-insights';

aa('init', {
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_API_KEY',
  useCookie: false, // Disable cookies
});

​
Conditional Tracking

function App({ hasAnalyticsConsent }) {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      insights={hasAnalyticsConsent}
    />
  );
}

​
Troubleshooting

​
Events Not Showing Up

1

Verify insights enabled

Check that insights={true} or insights object is passed to DocSearch
2

Check API key permissions

Ensure your API key has search and analytics permissions
3

Verify queryID

Click events require a queryID from search results
4

Check network requests

Look for requests to insights.algolia.io in browser DevTools

​
Click Analytics Not Working

Make sure clickAnalytics is enabled in your search parameters: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indices={[
    {
      name: 'YOUR_INDEX_NAME',
      searchParameters: {
        clickAnalytics: true,
      },
    },
  ]}
  insights={true}
/>

​
Best Practices

1

Always enable insights

Enable insights from day one to build a baseline of analytics data.
2

Use consistent user tokens

For authenticated users, use their user ID as the token for accurate tracking across sessions.
3

Combine with custom analytics

Use both Algolia Insights and your existing analytics platform for comprehensive tracking.
4

Monitor search quality

Regularly review analytics to identify searches with low click-through rates or no results.
5

Respect user privacy

Implement proper consent mechanisms and provide opt-out options.
6

Test in development

Test insights events in development using browser DevTools to verify they’re being sent correctly.

​
TypeScript Interface

import type { AutocompleteOptions } from '@algolia/autocomplete-core';
import type { InternalDocSearchHit } from './types';

export interface DocSearchProps {
  /**
   * Insights client integration options to send analytics events.
   */
  insights?: AutocompleteOptions<InternalDocSearchHit>['insights'];
  // ... other props
}
The insights prop accepts the same configuration as the Autocomplete Insights plugin, giving you full control over analytics behavior.

Build docs developers (and LLMs) love

Get started for freeTalk to us