Initialize the Coveo Analytics JavaScript

You must include the following script tag to load the coveo.analytics library into your 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 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
coveoua('init', <SEARCH_TOKEN/COVEO_API_KEY>, <ENDPOINT>);
</script>

Authentication credentials need to be passed in the form of an API key or search token to the COVEO_API_KEY value.

Currency Code

Replace CURRENCY_CODE with the three-letter currency code following the ISO 4217 standard to identify a user’s currency (e.g.: USD).

API Key for Analytics

Replace the COVEO_API_KEY parameter with an API key for Analytics created for your catalog. This will automatically pass your catalog ID in your commerce events, so that you can track them in usage analytics dashboards. The collected events are then sent to machine learning models which help harmonize the results returned to the customers.

OR

Replace the SEARCH_TOKEN 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 you use the Impersonate domain in the Analytics service, linked above. Don’t use the Impersonate domain in the Search Service as it will allow users to send queries under any identity.

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

  1. Access the Catalogs page.

  2. Click the catalog for which you want to create an API key, and then click Create API Key in the Action bar.

  3. Select an API Key for Analytics.

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

Coveo UA Alternate Endpoints

To log usage analytic 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.

When initializing the library you will need to specify the Coveo endpoint for your region coveoua('init', <COVEO_API_KEY>, <ENDPOINT>)

Coveo Endpoint

prod-us (US - default)

https://analytics.cloud.coveo.com/rest/ua

prod-eu (Europe)

https://analytics-eu.cloud.coveo.com/rest/ua

prod-au (Australia)

https://analytics-au.cloud.coveo.com/rest/ua

HIPAA

https://analyticshipaa.cloud.coveo.com/rest/ua

User Authentication

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. Setting a value in the userId field, such as asmith@example.ca will log the event under that specific identity. Leaving the userId field empty will log the event under an anonymous identity.

Use a Search Token

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

The search token is used during the initialization of the script. Replace the COVEO_API_KEY value specified in the Initialize the Script section.

The userId field is ignored at all times 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 what follows for an authenticated user (replace asmith@example.com with the actual email of the user for whom you are requesting a search token):

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

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

What's Next for Me?