API client / Methods / Insights

Init

This method is only available for JavaScript.

Required API Key: any key with the search ACL
Method signature 
Only available for JavaScript
See code examples

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

Initialize the Insights API client to communicate with the Algolia Insights API.

Use this method to set global options for the Insights API Client. For example, setting the userToken parameter automatically sends the user token with every event.

It’s also useful to update the params anytime with the partial option.

Guides Get started with click and conversion events
User token
Send click and conversion events with InstantSearch
Send click and conversion events with Autocomplete
API Insights API

Examples

Read the Algolia CLI documentation for more information.

The following examples initialize the Insights API client.

If the user is logged in, set the authenticated user token, which should come from your system.

Copy 
1
2
3
4
5
6
7

import aa from "search-insights";

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

If the user isn’t identified, you can let the Insights API Client generate an anonymous user token, and persist it in the cookies.

Copy 
1
2
3
4
5
6
7

import aa from "search-insights";

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

To set the authenticated user token later, such as, after users sign in, use the setAuthenticatedUserToken method.

Parameters

Parameter Description
appId
type: string
Optional

Identifier of your Algolia application.
apiKey
type: string
Optional

Search API key of your Algolia application.
useCookie
type: boolean
default: false
Optional

Indicates whether to store the anonymous user token in a browser cookie.

Make sure to obtain user consent before setting this parameter to true to comply with local data protection regulations.

Set this parameter to true when using Personalization.

See also: Persisting the user token
cookieDuration
type: integer
default: "15_552_000_000" (6 months)
Optional

Cookie duration in milliseconds.

To enable better personalized experiences with Personalization, it’s recommended to set a cookie duration of at least 3 months (7_776_000_000 milliseconds).
userHasOptedOut
type: boolean
default: false
Optional

Indicates whether to exclude users who have opted out from analytics.

Set this parameter to true when the user requests not to be tracked.
userToken
type: string
pattern: [A-Za-z0-9_=+/-]{1,129}
Optional

Anonymous user identifier.

See also: User Token
authenticatedUserToken
type: string
pattern: [A-Za-z0-9_=+/-]{1,129}
Optional

Pseudonymous identifier for authenticated users.

Never include personally identifiable information in user tokens.

See also: User Token
region
type: "de" | "us"
Optional

Analytics region.
host
type: string
Optional

URL to route requests through before they’re forwarded to Algolia.
partial
type: boolean
Optional

Indicates whether to partially update the configuration while preserving the existing options. This is useful to update the settings of a running Insights client without having to specify all options again.
Copy 
1
2
3
4

aa('init', {
  partial: true,
  userHasOptedOut: true,
});

Response

This method doesn't return a response.

Did you find this page helpful?