UI Libraries / Autocomplete / createAlgoliaInsightsPlugin

createAlgoliaInsightsPlugin

The Algolia Insights plugin automatically sends click and conversion events to the Algolia Insights API whenever a user interacts with the autocomplete.

Installation

First, you need to install the plugin.

1
2
3
yarn add @algolia/autocomplete-plugin-algolia-insights
# or
npm install @algolia/autocomplete-plugin-algolia-insights

Then import it in your project:

1
import { createAlgoliaInsightsPlugin } from '@algolia/autocomplete-plugin-algolia-insights';

If you don’t use a package manager, you can use the HTML script element:

1
2
3
4
5
6
<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-plugin-algolia-insights"></script>
<script>
  const { createAlgoliaInsightsPlugin } = window[
    '@algolia/autocomplete-plugin-algolia-insights'
  ];
</script>

Examples

This example uses the plugin within autocomplete-js, along with the algoliasearch API client and Search Insights library.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import algoliasearch from 'algoliasearch/lite';
import { autocomplete } from '@algolia/autocomplete-js';
import { createAlgoliaInsightsPlugin } from '@algolia/autocomplete-plugin-algolia-insights';
import insightsClient from 'search-insights';

const appId = 'latency';
const apiKey = '6be0576ff61c053d5f9a3225e2a90f76';
const searchClient = algoliasearch(appId, apiKey);
insightsClient('init', { appId, apiKey });

const algoliaInsightsPlugin = createAlgoliaInsightsPlugin({ insightsClient });

autocomplete({
  container: '#autocomplete',
  plugins: [algoliaInsightsPlugin],
});

If you’re using search-insights >= 2.0.0, the library no longer sets an anonymous token automatically. You can either set the user token, or re-enable the cookie-based anonymous token.

1
2
3
4
5
6
insightsClient('init', { appId, apiKey });
insightsClient('setUserToken', yourUserToken);

// or

insightsClient('init', { appId, apiKey, useCookie: true });

The plugin exposes hooks to let you inject custom logic in the lifecycle: onItemsChange, onSelect, and onActive. You can use them to either customize the events sent to Algolia, or plug additional behavior.

For example, if you have several search experiences on your site, you can customize the event name to identify where the events came from:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
const algoliaInsightsPlugin = createAlgoliaInsightsPlugin({
  insightsClient,
  onItemsChange({ insights, insightsEvents }) {
    const events = insightsEvents.map((insightsEvent) => ({
      ...insightsEvent,
      eventName: 'Product Viewed from Autocomplete',
    }));
    insights.viewedObjectIDs(...events);
  },
  onSelect({ insights, insightsEvents }) {
    const events = insightsEvents.map((insightsEvent) => ({
      ...insightsEvent,
      eventName: 'Product Selected from Autocomplete',
    }));
    insights.clickedObjectIDsAfterSearch(...events);
  },
});

If you’re using another analytics provider along with Algolia Insights, you can leverage these hooks to send them events as well. For example, you can send Segment events:

1
2
3
4
5
6
7
8
9
10
const algoliaInsightsPlugin = createAlgoliaInsightsPlugin({
  insightsClient,
  onActive({ insights, insightsEvents }) {
    insightsEvents.forEach((insightsEvent) => {
      // Assuming you've initialized the Segment script
      // and identified the current user already
      analytics.track('Product Browsed from Autocomplete', insightsEvent);
    });
  },
});

If you send events to other analytics providers, it might make sense to create a dedicated plugin.

Parameters

insightsClient
type: InsightsClient
Required

The initialized Search Insights client.

onItemsChange
type: (params: OnItemsChangeParams) => void

Hook to send an Insights event whenever the items change.

By default, it sends a viewedObjectIDs event.

In as-you-type experiences, items change as the user types. This hook is debounced every 400 ms to reflect actual items that users notice and avoid generating too many events for items matching “in progress” queries.

1
2
3
4
5
type OnItemsChangeParams = {
  insights: InsightsApi;
  insightsEvents: ViewedObjectIDsParams[];
  state: AutocompleteState<any>;
};
onSelect
type: (params: OnSelectParams) => void

Hook to send an Insights event whenever an item is selected.

By default, it sends a clickedObjectIDsAfterSearch event.

1
2
3
4
5
6
7
type OnSelectParams = {
  insights: InsightsApi;
  insightsEvents: ClickedObjectIDsAfterSearchParams[];
  item: AlgoliaInsightsHit;
  state: AutocompleteState<any>;
  event: any;
};
onActive
type: (params: OnActiveParams) => void

Hook to send an Insights event whenever an item is active.

By default, it doesn’t send any events.

1
2
3
4
5
6
7
type OnActiveParams = {
  insights: InsightsApi;
  insightsEvents: ClickedObjectIDsAfterSearchParams[];
  item: AlgoliaInsightsHit;
  state: AutocompleteState<any>;
  event: any;
};

Did you find this page helpful?