🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
API client / Methods / Insights

Clicked object IDs after search

Required API Key: any key with the search ACL
Method signature
$insights->user(string userToken)->clickedObjectIDsAfterSearch(
  string eventName,
  string indexName,
  array objectIDs,
  array positions,
  string queryID
)

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.

You’re currently reading the Ruby API client v2 documentation. Check the migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.

About this method

Send a click event related to an Algolia request.

Use this event to track when users click items in the search results. If you’re using Algolia to build your category pages, you’ll also use the clickedObjectIDsAfterSearch event.

Sending this event is useful for:

Related methods:

  • clickedObjectIDs: track click events not related to Algolia requests.
  • sendEvents: if you don’t want to send real-time events.

Examples

Read the Algolia CLI documentation for more information.

The following example sends one click event to the Algolia Insights API. The event represents a user user-123456 clicking on the item objectID-1, which is at the second position in the results from the index your_index_name

1
2
3
4
5
6
7
8
9
10
11
12
$insights = Algolia\AlgoliaSearch\InsightsClient::create(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

$insights->user("user-123456")->clickedObjectIDsAfterSearch(
  'your_event_name',
  'your_index_name',
  ['objectID-1'],
  [2],
  'queryID'
);

Parameters

userToken
type: string
pattern: [A-Za-z0-9_=+/-]{1,129}
Required

Pseudonymous or anonymous user identifier.

Never include personal identifiable information in user tokens.

See also: User Token

eventName
type: string
pattern: [\x20-\x7E]{1,64}
Required

Name of the specific event.

Format: 1-64 ASCII characters, except control characters.

To maximize the impact of your events, use consistent event names and consistent formatting—for example, “Product Added To Cart” (always in title case).

For example, you can adopt Segment’s object-action framework.

indexName
type: string
Required

Name of the Algolia index.

Format: same as the index name used by the search engine.

Some API clients use index instead of indexName.

objectIDs
type: array
items: string
Required

List of object identifiers for items of an Algolia index.

You can include up to 20 objectID.

positions
type: array
items: uint
Required

Positions of the clicked objects in the search results. This property is required for click events with queryID. The first search result has a position of 1 (not 0).

You must provide one position for each objectID.

Algolia uses this parameter to calculate the average click position.

The position is absolute, and not relative, to any results page. For example, if there are 10 results per page, the position of the third record of the second results page is 13. Since page starts at 0, you can use the following formula: $positionOnPage + $page * hitsPerPage.

queryID
type: string
pattern: [a-f0-9]{32}
Required

Unique identifier for a search query.

A queryID is required for events related to search or browse requests.

If you add clickAnalytics: true as a search request parameter, the queryID is included in the API response.

See also: Keep track of query IDs

Response

This method doesn't return a response.

Did you find this page helpful?