insights - Algolia

Signature

createInsightsMiddleware({
  insightsClient: null | InsightsClient,
  insightsInitParams?: object,
  onEvent?: (event: InsightsEvent, aa: null | InsightsClient) => void,
});

Import

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

const { createInsightsMiddleware } = instantsearch.middlewares;
// or directly use instantsearch.middlewares.createInsightsMiddleware()

Starting from v4.55.0, you can use the insights option instead of setting up the Insights middleware yourself.

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

Set the userToken for insights purposes (Click Analytics, Personalization, etc.)
Automatically send events from built-in widgets (you can turn this off)
Lets you send events from your own custom widgets

Requirements

search-insights v1.6.2 or later.
InstantSearch.js v4.8.3 or later.

Examples

JavaScript

const insightsMiddleware = createInsightsMiddleware({
  insightsClient,
  insightsInitParams,
  onEvent,
});

search.use(insightsMiddleware);

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.

<script>
  /*
    A snippet to include `search-insights`
    You can find it here
    https://github.com/algolia/search-insights.js
  */
</script>

<script>
  const insightsMiddleware = instantsearch.middlewares.createInsightsMiddleware({
    insightsClient: window.aa,
  });

  search.use(insightsMiddleware);

  const userToken = // Get the user token (synchronously or asynchronously).

  // The `insights` middleware receives a notification
  // and attaches the `userToken` to search calls onwards.
  window.aa('setUserToken', userToken);
</script>

import aa from "search-insights";
import { createInsightsMiddleware } from "instantsearch.js/es/middlewares";

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

search.use(insightsMiddleware);

// Get the user token (synchronously or asynchronously).
const userToken = /*...*/;

// The `insights` middleware receives a notification
// and attaches the `userToken` to search calls onwards.
aa("setUserToken", userToken);

insightsInitParams

object

since: v4.11.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 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.

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

createInsightsMiddleware({
  insightsInitParams: {
    userToken: "user-token",
    authenticatedUserToken: "auth-user-token",
  },
});

onEvent

(event: InsightsEvent, aa: null | InsightsClient) => void

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

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

Connectors

Many of the InstantSearch connectors expose the sendEvent method. If you use these connectors to create custom widgets, you can leverage the method to send custom events.Here’s a list of connectors that expose sendEvent.

connectAutocomplete: autocomplete
connectGeoSearch: geoSearch
connectHierarchicalMenu: hierarchicalMenu
connectHits: hits
connectInfiniteHits: infiniteHits
connectMenu: menu and menuSelect *
connectNumericMenu: numericMenu
connectRange: rangeInput and rangeSlider *
connectRatingMenu: ratingMenu *
connectRefinementList: refinementList
connectToggleRefinement: toggleRefinement

* The sendEvent method provided to connectNumericMenu, connectRange, and connectRatingMenu can’t be used to send clicked filter events.

JavaScript

const renderRefinementList = (renderOptions, isFirstRendering) => {
  const { sendEvent } = renderOptions;

  // `sendEvent` from `connectRefinementList` can send `click` events.
  const clickedFacetValue = "Apple";

  // This sends an event like the following:
  /*
    {
      eventType: 'click',
      insightsMethod: 'clickedFilters',
      payload: {
        eventName: 'Filter Applied',
        filters: ['brand:"Apple"'],
        index: '<your-index-name>',
      },
      widgetType: 'ais.refinementList',
    }
  */
  sendEvent("click", clickedFacetValue);

  // Or, you can send a custom payload
  sendEvent({
    eventType: "click",
    insightsMethod: "clickedFilters",
    payload: {
      eventName: "Filter Applied",
      filters: [`brand:${JSON.stringify(clickedFacetValue)}`],
      index: "<your-index-name>",
    },
    widgetType: "ais.refinementList",
  });
};

const customRefinementList = connectRefinementList(renderRefinementList);

Hits

The hits and infiniteHits widgets provide templates with an exposed sendEvent function.The sendEvent(eventType, payload, eventName) function triggers an event. When clicking the button, InstantSearch sends it to Algolia, or forwards it to onEvent if provided.

eventType: 'click' | 'conversion'
payload: Hit
eventName: string

JavaScript

hits({
  // or `infiniteHits`
  // ...
  templates: {
    item: (hit, { html, components, sendEvent }) => {
      return html`
        <div>
          <p>${components.Highlight({ attribute: "title", hit })}</p>
          <button
            type="button"
            onClick=${() => sendEvent("conversion", hit, "Product Added")}
          >
            Add to cart
          <button>
        </div>
      `;
    },
  },
});

​Import

​About this widget

​Requirements

​Examples

​Options

​Custom events

Import

About this widget

Requirements

Examples

Options

Custom events