Initialize the Coveo analytics library

This is for:

Developer

In this article

Global fields
Tracking ID
User authentication
Coveo UA alternate endpoints

You must include the following script tag to load the Coveo analytics library into your page. The first parameter is always a command name, and the other parameters vary depending on the executed command. The init command is used to initialize the script and must be called once on each page.

<script>
  (function(c,o,v,e,O,u,a){
  a='coveoua';c[a]=c[a]||function(){(c[a].q=c[a].q|| []).push(arguments)};
  c[a].t=Date.now();u=o.createElement(v);u.async=1;u.src=e;
  O=o.getElementsByTagName(v)[0];O.parentNode.insertBefore(u,O)
  })(window,document,'script','https://static.cloud.coveo.com/coveo.analytics.js/2/coveoua.js')
  coveoua('set', 'currencyCode', '<CURRENCY_CODE>'); 

  // When your Coveo organization contains multiple websites, add the following line of code

  coveoua('set', 'trackingId': '<YOUR_STOREFRONT>'); 

  // end

  coveoua('init', '<COVEO_API_KEY_OR_SEARCH_TOKEN>', '<ENDPOINT>');   

  // When using an API key instead of a search token, add the following lines of code

  if (typeof <USER_ID> !== 'undefined') {
    coveoua('set', 'userId', '<USER_ID>'); 
  }
  // end
</script>

	Global fields
	Tracking ID
	User Authentication
	Coveo UA Endpoint

Global fields

Some commands allow setting data where fields parameters can be set for the entire page. Fields can be set with coveoua("set", <FIELD_NAME>, <FIELD_VALUE>). In the example above we replace <CURRENCY_CODE> in the script with the three-letter currency code following the ISO 4217 standard to identify a user’s currency (e.g., USD). (i.e., coveoua('set', 'currencyCode', 'EUR').) For reference information, see Global fields references.

Tracking ID

A tracking ID is a unique identifier used to differentiate and categorize Coveo Usage Analytics (Coveo UA) data between distinct experiences or website properties within a client’s organization. Similar to the organization ID which identifies the organization itself, the tracking ID points to a specific storefront, creating a way to bucket events belonging to different user journeys.

In a user journey, all events should be tied together for consistency and for accurate data analytics. The tracking ID is therefore the common thread that connects all user actions within a single experience, facilitating the process of analyzing the data including user behavior and preferences.

Note

A single user journey can’t span multiple tracking IDs, and UA data is segregated by tracking ID. Therefore when you analyze metrics like page views, clicks, or conversions, the advanced reports will show them separately for each tracking ID.

It can be adapted to different setups, including but not limited to variations in languages, regions, and business strategies.

The tracking ID shouldn’t be confused with other factors such as the site’s domain, locale, or catalog ID.

In the script above you would replace <YOUR_STOREFRONT> with your unique identifier to ensure that analytics across multiple digital experiences are properly tracked. See Tracking ID for more information.

User authentication

Replace <COVEO_API_KEY_OR_SEARCH_TOKEN> in the script with authentication credentials passed in the form of an API key or a search token.

API key

Replace <COVEO_API_KEY_OR_SEARCH_TOKEN> in the script with an API key for Analytics created for your catalog. Upon receipt of a commerce event in Coveo Usage Analytics (Coveo UA), we extract the catalog ID for that event based on the api key. The collected events are then sent to Coveo Machine Learning (Coveo ML) models which help to harmonize the results returned to the customers.

Before you start, ensure that you’re aware of the leading practices regarding API keys. To create an API key for Analytics, you must:

Access the Catalogs (platform-ca | platform-eu | platform-au) page.
Click the catalog for which you want to create an API key, and then click Create API Key in the Action bar.
Select API Key for Analytics.
Click Create Key.

The created API key value is unique. It’s impossible to view the value more than once.

If you fail to get the value, delete the lost key and create a new one.

Use the `userId` field with an API key

Provided that the API key has the necessary privileges, use the userId field to log user identities. Replacing <USER_ID> in the script with a value, such as asmith@example.com, will log the event under that specific identity. Leaving the field empty will log the event under an anonymous identity.

Search token

An alternate authentication method would be to use a search token when impersonating users, because a search token is temporary and encrypted.

Replace <COVEO_API_KEY_OR_SEARCH_TOKEN> in the script with a search token you create, with the Push access level on the Analytics Data domain and the Allowed access level on the Impersonate domain. The user-specific token will add the user’s information to the event and context which will improve the search experience for the user.

WARNING

Ensure that you use the impersonate domain of the Analytics service, linked above. Don’t use the Impersonate domain of the Search service, as it will allow users to send queries under any identity.

The userId field is always ignored when using a search token, since Coveo will instead extract the user from the search token itself.

When creating the token, use the following payload for an unauthenticated user:

{
    "userIds": [
        {
            "name": "anonymous",
            "provider": "Email Security Provider",
            "type" : "User"
        }
    ]
}

Use a payload similar to the following for an authenticated user (replace asmith@example.com with the actual email of the user for whom you’re requesting a search token):

{
    "userIds": [
        {
            "name": "asmith@example.com",
            "provider": "Email Security Provider",
            "type": "User"
        }
    ]
}

Every Coveo organization comes with an Email Security Provider. Hence, the above examples will be compatible by default. If you’re using a custom security identity provider, set the provider parameter to the name of that provider instead.

Coveo UA alternate endpoints

To log UA events for an organization, ensure that you set the Coveo endpoint option of your desired Analytics component. Otherwise, the default production endpoint (prod-us) will be used and you won’t benefit from your organization-specific analytics endpoint.

When initializing the library, replace <ENDPOINT> in the script with the Coveo endpoint for your organization.

Coveo Endpoint