---
title: Log view events
slug: '2651'
canonical_url: https://docs.coveo.com/en/2651/
collection: build-a-search-ui
source_format: adoc
---
# Log view events

Any page that you want a recommendation interface to recommend typically logs a view [event](https://docs.coveo.com/en/260/) every time it's opened.
Although view events aren't currently available for [Coveo Analytics reports](https://docs.coveo.com/en/266/), they're required to feed [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [Content Recommendation (CR)](https://docs.coveo.com/en/1016/) [models](https://docs.coveo.com/en/1012/).

This article provides guidelines for performing HTTP requests against the [Usage Analytics (UA) Write API](https://docs.coveo.com/en/18/) to properly log view events.

> **Important**
>
> The information in this article is only relevant when you can't (or choose not to) [use the Coveo UA library](https://docs.coveo.com/en/1818/) to send view events to the [Coveo Platform](https://docs.coveo.com/en/186/).
> This library will handle all of the HTTP requests for you.

To log a view event, make a POST request to

[source,text,subs="attributes+"]
```
https://<ORG_ID>.analytics.org.coveo.com/rest/ua/v15/analytics/view
```

where `<ORG_ID>` is the unique identifier of your [Coveo organization](https://docs.coveo.com/en/185/).

In the HIPAA environment, use:

[source,text,subs="attributes+"]
```
https://<ORG_ID>.analytics.orghipaa.coveo.com/rest/ua/v15/analytics/view
```

> **Note**
>
> In either case, under the hood, Coveo will use the [organization endpoints](https://docs.coveo.com/en/mcc80216/) to redirect your requests to the target region.

Use an access token with the [privilege](https://docs.coveo.com/en/228/) to push [Coveo Analytics data](https://docs.coveo.com/en/259/) (that is, the **Allowed** [access level](https://docs.coveo.com/en/2818/) on the [**Analytics data**](https://docs.coveo.com/en/1707#analytics-data-domain) [domain](https://docs.coveo.com/en/2819/)).

## Example

In the following request, only the body properties which are required by the Coveo UA and Coveo ML services are included.
In this example, even though the `username` is required, it's not included because it's extracted from the [search token](https://docs.coveo.com/en/1346/).
If another authentication method was used, the `username` field would need to be included in the request body.

[source,http,subs="attributes+"]
```
POST https://myorganizationid9sd8df7s.analytics.org.coveo.com/rest/ua/v15/analytics/view HTTP/1.1
​
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

Payload:

```json
{
  "language": "en",
  "clientId": "489aa3e3-aed2-4563-8e81-62bb73178a56",
  "location": "https://docs.coveo.com/en/1243/",
  "contentIdKey": "permanentid",
  "contentIdValue": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960"
}
```

## Required request body property

The following property is required by the UA Write API when logging a view event.

### `location` (string)

The URL of the viewed page or component, usually `document.location.href`.
Maximum: 1024 characters.

Coveo ML uses this parameter for debugging purposes.

```json
{
  ...
  "location": "https://docs.coveo.com/en/1243/",
  ...
}
```

## Coveo ML-required request body properties

The following properties aren't required by the UA Write API when logging a view event, but they're required when using the Coveo ML service (otherwise, Coveo ML models won't function properly).

### `contentIdKey` (string)

The name of a field in the index that uniquely identifies the item.
Maximum: 128 characters.

A good practice is to use the [`permanentid`](https://docs.coveo.com/en/1913/) field.

CR models use this parameter to match the viewed page or component with the corresponding item in the index.

```json
{
  ...
  "contentIdKey": "permanentid",
  ...
}
```

### `contentIdValue` (string)

The value of the field selected as `contentIdKey`.
This must not contain any of the following characters: `{`, `}`, or `:`.
Maximum: 512 characters.

This is generally the `permanentid` value in the index.

Coveo ML CR models use this parameter to match the viewed page or component with the corresponding item in the index.

```json
{
  ...
  "contentIdValue": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960",
  ...
}
```

### `language` (string)

The language of the recommendation interface from which the view event originates.
Maximum: 256 characters.

This value must be an [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) code, and it must match the first part of the `locale` value in the request body of the corresponding query to the Search API.

Coveo ML builds an independent CR submodel for each `language` value.

```json
{
  ...
  "language": "en",
  ...
}
```

### `username` (string)

The name of the [user](https://docs.coveo.com/en/250/) [security identity](https://docs.coveo.com/en/240/) which
caused the search interface to log a view event.
Maximum: 128 characters.
This can only be specified when authenticated with an API key that was created using the **Authenticated search** [template](https://docs.coveo.com/en/1718#api-key-templates) or an [OAuth2 token](https://docs.coveo.com/en/1369/) with the privilege to [impersonate](https://docs.coveo.com/en/2737/) users (that is, the **Allowed** access level on the [**Impersonate** domain](https://docs.coveo.com/en/1707#impersonate-domain-analytics)).

> **Important**
>
> A private API key or an OAuth2 token with the privilege to impersonate users shouldn't be exposed publicly.

If `username` isn't specified and the request is authenticated with a search token, the service tries to extract the `username` value from the access token that authenticated the log search event request.
If this fails, `username` is left blank.

If this isn't specified and the request is authenticated with an API key, `username` is set to `anonymous`.

> **Note**
>
> When the request is [authenticated](https://docs.coveo.com/en/2120/) with a [search token](https://docs.coveo.com/en/1346/), and the `username` is extracted from the token, the `username` value won't appear in the event content of the [Event browser](https://docs.coveo.com/en/n3re0108/).
> To retrieve this value, you'll need to [query the Snowflake database](https://docs.coveo.com/en/n1cd0393#user-name) where the `username` value is stored.
> This is the only way to reference the `username` associated with view events when using search token authentication.

Coveo ML CR models use `username` to build user profiles and provide user-based recommendations.

```json
{
  ...
  "username": "alice.smith@example.com",
  ...
}
```

## Coveo ML-optional request body properties

The following properties aren't required by either the UA Write API or Coveo ML service when logging search events.
However, specifying values for these properties may improve the effectiveness of Coveo ML.

### `contentType` (string)

The type of content on the page.
Maximum: 128 characters.

When creating a CR model, it's possible to select the specific `contentType` values you want to recommend (see [Recommendation content types](https://docs.coveo.com/en/1744/)).

```json
{
  ...
  "contentType": "Docs",
  ...
}
```

### `outcome` (integer from `-5` to `5`)

An indication of the quality of the outcome of this event.
A value of `-5` corresponds to the worst possible outcome, a value of `0` corresponds to a neutral outcome, and a value of `5` corresponds to the best possible outcome.

The `outcome` property will eventually be leveraged by the Coveo ML service.

```json
{
  ...
  "outcome": 0,
  ...
}
```

### `title` (string)

The title of the item.
Maximum: 256 characters.

Coveo ML uses this parameter for debugging purposes.

```json
{
  ...
  "title": "Coveo for Salesforce",
  ...
}
```

## Optional request body properties

The following properties are entirely optional when logging view events.
Although they're not leveraged by the Coveo ML service nor are they currently available for reporting, you may want to log them because they will eventually be available for reporting.

### `anonymous` (Boolean)

Whether the navigation that caused the search interface to log a view event was triggered by an anonymous user.
The default value is `false`.

If the user is authenticated but wants to be anonymous, set `anonymous` to `true`.
The UA Write API won't extract the `name` and `userDisplayName`, if present, from the search token.
As long as you don't include their identity elsewhere in your request, the user will remain anonymous.

```json
{
  ...
  "anonymous": false,
  ...
}
```

### `originContext` (string)

The origin of the event.
This is used to specify the deployment from which the user performs the action.
Maximum: 128 characters.
Suggested values are `Search`, `InternalSearch`,
`CommunitySearch`, or the `originLevel1` value.

```json
{
  ...
  "originContext": "CommunitySearch",
  ...
}
```

### `originLevel1` (string, optional)

The name or identifier of the search interface from which the view event originates.
Maximum: 128 characters.

If `[originLevel1](https://docs.coveo.com/en/1337/)` isn't specified and the request is authenticated with a search token, the service tries to extract the `[searchHub](https://docs.coveo.com/en/1342/)` value from the access token that authenticated the request to log a search event (see [Set the Search Hub](https://docs.coveo.com/en/365#set-the-search-hub)).

> **Important**
>
> Coveo ML models use the `originLevel1` value as a default filter field.
> These filters don't affect how the models learn, but they must be logged correctly for recommendations to work.
> When Coveo ML models make suggestions, items which don't meet the right filters are ignored (see [Get query suggestions - Troubleshooting](https://docs.coveo.com/en/1459#troubleshooting)).

```json
{
  ...
  "originLevel1": "ExternalSearch",
  ...
}
```

### `originLevel2` (string)

The name or identifier of the [tab](https://docs.coveo.com/en/1406/) from which the view event originates.
Maximum: 128 characters.

```json
{
  ...
  "originLevel2": "All",
  ...
}
```

### `[originLevel3](https://docs.coveo.com/en/1339/)` (string)

The URL of the page that redirected the browser to the
page
from which the view event originates (that is, `document.referrer`). Maximum: 128 characters.
```json
{
  ...
  "originLevel3": "https://connect.coveo.com/s/search/All/Home/%40uri",
  ...
}
```

### `[referrer](https://docs.coveo.com/en/1344/)` (string)

The URL of the page that redirected the browser to the page from which the view event originates, that is, `document.referrer`.

```json
{
  ...
  "referrer": "https://connect.coveo.com/s/search/All/Home/%40uri",
  ...
}
```

> **Note**
>
> `originLevel3` and `referrer` fulfill the same purpose.
> While both properties are exposed for legacy reasons, the best practice is to use `originLevel3`.

### `splitTestRunName` (string)

The name of the [A/B test](https://docs.coveo.com/en/3255/) to run, if one is active.
Maximum: 128 characters.

```json
{
  ...
  "splitTestRunName": "splitTest",
  ...
}
```

### `splitTestRunVersion` (string)

The version of the A/B test to run, if one is active.
Maximum: 128 characters.

```json
{
  ...
  "splitTestRunVersion": "splitTestRunAlpha",
  ...
}
```

### `trackingId` (string)

The value to identify which web property an event is related to.
This is a human-readable name you can use when sending analytics events.

```json
{
  ...
  "trackingId": "online_store",
  ...
}
```

### `userAgent` (string)

Information about the browser and operating system of the user who
navigated to the page that
caused the search interface to log a view event.
Maximum: 1024 characters.

> **Note**
>
> If the client performs HTTP requests directly against the UA Write API to log events (rather than performing those requests through a proxy server), the user's browser will typically include the correct information in the `User-Agent` request header.
> In this case, it's not necessary to specify a value for the `userAgent` request body property.

```json
{
  ...
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.181 Safari/537.36",
  ...
}
```

### `userDisplayName` (string)

The display name of the user performing the view event.
Maximum: 128 characters.

If `userDisplayName` isn't specified and the request is authenticated with a search token, the service tries to extract the `userdisplayName` value from the access token that authenticated the request to log a view event.

```json
{
  ...
  "userDisplayName": "Alice",
  ...
}
```

## View event `customData` (key-value pairs)

These are custom key-value pairs which can contain all of the user-defined [dimensions](https://docs.coveo.com/en/258/) and their values, and which can be used for reporting or learning.

* The `customData` section must be valid JSON.

* When possible, use a string as the value.

* The value can be any valid JSON, but it's handled as string over [Coveo Analytics](https://docs.coveo.com/en/182/), and the string conversion could result in the alteration of the original JSON.
Keys may only contain alphanumeric or underscore characters, and all spaces in the keys are replaced with underscores.
Any uppercase characters in the keys are converted to lowercase characters.

**Examples**

* `"key" : "value"` → This is the recommended format for [Coveo Analytics](https://docs.coveo.com/en/182/), which renders the string as `"value"` and makes it usable as any other string [dimension](https://docs.coveo.com/en/258/) type.

* `"key" : [ "value_1", "value_2" ]` → This becomes the string `"[ "value_1", "value_2" ] "` within [Coveo Analytics](https://docs.coveo.com/en/182/).
Although it's harder to use for reporting, this value could still be useful (for example, when using the filter `"contains"` type).

* Any [field](https://docs.coveo.com/en/200/) beginning with `context_` will be used by [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) as user [context](https://docs.coveo.com/en/1345/) to learn and provide boosts to contextually relevant [items](https://docs.coveo.com/en/210/).

> **Note**
>
> When reporting on view events becomes possible, we will recommend that you [create your custom dimension](https://docs.coveo.com/en/1522/) before adding `customData`.

```json
{
  ...
  "customData":{
    "context_usertype" : "Guest"
  },
  ...
}
```