Send events

Capturing real-time user interactions as events gives you actionable insights via click and conversion metrics, and they help you increase your customer engagement and conversions. Events are used to activate Algolia features and products like NeuralSearch, Dynamic Re-Ranking, Query Categorization, Recommend, and Personalization.

Enable events collection

Set the clickAnalytics parameter to true when making search requests. This includes the queryID parameter in the search response, which is required for linking events and search requests.

1
2
3
4
5
6
7
8
9
10
11
  const algoliasearch = require("algoliasearch");
  const client = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");
  const index = client.initIndex("YourIndexName");

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

Initialize search-insights.js

Install the search-insights library.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<script>
  var ALGOLIA_INSIGHTS_SRC =
  "https://cdn.jsdelivr.net/npm/search-insights@2.16.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>

1
npm install search-insights

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

1
2
3
4
5
6
import aa from 'search-insights';

aa("init", {
  appId: "YourApplicationID",
  apiKey: "YourSearchOnlyAPIKey",
});

Understand which events to track

To understand which events you should send, think about the different steps a user takes through your website to perform desired actions.

For example, a user might: Be presented with a list of real estate properties after performing a search from your homepage. Then click on a property to view more details. Finally, convert by contacting the realtor.

In this example, you should track the following events:

• Property Clicked by using the clickedObjectIDAfterSearch method.
• Property Contacted by using the convertedObjectIDAfterSearch 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

Keep track of query IDs

Conversion events are often triggered outside of the search results page. In order to correctly attribute which query is responsible for a conversion, it is necessary to keep track of the query ID returned when a search is performed so that it can be included in conversion events.

To relate the conversion events back to the search request made on your search results or category pages, you need to keep track of the query IDs across your pages.

Track click events

Click events capture when users indicate they want to view specific pieces of content. Add the following code to track a user navigating to a piece of content from a search results page:

1
2
3
4
5
6
7
8
9
window.aa("clickedObjectIDsAfterSearch", {
    index: "YourIndexName",
    eventName: "Item Clicked",

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

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

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

The positions parameter 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 a piece of content without performing a search—for example, they browsed there from elsewhere on your site, add the following code to track that:

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

Track conversion events

An example of a conversion event that may be relevant to your media site:

1
2
3
4
5
6
7
// A user reached the bottom of an article page
window.aa("convertedObjectIDsAfterSearch", {
  eventName: "Article Read",
  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 is used by Algolia to relate the event to a prior search.

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

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

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

1
2
3
4
5
6
// A user watched a video
window.aa("convertedObjectIDs", {
  eventName: "Video Watched",
  index: "YourIndexName",
  objectIDs: ["objectID-1"],
});

Some other examples of conversion events are:

• Article Bookmarked: a user bookmarked an article.
• Article Liked: a user liked an article.
• Article Recommended: a user recommended an article.
• Playlist Followed: a user followed a playlist.
• Author Followed: a user followed an author.
• Brand Followed: a user followed a brand.

Track additional 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 article—for example, on your homepage.

1
2
3
4
5
window.aa("clickedObjectIDs", {
  index: "YourIndexName",
  eventName: "Article Clicked",
  objectIDs: ["objectID-1"],
});

(Optional) Handle known users for Personalization

For effective personalization, you need to identify users across sessions. It’s best to use an identifier from your authentication system after users signed in. For more information, see User token.

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

1
2
3
// 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, you also need to update the user token you send with your search requests.

1
2
3
4
5
6
7
8
9
10
11
12
13
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.

1
2
3
4
5
// If user consented
aa("init", {
    partial: true,
    useCookies: true,
});

(Optional) Send view events for Personalization

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

To capture view events, such as when a user views search results, add this code:

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