Send media events

Collect user interactions as events on your media website using InstantSearch.

This page shows media-specific click and conversion patterns for InstantSearch apps. For the concepts behind event tracking, see Click and conversion events. For other implementation paths, see Choose how to send events.

Enable events collection

To follow this guide, build search results or category pages with one of these UI libraries:

• InstantSearch.js version 4.59 or later (Upgrade guide)
• React InstantSearch version 7.2.1 or later (Upgrade guide)
• Vue InstantSearch version 4.12.0 or later (Upgrade guide)

InstantSearch loads the search-insights library for you from jsDelivr. You don’t need to install or initialize it yourself.

If you’re using a Content Security Policy and you want to let InstantSearch load search-insights, add https://cdn.jsdelivr.net to your list of trusted JavaScript sources.

script-src https://cdn.jsdelivr.net/

If you prefer self-hosting search-insights, add it to your project:

1. Install the Insights client
2. Initialize the Insights client (optional)

InstantSearch doesn’t load search-insights when it detects it on the page.

You can enable automatic collection in the Algolia dashboard or in your InstantSearch app.

Enabling automatic events collection does the following:

• Adds the search-insights library to your project and makes it globally available as window.aa
• Sets an anonymous userToken for events and search requests
• Includes the queryID parameter in the search response
• Sends default click and view events for your InstantSearch widgets

Go to the Events hub in the Algolia dashboard to check the default events arriving from your website or app. For more information, see Validate your events.

No code

1. Go to the Algolia dashboard and select your Algolia .
2. On the left sidebar, select Data sources > Events > Settings.
3. Click Enable automatic events collection.

Code

Enable the insights option:

JavaScript

const search = instantsearch({
  searchClient,
  indexName: "YourIndexName",
  insights: true, 
});
// Add your InstantSearch widgets here
search.start();

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

Map your media journey to events

Map the steps users take through your website and add events that aren’t automatically captured by InstantSearch widgets. This is especially useful for actions such as watching a video, reading an article, or liking a page.

Search results page

Starting with a search on any of your pages, a user might take the following actions:

1. Select content from the search results to open the content details page.
2. Consume content, such as watching a video, reading an article, or listening to an audio track.
3. Interact with content, such as liking, subscribing, or following.

Browse page

Starting with a visit to your homepage or to a category page, a user might take the following actions:

1. Select a content category to open a category page.
2. Select content displayed on the page to open the content details page.
3. Consume content, such as watching a video, reading an article, or listening to an audio track.
4. Interact with content, such as liking, subscribing, or following.

External referrals

Starting with a search on an internet search engine, with a click on a recommendation, or any other external referral, a user might take the following actions:

1. Click on a (internet) search result, recommendation, or other link to your website.
2. Depending on where the user lands on your website, they continue the same path as if they started with your homepage or with a category page.

Search and search results pages

User action	Method name	Automatically collected?
User clicks search result	clickedObjectIDsAfterSearch	Yes
User clicks categories/filters	clickedFilters	Yes
User views search results	viewedObjectIDs	Yes

Browse/category page

User action	Method name	Automatically collected?
User clicks content	clickedObjectIDsAfterSearch	Yes
User views content	viewedObjectIDs	Yes

Content details page

User action	Method name	Automatically collected?
User views content	viewedObjectIDs	No

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 media conversion events

Send events from InstantSearch widgets

You can use the sendEvent function to send conversion events from your InstantSearch app.

JavaScript

hits({
  templates: {
    item(hit, { html, components, sendEvent }) {
      return html`
        <h2>${components.Highlight({ attribute: "name", hit })}</h2>
        <p>${hit.description}</p>
        <button
          onClick="${() =>
            sendEvent("conversion", hit, "Article Added To Favorites");
          }"
        >
          Add to favorites
        </button>
      `;
    },
  },
});

Setting custom conversion events doesn’t prevent the custom click event from being sent.

On pages without InstantSearch widgets

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

JavaScript

// 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 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 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 media click events

Override default click events

The hits and infiniteHits widgets expose a sendEvent function. Use it to send click events when users interact with your search results.

JavaScript

hits({
  templates: {
    item(hit, { html, components, sendEvent }) {
      return html`
        <div onClick="${() => sendEvent("click", hit, "Article Clicked")}">
          <h2>${components.Highlight({ attribute: "name", hit })}</h2>
          <p>${hit.description}</p>
        </div>
      `;
    },
  },
});

You can set more events on specific parts of your template. In the following example, when clicking on the View more info button, two events are sent to the Insights API:

• A click event with the eventName “Article More Info Clicked”
• A click event with the eventName “Article Clicked” (through event propagation)

JavaScript

hits({
  templates: {
    item(hit, { html, components, sendEvent }) {
      return html`
        <div onClick="${() => sendEvent("click", hit, "Article Clicked")}">
          <h2>${components.Highlight({ attribute: "name", hit })}</h2>
          <p>${hit.description}</p>
          <button
            onClick="${() =>
              sendEvent("click", hit, "Article More Info Clicked")
            }"
          >
            View more info
          </button>
        </div>
      `;
    },
  },
});

To only send the most specific event per clicked element, you can use Event.stopPropagation in your event handler.

JavaScript

hits({
  templates: {
    item(hit, { html, components, sendEvent }) {
      return html`
        <div onClick="${() => sendEvent("click", hit, "Article Clicked")}">
          <!-- ... -->
          <button
            onClick="${(event) => {
              event.stopPropagation(); 

              sendEvent("click", hit, "Article More Info Clicked");
            }}"
          >
            View more info
          </button>
        </div>
      `;
    },
  },
});

When InstantSearch captures a custom click event that you defined, it doesn’t send the default click event. In the following example, when clicking the View more info button, only the “Article More Info Clicked” event is sent.

JavaScript

hits({
  templates: {
    item(hit, { html, components, sendEvent }) {
      return html`
        <h2>${components.Highlight({ attribute: "name", hit })}</h2>
        <p>${hit.description}</p>
        <button
          onClick="${() =>
            sendEvent("click", hit, "Article More Info Clicked")
          }"
        >
          View more info
        </button>
      `;
    },
  },
});

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

JavaScript

window.aa("clickedObjectIDs", {
  index: "YourIndexName",
  eventName: "Article 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);

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,
});

If you don’t use persistent user identifiers, a new anonymous user token is generated on every page refresh.

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

InstantSearch automatically sends view events for search results and category pages. Send additional view events for experiences outside InstantSearch widgets, such as a homepage hero or editorial module.

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.

Examples

• InstantSearch.js:

  • Demo
  • Source code

• React InstantSearch:

  • Demo
  • Source code

• Vue InstantSearch:

  • Demo
  • Source code

Add events to a React InstantSearch application