---
title: Event Protocol
slug: o3r90189
canonical_url: https://docs.coveo.com/en/o3r90189/
collection: build-a-search-ui
source_format: adoc
---
# Event Protocol
The [Event Protocol](https://docs.coveo.com/en/o9je0592/) is a new standard for sending [Coveo Analytics events](https://docs.coveo.com/en/260/) to Coveo.

> **Important**
>
> The [Event Protocol](https://docs.coveo.com/en/o9je0592/) and [Coveo Relay library](https://docs.coveo.com/en/o9je0322/) are generally available for Commerce.
> 
> However, they're in closed beta for Coveo for Service, Website, and Workplace implementations.
> If you're interested in using the Event Protocol and Relay library for these implementations, contact your customer success manager (CSM).

We highly recommend using [Coveo Atomic](https://docs.coveo.com/en/lcdf0264/), [Coveo Headless](https://docs.coveo.com/en/lcdf0493/) or [Coveo Relay](https://docs.coveo.com/en/relay/latest/), which wrap the complexity of the Event API, over using the Event API directly.

## Search events

The Event Protocol doesn't require you to log search events.
When you send search requests to the [Search API](https://docs.coveo.com/en/13#tag/Search-V2/operation/searchUsingPost) or the [Commerce API](https://docs.coveo.com/en/103#tag/Search/operation/search), the API automatically logs the corresponding search events server-side.

[Coveo Headless](https://docs.coveo.com/en/lcdf0493/) and [Atomic](https://docs.coveo.com/en/lcdf0264/) use the Event Protocol by default as of v3, activating server-side logging of search events automatically.

### Commerce API server event logging

You can also activate server-side event logging in the Commerce API by setting the [`context.capture`](https://docs.coveo.com/en/103#operation/search-context) parameter to `true` in your commerce queries.

```json
{
  ...
  "context": {
    ...
    "capture": true, <1>
  }
}
```
<1> Activates server-side event logging.

> **Note**
>
> The `context.capture` parameter is currently `true` by default, but it will be `false` by default in a future release.

### Search API server event logging

You can activate server-side event logging in the Search API by setting the [`analytics.capture`](https://docs.coveo.com/en/13#operation/searchUsingPost-analytics-capture) parameter to `true` in your search requests.

If you do so, be sure to set the `analytics.actionCause` parameter.
See [Standard actions and UA reference](https://docs.coveo.com/en/1389/).

For reporting purposes, also provide as many parameters exposed in the [`analytics`](https://docs.coveo.com/en/13#operation/searchUsingPost-analytics) object as possible.

**Example:**

```json
{
  ...
  "analytics": {
    "capture": true, <1>
    "actionCause": "searchboxSubmit", <2>
    "clientId": "9dn3nd88-75ea-3b8d-93nq-1208a732cafc", <3>
    "clientTimestamp": "2024-04-10T14:01:28.026Z",
    "documentReferrer": "default",
    "originContext": "Search",
    "documentLocation": "https://sports.barca.group/search",
    "documentReferrer": "default",
    "originContext": "Search"
  }
}
```
<1> Activates server-side event logging.
<2> Sets the action cause as specified in [Standard actions and UA reference](https://docs.coveo.com/en/1389/).
<3> Additional parameters for reporting purposes.

## Opting-in or out of tracking

You may need to provide users with the ability to opt-in or out of tracking, following the applicable privacy regulations (see [Data tracking](https://docs.coveo.com/en/3348/)).

### Server events

When you want to prevent search events from being used for analytics purposes, set the `capture` parameter to `false` in your search requests.
When using the Commerce API, that's the [`context.capture`](https://docs.coveo.com/en/103#operation/search-context) parameter, while in the Search API, it's the [`analytics.capture`](https://docs.coveo.com/en/13#operation/searchUsingPost-analytics-capture) parameter.
Also, don't send any data persisted in the browser, such as `clientId`, since it would constitute tracking.

**Commerce API example**

```json
{
  ...
  "context": {
    "capture": false,
    ...
  }
}
```

**Search API example**

```json
{
  ...
  "analytics": {
    "capture": false,
    ...
  }
}
```

> **Note**
>
> If you're using the [Coveo Headless](https://docs.coveo.com/en/lcdf0493/) Commerce controllers, see [Disable and enable analytics](https://docs.coveo.com/en/headless/latest/usage/headless-usage-analytics/headless-ep#disable-and-enable-analytics).

### Client events

Disabling and enabling client-side event logging depends on your implementation.

If you're using Relay, see [Relay: Opting-in or out of tracking](https://docs.coveo.com/en/relay/latest/usage#opting-in-or-out-of-tracking).

If you're using the [Coveo Headless](https://docs.coveo.com/en/lcdf0493/), see [Disable and enable analytics](https://docs.coveo.com/en/headless/latest/usage/headless-usage-analytics/headless-ep#disable-and-enable-analytics).

If you're using the Event API directly, make sure that your implementation logs events only after users have consented, or haven't opted out of tracking, depending on the applicable privacy law.

## What's next?
If you're using the Event Protocol for a commerce implementation, see [Event Protocol for commerce](https://docs.coveo.com/en/o1n91230/).

To track events using the Relay library, see the [Relay library documentation](https://docs.coveo.com/en/relay/latest/).