Initialize the Coveo UA library

This is for:

Developer

In this article

Global fields
Tracking ID
User authentication
userId (optional)
Coveo UA alternate endpoints

You must include the following script tag to load the Coveo UA 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>'); 

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

  // When using an API key instead of a search token, optionally 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
	`userId` (optional)

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>).

For reference information, see Global fields references.

Set the currency code

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. For example, if you initialize the library on a page that serves European users, you would enter coveoua('set', 'currencyCode', 'EUR').

Tracking ID

A Coveo organization can serve many ecommerce sites or applications. It’s important to segregate the data gathered from each of these sites or applications to ensure personalized and relevant outputs from your Coveo Machine Learning models, as well as usable reporting, and clear merchandising actions.

A tracking ID is a unique identifier used to differentiate and categorize Coveo Usage Analytics (Coveo UA) data by site or app. 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.

Note

The trackingId parameter can only contain letters, numbers, hyphens (-), underscores (_), and periods (.). For example, barca_sports_us-2.1.

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.

Example

Your Coveo organization powers two brands: Barca sports and Barca parts. You operate in two different countries: United States and Canada.

Therefore, you have four different sites that require their own unique tracking ID:

barca_sports_us
barca_sports_ca
barca_parts_us
barca_parts_ca

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

Additionally, 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> with a search token or an API key that grants the Push access level on the Analytics Data domain in the target organization. To use that same search token or API key for your search interface as a whole, also grant it the Allowed access level on the Execute Queries domain privilege.

We strongly recommend that the access token enforces a searchHub value. See Defining the search hub in the authentication for more details.

`userId` (optional)

Provided that the API key has the necessary Impersonate privilege in the Analytics Data domain, you can set the userId field in the payload. 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.

WARNING

Don’t grant the Impersonate privilege of the Search domain, as exposing such an API key in client-side code would allow users to send queries under any identity.

If you’re using search token authentication, the userId is enforced through the token. There’s no need to set it client-side.

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