Send events

Collect user interactions as events on your website using search-insights.js

This page shows how to send click and conversion events manually with search-insights. For the concepts behind event tracking, see Click and conversion events. For other implementation paths, see Choose how to send events.

Set up event collection

Before sending events manually, make sure your search requests return queryID and your frontend can call search-insights.

Set the clickAnalytics parameter to true when making search requests. This includes the queryID parameter in the search response, which links search-related events to the originating search request.

JavaScript

const algoliasearch = require("algoliasearch");
const client = algoliasearch(
  "ALGOLIA_APPLICATION_ID",
  "ALGOLIA_SEARCH_API_KEY",
);
const index = client.initIndex("YourIndexName");

index
  .search("query test", { clickAnalytics: true })
  .then(({ queryID, hits }) => {
    console.log(hits);
    console.log(queryID);
  });

Install the search-insights library.

HTML

<script>
  var ALGOLIA_INSIGHTS_SRC = "https://cdn.jsdelivr.net/npm/search-insights@2.17.3/dist/search-insights.min.js";

  !function(e,a,t,n,s,i,c){e.AlgoliaAnalyticsObject=s,e[s]=e[s]||function(){
  (e[s].queue=e[s].queue||[]).push(arguments)},e[s].version=(n.match(/@([^\/]+)\/?/) || [])[1],i=a.createElement(t),c=a.getElementsByTagName(t)[0],
  i.async=1,i.src=n,c.parentNode.insertBefore(i,c)
  }(window,document,"script",ALGOLIA_INSIGHTS_SRC,"aa");
</script>

After installing search-insights, initialize the client in your website.

JavaScript

import aa from "search-insights";

aa("init", {
  appId: "ALGOLIA_APPLICATION_ID",
  apiKey: "ALGOLIA_SEARCH_API_KEY",
});

For more on tracking queryID and userToken, see Keep track of query IDs and User token.

Decide which custom events to send

Map the steps users take through your website and send events for the actions that matter to your business.

Consider the following sequence:

1. A user searches on your homepage and is presented with a list of real estate properties.
2. The user clicks on a property to view more details.
3. The user converts by contacting the realtor.

In this example, track these events:

• Property Clicked by using the clickedObjectIDsAfterSearch method.
• Property Contacted by using the convertedObjectIDsAfterSearch method.

A conversion is any user action that’s valuable to your business; a user purchasing from your store or subscribing to your newsletter are examples of common conversions. — GA4 About conversions

Track query IDs across pages

Conversion events often happen outside the search results page.

• A query ID is returned by the when a user performs a search.
• To associate a conversion with the correct , save this query ID and include it in your conversion events.
• To link conversion events back to the originating search request on your search results or category pages, track query IDs across your pages.

Track click events

Click events capture when users indicate they want to view specific items. Add the following code to track a user navigating to an item from a search results page:

JavaScript

window.aa("clickedObjectIDsAfterSearch", {
  index: "YourIndexName",
  eventName: "Item Clicked",

  // Fields from the search response.
  queryID: "YourQueryID",
  objectIDs: ["objectID-1"],
  positions: [1],
});

The queryID parameter of the clickedObjectIDsAfterSearch method is used by Algolia to relate the event to a prior search or browse event.

The objectIDs parameter of the clickedObjectIDsAfterSearch method should contain the ID of the item. This can be retrieved from the objectID field of the hits array returned from the search request.

The positions parameter of the clickedObjectIDsAfterSearch method indicates the position of the item in the search results. For example, if the user clicked on the top result on the page, positions should be [1].

If a user found an item without performing a search—for example, they browsed there from elsewhere on your site, add the following code to track that:

JavaScript

window.aa("clickedObjectIDs", {
  index: "YourIndexName",
  eventName: "Item Clicked",
  objectIDs: ["objectID-1"],
});

Track conversion events

An example of a conversion event that may happen after a search:

JavaScript

// A user contacted the realtor from a property details page
window.aa("convertedObjectIDsAfterSearch", {
  eventName: "Property Contacted",
  index: "YourIndexName",
  queryID: "query-1",
  objectIDs: ["objectID-1"],
});

The window.aa object is the API client for the Insights API and is globally available if you enabled automatic events collection.

The queryID parameter of the convertedObjectIDsAfterSearch method is used by Algolia to relate the event to a prior search.

The objectIDs parameter of the convertedObjectIDsAfterSearch method indicates which items were part of the conversion.

The objectID parameter is included in the search response for each hit.

If the event isn’t directly related to a search, for example, it’s triggered on the homepage, use the convertedObjectIDs method instead.

JavaScript

// A user favorited an item from a homepage recommendation module
window.aa("convertedObjectIDs", {
  eventName: "Item Added To Favorites",
  index: "YourIndexName",
  objectIDs: ["objectID-1"],
});

Some other examples of conversion events are:

• Item Added To Favorites: a user saved an item.
• Lead Submitted: a user completed a lead form.
• Demo Requested: a user asked for a product demo.
• Property Contacted: a user contacted the realtor.
• Store Appointment Booked: a user booked an appointment.

Track more click events

For Algolia Recommend and Personalization, capture additional click events when users select individual items:

• On your home page
• From recommendations

To send click events with the Insights client, add the following code whenever a user clicks on an item—for example, on your homepage.

JavaScript

window.aa("clickedObjectIDs", {
  index: "YourIndexName",
  eventName: "Item Clicked",
  objectIDs: ["objectID-1"],
});

Optional: identify known users for Personalization

For effective personalization, identify users across sessions. It’s best to use an identifier from your authentication system after users sign in.

After getting the identifier from your system, set it as the authenticatedUserToken parameter.

JavaScript

// Get a unique, pseudonymous identifier for signed-in users
const authenticatedUserToken = getUserTokenAfterSignIn();
window.aa("setAuthenticatedUserToken", authenticatedUserToken);

When you set the authenticatedUserToken parameter in the Insights client, also update the user token you send with your search requests.

JavaScript

function getEffectiveUserToken() {
  const userToken = window.aa("getUserToken");
  const authenticatedUserToken = window.aa("getAuthenticatedUserToken");
  return authenticatedUserToken || userToken;
}

index
  .search("query", {
    clickAnalytics: true,
    userToken: getEffectiveUserToken(),
  })
  .then(({ queryID, hits }) => {
    console.log(hits);
    console.log(queryID);
  });

If you can’t get persistent user identifiers from your system, you can store the anonymous user token in a cookie after obtaining user consent.

JavaScript

// If user consented
aa("init", {
  partial: true,
  useCookie: true,
});

For more on identity strategy and persistence, see User token.

Optional: send view events for Personalization

Personalization benefits from the same click and conversion events, plus it can use view events to enrich each .

Use the following code snippet to track view events, such as when a user views search results.

JavaScript

window.aa("viewedObjectIDs", {
  index: "YourIndexName",
  eventName: "Item Viewed",
  objectIDs: ["objectID-1"],
});

You don’t need to send a queryID when tracking view events.