createAlgoliaInsightsPlugin

A function to create a new Algolia Insights plugin for Autocomplete that lets you send click and conversion events to the Insights API.

Autocomplete is also available as an experimental widget in InstantSearch, making it easier to integrate into your search experience. To learn more, see the API reference for InstantSearch.js or React InstantSearch.

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

Starting from version 1.9.2 of Autocomplete, you no longer need to use this plugin directly. Instead, use the insights option of the autocomplete function.

See also:

• Send click and conversion events
• Get started with click and conversion events

Use the insights option

This option is available starting from v1.9.2.

Instead of using this plugin, you can set up events using the insights option of the autocomplete function.

JavaScript

import { autocomplete } from "@algolia/autocomplete-js";

autocomplete({
  container: "#autocomplete",
  insights: true,
});

// or with options

autocomplete({
  container: "#autocomplete",
  insights: {
    // ...
  },
});

If you don’t pass an insightsClient, it will be automatically detected from the window object, or downloaded from the jsDelivr CDN.

If you are using the insights option you don’t need to follow the rest of this guide.

Installation

First, you need to install the plugin.

npm

npm install @algolia/autocomplete-plugin-algolia-insights

Then import it in your project:

JavaScript

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

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

HTML

<script
  src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-plugin-algolia-insights@1.19.4/dist/umd/index.production.js"
  integrity="5jDabjvO1Afs9TotfK81SjT/TUkEX3XZGpfSYTZKJK4="
  crossorigin="anonymous"
></script>
<script>
  const { createAlgoliaInsightsPlugin } =
    window["@algolia/autocomplete-plugin-algolia-insights"];
</script>

If you don’t pass an insightsClient, it will be automatically detected from the window object, or downloaded from the jsDelivr CDN.

Examples

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

JavaScript

import { liteClient as 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],
});

To identify users consistently, it’s best if you set your own userToken with setUserToken, for example, for authenticated users. The search-insights library can create anonymous user tokens and store them in cookie. To use cookie-based anonymous tokens, initialize the library with useCookie set to true:

JavaScript

insightsClient("init", { appId, apiKey });
insightsClient("setUserToken", yourUserToken);

// or

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

In older versions of the search-insights library (earlier than version 2.0), cookie-based anonymous tokens are on by default.

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:

JavaScript

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 use these hooks to send events as well. For example, you can send Segment events:

JavaScript

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 · InsightsClient

The Search Insights client. If not provided, the plugin will use the global window.aa object, or fetch it from the jsDelivr CDN.

insightsInitParams · object · since: v1.14.0

Insights parameters to forward to the Insights client’s init method.

With search-insights >= v1.7.0 and < 2.0.0, the Insights client accepts useCookie and userToken parameters in the init method. You can pass useCookie: false to prevent the usage of cookies to store an anonymous user token. You can also pass a custom userToken while creating insights middleware, if you have one.

With search-insights >= 2.0.0, the default value of useCookie is false.

onItemsChange · (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 users type. 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.

TypeScript

type OnItemsChangeParams = {
  insights: InsightsApi;
  insightsEvents: ViewedObjectIDsParams[];
  state: AutocompleteState<any>;
};

onSelect · (params: OnSelectParams) => void

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

By default, it sends a clickedObjectIDsAfterSearch event.

TypeScript

type OnSelectParams = {
  insights: InsightsApi;
  insightsEvents: ClickedObjectIDsAfterSearchParams[];
  item: AlgoliaInsightsHit;
  state: AutocompleteState<any>;
  event: any;
};

onActive · (params: OnActiveParams) => void

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

By default, it doesn’t send any events.

TypeScript

type OnActiveParams = {
  insights: InsightsApi;
  insightsEvents: ClickedObjectIDsAfterSearchParams[];
  item: AlgoliaInsightsHit;
  state: AutocompleteState<any>;
  event: any;
};