insights

Middleware for setting the user token and sending click and conversion events to the Insights API.

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

const middleware = createInsightsMiddleware({
  // Optional parameters
  insightsClient?: InsightsClient | null,
  insightsInitParams?: object,
  onEvent?: function,
})

Import

JavaScript

import { createInsightsMiddleware } from "instantsearch.js/es/middlewares";

About this middleware

You can use <InstantSearch insights={true}> instead of setting up the Insights middleware yourself.

The createInsightsMiddleware creates an insights middleware to help you achieve the following:

1. Set the userToken for insights purposes (Analytics, Personalization, etc.).
2. Automatically send events from built-in widgets. You can turn this off if needed.
3. Send events from your own custom widgets.

Requirements

• search-insights v1.6.2 or later.

See also: Send click and conversion events with React InstantSearch

Examples

JavaScript

import { createInsightsMiddleware } from "instantsearch.js/es/middlewares";
import { useInstantSearch } from "react-instantsearch";
import { useLayoutEffect } from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";

function InsightsMiddleware() {
  const { addMiddlewares } = useInstantSearch();

  useLayoutEffect(() => {
    const middleware = createInsightsMiddleware({
      insightsClient: window.aa,
    });

    return addMiddlewares(middleware);
  }, [addMiddlewares]);

  return null;
}

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      {/* ... */}
      <InsightsMiddleware />
    </InstantSearch>
  );
}

Options

insightsClient · InsightsClient | null

The Insights client is used to send events. It synchronizes the user token between search and analytics calls.

To disable userToken synchronization and automatic event sending, set this to null.

JavaScript

const middleware = createInsightsMiddleware({
  insightsClient: aa,
});

const userToken = // Get the user token (synchronously or asynchronously).
  // The `insights` middleware receives a notification
  // and attaches the `userToken` to search calls onwards.
  aa("setUserToken", userToken);

insightsInitParams · object

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 userToken. 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.

You can set an authenticated user token and a user token in insightsInitParams. Both tokens are passed to the Insights API for sending events. If both are set, InstantSearch uses the authenticated user token for search queries.

Cookie

createInsightsMiddleware({
  insightsInitParams: {
    useCookie: true,
  },
});

onEvent · (event: InsightsEvent, aa: null | InsightsClient) => void · default: "undefined"

By default, the middleware sends events to Algolia using the provided insightsClient. You can also control events and send them yourself by implementing an onEvent method for the middleware to call instead. This method lets you access data and filter or modify the payload. You can also use it to send events to third-party trackers.

If you want to use onEvent to send events to third-party trackers, but don’t want to send them to Algolia, you can set insightsClient to null, and you don’t need the search-insights library in your application.

Show event properties

event.insightsMethod · string

The Insights method, such as, 'viewedObjectIDs', 'clickedObjectIDsAfterSearch'. For more information, see the Insights API reference.

event.payload · [key: string]: any

Event payload.

event.widgetType · string

Widget type given by connectors, such as 'ais.refinementList or 'ais.hits.

event.eventType · string

Event type, such as 'view', 'click', 'conversion', or anything else if you customized it.

JavaScript

createInsightsMiddleware({
  insightsClient: window.aa,
  onEvent: (event, aa) => {
    const { insightsMethod, payload, widgetType, eventType } = event;

    // Send the event to Algolia
    if (insightsMethod) {
      aa(insightsMethod, payload);
    }

    // Send the event to a third-party tracker
    if (widgetType === "ais.hits" && eventType === "click") {
      thirdPartyTracker.send("Product Clicked", payload);
    }
  },
});

Custom events

Many InstantSearch connectors expose the sendEvent method, which you can use for sending custom events from your custom widgets.

Here’s a list of connectors that expose sendEvent and they’re exposed at the default slot of corresponding React InstantSearch components.

• useHierarchicalMenu
• useHits
• useInfiniteHits
• useMenu
• useNumericMenu
• useRange
• useRefinementList
• useToggleRefinement

JavaScript

function Hits() {
  const { items, sendEvent } = useHits();

  return (
    <ol>
      {items.map((item) => (
        <li key={item.objectID}>
          <p>{item.name}</p>
          <button
            type="button"
            onClick={() => sendEvent("click", item, "Item Starred")}
          >
            Star
          </button>

          <button
            type="button"
            onClick={() => sendEvent("conversion", item, "Item Ordered")}
          >
            Order
          </button>
        </li>
      ))}
    </ol>
  );
}