> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send click and conversion events with the Flutter Helper

> Unlock Algolia's most powerful features by sending click and conversion events from your Flutter app.

export const UserToken = () => <Tooltip tip="A user token is a pseudonymous ID that represents an individual user across Algolia searches and events. It links queries, clicks, and conversions to a user profile, enabling user-level analytics, personalization, and recommendations." cta="User token" href=" /doc/guides/sending-events/concepts/usertoken">
    user token
  </Tooltip>;

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

export const Filter = () => <Tooltip tip="A filter is a condition that limits which records Algolia returns. Filters often use one or more facet-value pairs, such as brand:Apple AND color:red. You can also filter by numeric values, dates, tags, booleans, or geographic constraints." cta="Filtering" href="/doc/guides/managing-results/refine-results/faceting">
    filter
  </Tooltip>;

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 [Choose how to send events](/doc/guides/sending-events/getting-started).

## 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` 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](https://dashboard.algolia.com/account/api-keys).

```dart Dart theme={"system"}
final insights = Insights('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');
```

## Customizing the user token

You can set a custom <UserToken /> 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.

```dart Dart theme={"system"}
insights.userToken = 'user-123';
```

## Send events from the HitsSearcher component

If you're using multiple [`Hits Searcher`](/doc/api-reference/widgets/instantsearch/flutter) 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`](/doc/api-reference/api-parameters/clickAnalytics) parameter to get the `queryID`.
With the `queryID` parameter available, you can send click and conversion events:

```dart Dart theme={"system"}
final searcher = HitsSearcher(
    applicationID: 'ALGOLIA_APPLICATION_ID',
    apiKey: 'ALGOLIA_SEARCH_API_KEY',
    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:

```dart Dart theme={"system"}
searcher.eventTracker.isEnabled = false;
```

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

<Note>
  For the `positions` parameter of the [`clickedObjectIdsAfterSearch`](/doc/libraries/sdk/v1/methods/clicked-object-ids-after-search) method, the first object in the list of search results has a value of 1 (not 0), the second has a value of 2.
</Note>

## 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 a <Filter />.

```dart Dart theme={"system"}
final searcher = HitsSearcher(applicationID: 'ALGOLIA_APPLICATION_ID',
                              apiKey: 'ALGOLIA_SEARCH_API_KEY',
                              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:

```dart Dart theme={"system"}
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:

```dart Dart theme={"system"}
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](/doc/guides/sending-events/guides/queryid) across your app.

When you add events, check them in the [Events Debugger](https://dashboard.algolia.com/events/debugger) in the Algolia dashboard.
For more information, see [Validate your events](/doc/guides/sending-events/guides/validate).