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:
-
Access the Catalogs page.
-
Click the catalog for which you want to create an API key, and then click Create API Key in the Action bar.
-
Select an 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 |
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) |
|
prod-eu (Europe) |
|
prod-au (Australia) |
|
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.