Send click and conversion events with the Flutter Helper

Algolia for Flutter is beta software according to Algolia’s Terms of Service (“Beta Services”). To share feedback or report a bug, open an issue.

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.

Add the Insights Dart library

To send events to Algolia from your Flutter app, add the Insights Dart library to your project:

1. Add algolia_insights: ^1.0.0-pre to your pubspec.yaml file.
2. Run pub get console command.
3. Add import 'package:algolia_insights/algolia_insights.dart'; to your source files.

Add the Insights client

To add the Insights client, you’ll need your Algolia application ID, (search) API key, and a userToken to identify your users. You can find your application ID and API key in the Algolia dashboard.

1
final insights = Insights('YourApplicationID', 'YourSearchOnlyAPIKey');

Customizing the user token

You can set a custom user token by setting the userToken property on the Insights instance. The user token is used to track events for a specific user. If the user token isn’t specified, the system will automatically generate a token and store it on the device. This auto-generated user token ensures that events are still associated with a unique user identifier, even if a custom token isn’t explicitly provided.

1
insights.userToken = 'user-123';

Send events from the HitsSearcher component

If you’re using multiple Hits Searcher widgets, you must enable sending click events on each one separately. This lets you choose which click events to track and which to ignore.

The HitsSearcher component sends view events automatically. It sets the clickAnalytics parameter to get the queryID. With the queryID parameter available, you can send click and conversion events:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
final searcher = HitsSearcher(
    applicationID: 'YourApplicationID',
    apiKey: 'YourSearchOnlyAPIKey',
    indexName: 'YourIndexName',
  );

searcher.eventTracker.clickedObjects(
    eventName: 'Clicked Objects',
    objectIDs: ['object1', 'object2', 'object3'],
    positions: [1, 2, 3]);

searcher.eventTracker.viewedObjects(
    eventName: 'Viewed Objects',
    objectIDs: ['object1', 'object2', 'object3']);

searcher.eventTracker.convertedObjects(
    eventName: 'Converted Objects',
    objectIDs: ['object1', 'object2', 'object3']);

To turn off both automatic and manual events in the HitsSearcher class, set:

1
searcher.eventTracker.isEnabled = false;

This can be useful when you want to pause event tracking temporarily or when working in a development environment.

For the positions parameter, the first object in the list of search results has a value of 1 (not 0), the second has a value of 2.

Send events from the FacetList component

The FacetList component inherits the application ID, API key and index name parameters from the HitsSearcher. It also provides methods to track view, conversion, and click events for filters.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
final searcher = HitsSearcher(applicationID: 'YourApplicationID',
                              apiKey: 'YourSearchOnlyAPIKey',
                              indexName: 'YourIndexName');

final facetList = searcher.buildFacetList(
  filterState: filterState,
  attribute: 'actors',
);

facetList.eventTracker.clickedFilters(eventName: 'Clicked Filters',
                                      values: ['Samuel L. Jackson']);

facetList.eventTracker.viewedFilters(eventName: 'Viewed Filters',
                                     values: ['Samuel L. Jackson']);

facetList.eventTracker.convertedFilters(eventName: 'Converted Filters',
                                        values: ['Samuel L. Jackson']);

To turn off both automatic and manual event sending in the FacetList class, set:

1
facetList.eventTracker.isEnabled = false;

This can be useful when you want to pause event tracking temporarily or when working in a development environment.

Send click, conversion, and view events from other sources

Use the following methods to send click, conversion, or view events:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
insights.clickedObjectsAfterSearch(
    indexName: 'YourIndexName',
    eventName: 'Clicked Item',
    queryID: 'query id',
    objectIDs: ['objectID1', 'objectID2', 'objectID3'],
    positions: [5, 6, 7],
);


insights.convertedObjectsAfterSearch(
    indexName: 'YourIndexName',
    eventName: 'Purchased Item',
    queryID: 'query id',
    objectIDs: ['objectID1', 'objectID2', 'objectID3']
);

insights.viewedObjects(
    indexName: 'YourIndexName',
    eventName: 'Viewed Item',
    objectIDs: ['objectID1', 'objectID2', 'objectID3']
);

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

When you add events, check them in the Events Debugger in the Algolia dashboard. For more information, see Validate your events.