Insights

List of methods

Clicked Object IDs After Search clickedObjectIDsAfterSearch clickedObjectIDsAfterSearch clickedObjectIDsAfterSearch clicked_object_ids_after_search clicked_object_ids_after_search ClickedObjectIDsAfterSearch clickedObjectIDsAfterSearch ClickedObjectIDsAfterSearch clickedAfterSearch send event ClickedObjectIDsAfterSearch	Send a click event to capture a query and its clicked items and positions.
Clicked Object IDs clickedObjectIDs clickedObjectIDs clickedObjectIDs clicked_object_ids clicked_object_ids ClickedObjectIDs clickedObjectIDs ClickedObjectIDs clicked send event ClickedObjectIDs	Send a click event to capture clicked items.
Clicked Filters clickedFilters clickedFilters clickedFilters clicked_filters clicked_filters ClickedFilters clickedFilters ClickedFilters clicked send event ClickedFilters	Send a click event to capture the filters a user clicks on. You can’t send these events for numeric filters.
Converted Object IDs After Search convertedObjectIDsAfterSearch convertedObjectIDsAfterSearch convertedObjectIDs converted_object_ids_after_search converted_object_ids_after_search ConvertedObjectIDsAfterSearch convertedObjectIDsAfterSearch ConvertedObjectIDsAfterSearch convertedAfterSearch send event ConvertedObjectIDsAfterSearch	Send a conversion event to capture a query and its clicked items.
Converted Object IDs convertedObjectIDs convertedObjectIDs convertedObjectIDs converted_object_ids converted_object_ids ConvertedObjectIDs convertedObjectIDs ConvertedObjectIDs converted send event ConvertedObjectIDs	Send a conversion event to capture clicked items.
Converted Filters convertedFilters convertedFilters convertedFilters converted_filters converted_filters ConvertedFilters convertedFilters ConvertedFilters converted send event ConvertedFilters	Send a conversion event to capture the filters a user uses when converting.
Viewed Object IDs viewedObjectIDs viewedObjectIDs viewedObjectIDs viewed_object_ids viewed_object_ids ViewedObjectIDs viewedObjectIDs ViewedObjectIDs Viewed Object IDs send event ViewedObjectIDs	Send a view event to capture viewed items.
Viewed Filters viewedFilters viewedFilters viewedFilters viewed_filters viewed_filters ViewedFilters viewedFilters ViewedFilters viewed send event ViewedFilters	A user browsing on a category page usually sees content filtered on that specific category. However, they haven’t clicked on or interacted with that filter. In scenarios where a user sees filtered content without interacting with that filter, you send view events. Sending a view event captures the filters a user sees when viewing filtered content without having actively filtered it.
Send Events sendEvents sendEvents sendEvents send_events send_events SendEvents sendEvents SendEvents sendEvents send events	Send a batch of events.

It’s recommended to use the Kotlin API client, which is better suited for Android development.

The Insights API lets you capture click, conversion, and view events to help you understand how your users interact with your digital experience.

Guide Getting started with events

We released a new version of the JavaScript API client in public beta. Read the beta documentation for more information.

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.

Install the Insights client

The Insights client is distributed as a separate npm package. You can find the source code on GitHub

To send Insights events from your JavaScript application, you can 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.

Copy
<script>
var ALGOLIA_INSIGHTS_SRC = "https://cdn.jsdelivr.net/npm/search-insights@2.2.1";

!function(e,a,t,n,s,i,c){e.AlgoliaAnalyticsObject=s,e[s]=e[s]||function(){
(e[s].queue=e[s].queue||[]).push(arguments)},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>

Install the Insights client with npm

Install the search-insights package in your project:

Copy

1
npm install search-insights

Initialize the Insights 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.

Copy

1
2
3
4
5
6
7
8
9
10
<?php
# Installation instructions:
# https://www.algolia.com/doc/api-client/getting-started/install/
require_once __DIR__."/vendor/autoload.php";
use Algolia\AlgoliaSearch\InsightsClient;

$insightsClient = InsightsClient::create(
  "YourApplicationID",
  "YourSearchOnlyAPIKey"
)

1
2
3
4
5
6
7
8
# Installation instructions:
# https://www.algolia.com/doc/api-client/getting-started/install/
require 'algolia'

insights_client = Algolia::Insights::Client.create(
  'YourApplicationID',
  'YourSearchOnlyAPIKey',
)

1
2
3
4
5
6
7
8
// If you include Insights in your HTML,
// comment out the following line
const aa = require("search-insights")

aa('init', {
  appId: 'YourApplicationID',
  apiKey: 'YourSearchOnlyAPIKey'
})

1
2
3
4
5
6
7
8
# Installation instructions:
# https://www.algolia.com/doc/api-client/getting-started/install/
from algoliasearch.insights_client import InsightsClient

insights_client = InsightsClient.create(
  "YourApplicationID", 
  "YourSearchOnlyAPIKey",
)

1
2
3
4
5
6
7
8
// Installation instructions:
// https://www.algolia.com/doc/api-client/getting-started/install/
import AlgoliaSearchClient

let client = InsightsClient(
  appID: "YourApplicationID",
  apiKey: "YourSearchOnlyAPIKey"
)

1
2
3
4
5
6
7
8
9
10
11
// Installation instructions:
// https://www.algolia.com/doc/api-client/getting-started/install/
import com.algolia.search.client.ClientInsights
import com.algolia.search.model.APIKey
import com.algolia.search.model.ApplicationID

suspend fun main() {
  val client = ClientInsights(
    applicationID = ApplicationID("YourApplicationID"),
    apiKey = APIKey("YourSearchOnlyAPIKey")
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Installation instructions:
// https://www.algolia.com/doc/api-client/getting-started/install/
using Algolia.Search.Clients;

class Program
{
  public static void Main(string[] args)
  {
    var client = new InsightsClient(
        "YourApplicationID",
        "YourSearchOnlyAPIKey"
    );
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Installation instructions:
// https://www.algolia.com/doc/api-client/getting-started/install/
package events;

import com.algolia.search.DefaultInsightsClient;
import com.algolia.search.InsightsClient;

public class App {
  public static void main(String[] args) {
    InsightsClient client = DefaultInsightsClient.create(
          "YourApplicationID",
          "YourSearchOnlyAPIKey"
    );
  }
}

1
2
3
4
5
6
7
8
9
10
11
// Installation instructions:
// https://www.algolia.com/doc/api-client/getting-started/install/
package main
import "github.com/algolia/algoliasearch-client-go/v3/algolia/insights"

func main() {
  insightsClient := insights.NewClient(
    "YourApplicationID",
    "YourSearchOnlyAPIKey"
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Installation instructions:
// https://www.algolia.com/doc/api-client/getting-started/install/
package org.example

import algolia.AlgoliaClient
import algolia.AlgoliaDsl._
import algolia.inputs.InsightsEvent

import scala.concurrent.ExecutionContext.Implicits.global

object Program extends App {
  val client = new AlgoliaClient(
    "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:

Copy
// See previous code snippet for how to initialize the Insights client
aa('set-user-token', 'user-token-1')

The search-insights library can also generate anonymous user IDs that it stores in a cookie.

Copy
const aa = require('search-insights')

aa('init', {
  appId: 'YourApplicationID',
  apiKey: 'YourSearchOnlyAPIKey',
+ useCookie: true,  
})

Make sure to obtain user consent before storing cookies on a user’s device.

Did you find this page helpful?