Send click and conversion events with Angular InstantSearch

Angular InstantSearch isn’t compatible with Angular’s Ivy view engine. We’re investigating how best to support this. For more information and to vote for Algolia’s support of Angular 16 and beyond, see the GitHub issue Algolia Support for Angular InstantSearch

Events are actions that users take on your app or website. They unlock powerful features, such as recommendations, personalization, smarter search results, and analytics that help you optimize your user experience. For more information, see Get started with click and conversion events.

To send events from your Angular InstantSearch app, follow these steps:

1. Add the insights client.
2. Add click events when users click search results.
3. Track conversions that start in your InstantSearch app.

Before you begin

This guide works with:

• search-insights version 1.6.2 or later
• Angular InstantSearch

Add search-insights to your project

The search-insights JavaScript library lets you send events to the Algolia Insights API. To add it to your project:

1. Install the Insights client
2. Initialize the Insights client

Add the insights client

After adding the search-insights library to your project, connect it to your Angular app.

1
2
3
4
5
6
7
8
9
10
11
12
import algoliasearch from 'algoliasearch/lite'

@Component({
  template: ` <ais-instantsearch [config]="config"> </ais-instantsearch> `,
})
export class AppComponent {
  config = {
    indexName: 'instant_search',
    searchClient: algoliasearch('YourApplicationID', 'YourAPIKey'),
    insightsClient: (window as any).aa,
  }
}

This example assumes that you’ve included the search-insights snippet in your HTML.

Set the userToken

To identify users across sessions, explicitly set the userToken:

1
aa('setUserToken', 'user-id')

For example, use the account ID after the user signed in on your website. The search-insights library can generate an anonymous user token and store it in the first-party _ALGOLIA cookie.

Don’t use personally identifiable information as a user ID.

Get the queryID from the search response

Search-related events must include a query ID. To retrieve it, set the clickAnalytics parameter to true using the ais-configure widget:

1
2
3
<ais-instantsearch [config]="config">
  <ais-configure [searchParameters]="{ clickAnalytics: true }"></ais-configure>
</ais-instantsearch>

The insights function infers the queryID from the InstantSearch context.

Send click events

Call the insights function from within the ais-hits component to send an event:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<ais-hits>
  <ng-template let-hits="hits" let-insights="insights">
    <div *ngFor="let hit of hits">
      <a href="/product?queryID={{hit.__queryID}}">
        <ais-highlight attribute="name" [hit]="hit"></ais-highlight>
      </a>
      <button
        (click)="insights('clickedObjectIDsAfterSearch', { eventName: 'Product Clicked', objectIDs: [hit.objectID] })"
      >
        Add to cart
      </button>
    </div>
  </ng-template>
</ais-hits>

Similar to the queryID, the insights function can infer the required event properties from the InstantSearch context. You must provide an eventName.

Check your click events in the Events Debugger. For more information, see Validate your events.

Send conversion events

You can use the insights function with convertedObjectIDsAfterSearch to send a conversion event.

However, conversions often happen outside your search pages. For example, the Order completed event for a successful purchase happens in the shopping cart. To capture these conversions, keep track of the query ID across your site.

Then, send the conversion event with convertedObjectIDsAfterSearch from the search-insights library.

Check your conversion events in the Events Debugger. For more information, see Validate your events.

The insights function doesn’t support sending events that are unrelated to search. For these events, use the API clients, Insights API, or InstantSearch library.

A complete example

See Insights for Angular InstantSearch for a complete example.