Initialize the Coveo UA library

This is for:

Developer
Important

We strongly recommend that all new Commerce implementations use the Event Protocol to log events.

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>'); 1

  // When your Coveo organization contains multiple websites, add the following line of code
  coveoua('set', 'trackingId', '<YOUR_STOREFRONT>'); 2

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

  // 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>'); 5
  }
  // end
</script>
1 Global fields
2 Tracking ID
3 User Authentication
4 Coveo UA endpoint
5 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 script in the introduction, replace <CURRENCY_CODE> 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 Coveo-powered commerce sites or applications, but all usage analytics events in a user’s journey should be tied together with a single tracking ID for accurate data analytics and consistency.

tracking IDs segregate the data gathered from each of these sites or applications to ensure personalized and relevant output from your Coveo Machine Learning (Coveo ML) models, usable reporting, and clear merchandising actions.

Each tracking ID points to a specific ecommerce storefront, creating a way to distinguish between distinct sites and their respective user journeys.

The tracking ID is defined when sending events to the Coveo Platform. Interfaces built with the Coveo Headless library or Atomic library automatically include the tracking ID in the events they send. While tracking ID values are specified when sending usage analytics events, each value that’s sent must be registered using a Property in your Coveo organization. To learn how to map your storefront architecture and use tracking IDs in Coveo for Commerce, refer to the Coveo for commerce setup guide.

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 to be sent with each event:

  • barca_sports_us

  • barca_sports_ca

  • barca_parts_us

  • barca_parts_ca

Each of these tracking IDs is registered using a property in your Coveo organization to ensure that the data is correctly sent:

  • Barca Sports US

  • Barca Sports CA

  • Barca Parts US

  • Barca Parts CA

Important

  • The trackingId parameter can only contain lowercase letters, numbers, and underscores (_), such as barca_sports_us1.

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

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

In the script in the introduction, replace <YOUR_STOREFRONT> with your tracking ID to ensure that analytics across multiple digital experiences are properly tracked.

User authentication

In the script in the introduction, replace <COVEO_API_KEY_OR_SEARCH_TOKEN> with an API key that was created using the Anonymous search template or a search token that grants the Push access level on the Analytics Data domain in the target organization. To use that same search token for your search interface as a whole, also grant it the Allowed access level on the Execute Queries domain privilege.

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 Platform endpoint for your organization.

Coveo Endpoint

prod

https://<ORG_ID>.analytics.org.coveo.com

HIPAA

https://<ORG_ID>.analytics.orghipaa.coveo.com

Where <ORG_ID> is the unique identifier of your Coveo organization.