Insights
Init |
Initialize the Insights API client to communicate with the Algolia Insights API. |
Clicked object IDs after search |
Send a click event related to an Algolia request. |
Clicked object IDs |
Send a click event to capture clicked items. |
Clicked filters |
Send a click event to capture when users select filters. |
Converted object IDs after search |
Send a conversion event related to an Algolia request. |
Converted object IDs |
Send a conversion event to capture clicked items. |
Converted filters |
Send a conversion event to capture the filters a user selected when converting. |
Viewed object IDs |
Send a view event to capture viewed items. |
Viewed filters |
Send a view event to capture the active filters for items a user viewed. |
Send events |
Send a list of events in a single request. |
Set user token |
Set the user token for all subsequent events sent to the Algolia Insights API. |
Get user token |
Get the user token from the Insights API Client state. |
We released a new version of the PHP API client in public beta. Read the beta documentation for more information.
We released a new version of the Java API client in public beta. Read the beta documentation for more information.
The Algolia Insights API lets you collect events related to your search and discovery experience. 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.
Install the Insights client
The Insights client is a separate npm package. Find the source code on GitHub.
To send Insights events from your JavaScript app, either include a code snippet directly in your HTML or install it as a dependency in your project.
Include the Insights client in your HTML
Paste the following code snippet into the <head>
tag of every page where you want to track Insights events.
1
2
3
4
5
6
7
8
<script>
var ALGOLIA_INSIGHTS_SRC = "https://cdn.jsdelivr.net/npm/search-insights@2.6.0/dist/search-insights.min.js";
!function(e,a,t,n,s,i,c){e.AlgoliaAnalyticsObject=s,e[s]=e[s]||function(){
(e[s].queue=e[s].queue||[]).push(arguments)},e[s].version=(n.match(/@([^\/]+)\/?/) || [])[1],i=a.createElement(t),c=a.getElementsByTagName(t)[0],
i.async=1,i.src=n,c.parentNode.insertBefore(i,c)
}(window,document,"script",ALGOLIA_INSIGHTS_SRC,"aa");
</script>
If you prefer hosting your own version, copy the script in your own project.
1
2
3
4
5
<script>
var ALGOLIA_INSIGHTS_SRC = 'path/to/search-insights.min.js';
// …
</script>
Install the Insights client with npm
Install the search-insights
package in your project:
1
npm install search-insights
Initialize the Insights client
Starting from v2.4.0, you no longer need to initialize the Insights client and instead can pass credentials via headers
per individual call. If you’re using the client with InstantSearch or Autocomplete, credentials are inferred from the passed search client.
To initialize the Insights client, you need your Algolia application ID and your API key with search
permissions.
You can find both in your Algolia dashboard.
1
2
3
4
5
6
7
8
<?php
require_once __DIR__."/vendor/autoload.php";
use Algolia\AlgoliaSearch\InsightsClient;
$insightsClient = InsightsClient::create(
"YourApplicationID",
"YourSearchOnlyAPIKey"
)
Identify users
You need to provide anonymous or pseudonymous user identifiers as userToken
when tracking Insights events. To identify users consistently, you should provide your own user IDs:
1
2
// See previous code snippet for how to initialize the Insights client
aa('setUserToken', 'user-token-1');
The search-insights
library can also generate anonymous user IDs and store them in a cookie which persists across sessions.
1
2
3
4
5
6
7
const aa = require('search-insights')
aa('init', {
appId: 'YourApplicationID',
apiKey: 'YourSearchOnlyAPIKey',
+ useCookie: true,
})
Ensure you obtain user consent before storing cookies on their device.