Send events with Flutter Helper

The Flutter Helpers are available as alpha software. They depend on the Algolia Dart API client, which is developed by the community. Note that the Algolia SLA don’t apply to community projects. To share feedback or report a bug, open an issue.

The Flutter Helper library allows developers to send click, conversion, and view events. For search-related events, it correlates the event with the queryIDs generated when you’ve set the clickAnalytics parameter to true.

Algolia uses valid search-related events for Click and Conversion Analytics. Click and Conversion Analytics form the foundation for more advanced features like A/B Testing and Dynamic Re-Ranking. Algolia uses all valid events for Personalization. Even if you aren’t planning on implementing Personalization right away, it’s helpful to consider sending events as if you were. This lets you implement Personalization later on with a robust corpus of well-formatted user data.

Supported platforms

Insights Dart is supported on all the platforms supported by Dart/Flutter: Android, iOS, Linux, macOS, Windows, and the web.

Install the Insights Dart library

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

Initialize the Insights client

First, you need to initialize the Insights instance with your application ID and API key: find them in the API Keys section) of the dashboard. Every event you send should have a userToken field to specify the user it relates to.

1
final insights = Insights('MY_APPLICATION_ID', 'MY_API_KEY');

Sending events

Once you’ve registered your index with the application ID and the API key, you can start sending events. For examples of the different kinds of events and what user behaviors translate into them, refer to the guide on capturing user behaviors as events.

Insights events (view, click, and conversion) don’t take immediate effect. There’s a delay of from a few minutes up to an hour (depending on whether they’re sent after a search or not and how long after a search they’re sent).

For a better estimation, see how long it takes for Insights events to be taken into account.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
insights.clickedObjectsAfterSearch(indexName: 'MY_INDEX_NAME',
                                   eventName: 'CLICK_OBJECT',
                                   queryID: 'QUERY_ID',
                                   objectIDs: ['objectID1', 'objectID2', 'objectID3'],
                                   positions: [5, 6, 7]);


insights.convertedObjectsAfterSearch(indexName: 'MY_INDEX_NAME',
                                     eventName: 'CLICK_OBJECT',
                                     queryID: 'QUERY_ID',
                                     objectIDs: ['objectID1', 'objectID2', 'objectID3'],);


insights.viewedObjects(indexName: 'MY_INDEX_NAME',
                       eventName: 'CLICK_OBJECT',
                       objectIDs: ['objectID1', 'objectID2', 'objectID3'],);

Tracking queryID on other pages

Conversion events don’t always happen on a search results page. For example, a user could buy an item from a product detail page, meaning you must pass the queryID to that page.

Embedding click events in the hits searcher component

The Insights Dart library comes pre-packaged inside Flutter Helper. This simplifies the tracking of click events on search results generated using the Flutter Helper Hits Searcher widgets. You must still send click, view, and conversionevents from other sources.

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

Sending events from the hits searcher component

HitsSearcher component is initialized with data necessary for Insights events It sends View events for received hits automatically and provides convenient methods to track click, view, and conversion objects from the search results. It automatically sets clickAnalytics search parameter to true which guarantees the availability of the queryID parameter fetched with the latest search results. When queryID is available, it sends Click and Convert objects after search events.

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

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 event sending in the HitsSearcher class, set the isEnabled flag of eventTracker to false. This can be useful when you want to pause event tracking temporarily or when working in a development environment.

1
searcher.eventTracker.isEnabled = false;

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

Sending events from the facet list component

The FacetList component is initialized with HitsSearcher from which it inherits the application ID, API key and index name parameters for Insights events. It also provides convenient methods to track View, Conversion, and Click filters events.

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

final facetList = FacetList(searcher: searcher,
                            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 the isEnabled flag of eventTracker to false. This can be useful when you want to pause event tracking temporarily or when working in a development environment.

1
facetList.eventTracker.isEnabled = false;