Log Collect events

This is for:

Developer

What’s the Collect endpoint?

The Coveo Collect endpoint offers a new generic way to collect and track events instead of using the older /search, /searches, /click, /custom, and /view Usage Analytics (UA) Write API endpoints.[1] It lets you capture all a user’s interactions with a Coveo-powered website or application, without requiring any event states to be retained on the client side.

As a developer, you can use the Collect endpoint to associate interactions with a website or application in a specific context, even if the user journey is non-linear and includes multiple search events or spans multiple browser tabs. This raw user interaction data can then be leveraged in reports which allow stakeholders to better understand how users are interacting with their business.

To use the Collect endpoint, make a POST request with the user interaction data in JSON format.

Example
POST https://platform.cloud.coveo.com/rest/ua/v15/analytics/collect HTTP/1.1
Authorization: Bearer ********-****-****-************

Payload:

{
  "v": "1",
  "tid": "mycoveoorganizationg8tp8wu3",
  "cid": "35009a79-1a05-49d7-b876-2b884d0f825b",
  "uid": "as8eknlll",
  "pid": "5fa524ac-dbe1-4a15-af17-b69cfbd6cafc",
  "uip": "1.2.3.4",
  "t": "pageview",
  "dr": "http://example.com",
  "dl": "http://example.com/added-to-my-cart/651792_00099999910000025592",
  "dt": "Added to my cart",
  "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.105 Safari/537.36",
  "ul": "en-US"
}

When should I use the Collect endpoint?

The Collect endpoint can deterministically link non-linear events within their own specific contexts. The Collect endpoint supports both Case Assist and Commerce events. As a developer, you should use it whenever you need to associate user interactions that happen in or out of a Coveo-powered website or application.

Tip
Leading practice

We recommend using the Coveo analytics library to log Commerce events, rather than doing so directly through the Collect endpoint API. This library handles a lot of the complexity for you, and you should use it unless you have good reasons not to (for example, if you can’t run JavaScript in your application).

The Collect endpoint has three main benefits over the older UA Write API endpoints:

  • It supports multiple objects per action or event.

  • It’s easier to implement without using the Coveo JavaScript Search Framework.

  • It lets you track events even before you implement Coveo search components on a website or application.

The Collect endpoint is flexible and gives you the freedom to emit an event as long as the data layer has the required data. You can use it in standard server-side rendered websites, or in dynamic progressive web application (PWA) and single-page application (SPA) environments.

For example, when a user opens a product detail page in a dynamic commerce application, you can emit a pageview hit before sending an event hit with the detail product action. On a standard website, you can track the same interactions with the Collect endpoint by emitting a single pageview hit with the detail product action.

Example

A user accesses an SPA ecommerce website to find some shoes. A pageview hit is sent. The user searches for "red running shoes" and several results are returned. This sends an event hit with the impression product action. The user clicks a pair that they like, which sends an event hit with the click product action.

After the click, the user is redirected to a page which provides detailed product information. A new pageview hit with the detail product action is sent.

After taking a closer look at the shoes and reading some reviews on the product page, the user decides that this is the right pair for them. They click the Add to Cart button, which sends an event hit with the add product action.

Finally, the user completes the purchase. This sends an event hit with the purchase product action.

Usage

To use the Collect endpoint, make a POST request with the user interaction data in JSON format.

Example
POST https://platform.cloud.coveo.com/rest/ua/v15/analytics/collect HTTP/1.1
Authorization: Bearer ********-****-****-************

Payload:

{
  "v": "1",
  "tid": "mycoveoorganizationg8tp8wu3",
  "cid": "35009a79-1a05-49d7-b876-2b884d0f825b",
  "uid": "as8eknlll",
  "pid": "5fa524ac-dbe1-4a15-af17-b69cfbd6cafc",
  "uip": "1.2.3.4",
  "t": "pageview",
  "dr": "http://example.com",
  "dl": "http://example.com/added-to-my-cart/651792_00099999910000025592",
  "dt": "Added to my cart",
  "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.105 Safari/537.36",
  "ul": "en-US"
}
Note

Coveo stores all parameters by default, including those that aren’t listed below. If you store custom parameters, it’s best to use the custom parameter to store them. This will keep you from running into a conflict as Coveo expands its list of parameters.

Reference

General

v (string, required)

The protocol version for all hit types. The current value is 1.

Example: "v": "1"

tid (string, required)

The unique organization ID automatically generated for a Coveo organization based on its name, used for configuration and identification purposes. Maximum: 128 bytes. For more information, see Find your organization ID.

Example: "mycoveoorganization8tp8wu3"

aip (boolean, optional)

Whether the IP address of the sender is anonymized.

For example, the IP is anonymized if any of the following parameters are present in the payload: &aip=, &aip=0, or &aip=1.

Note

Coveo always anonymizes the IP by using a non-reversible hash and ignoring this parameter. The hash is performed in the same way as UA events. For more information, see the UIP parameter.

npa (boolean, optional)

Whether an event is marked as disabled for advertising personalization, including for events from a property with a setting that otherwise permits ads personalization.

For example, if a transaction is marked to disable advertising personalization, it won’t be used when populating a remarketing audience for "past purchasers".

Note

Coveo doesn’t use this parameter and ignores it.

ds (string, optional)

Indicates the data source of the hit.

Example: "ds": "web"

Note

Coveo doesn’t use this parameter and ignores it.

qt (integer, optional)

Collects offline and latent hits.

Represents the time delta (in milliseconds) between the hit occurrence and the moment the hit was sent. The value must be greater than or equal to 0.

Notes

  • A value greater than four hours may lead to the hit not being processed.

  • Coveo doesn’t use this parameter and ignores it.

searchHub (string, optional)

Indicates the name or identifier of the search interface from which the query originated. Maximum: 128 characters.

When specified, the originLevel1 field of the corresponding event is populated with identical data.

Note

For case assist, as a best practice, we recommend specifying the searchHub.

tab (string, optional)

Indicates the name or identifier of the selected tab from which the query originated. When specified, the originLevel2 field of the corresponding event is populated with identical data.

z (string, optional)

Sends a random number in GET requests to ensure browsers and proxies don’t cache hits. This value isn’t used in reporting.

context_website deprecated (string, optional)

Warning

The customData.context_website has been deprecated in favour of trackingId since version 2.28.15 of the Coveo analytics library. Any implementations using context_website, will automatically map that value to trackingId.

Identifies analytics coming from a product discovery experience. If you own multiple ecommerce storefronts, use this field to differentiate them.

trackingId (string)

Note

Available on version 2.28.15 of the Coveo analytics library and greater.

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

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

contentId (string, optional)

Indicates the value of the field selected as contentIdKey.

contentIdKey (string, optional)

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

contentType (string, optional)

Indicates the type of content in the item. Maximum: 128 characters.

tm (integer, optional)

Indicates the Unix timestamp of an event. It’s used to analyze the timing of events as well as event sequences and trends over time.

"Example: "tm": "1689674670262"

rankingModifier (string, optional)

Indicates the ranking modifier that affected the result ranking. Should match the value of the rankingModifier field of the result in the Search API response.

Example: "rankingModifier": "Reveal ART"

Note

Only sent when logging a collect click event.

User

cid (string, required)

Required if the UIP isn’t specified in the request. It pseudonymously identifies a particular browser or app instance.

Note

The cid must be a valid UUID as it identifies an anonymous browser on a certain website.

For example, when a user visits the same website twice with the same browser, they’re assigned the same client_id in addition to the visitor ID. A different website using the same browser results in a different cid.

If not specified, the UA visitor cookie behavior is considered instead and the cid becomes the visitor ID value. This ensures compatibility with UA events in the case of a hybrid implementation, but this approach isn’t recommended, due to the upcoming third-party cookie deprecation.

uid (string, optional)

Represents the user ID and identifies a user through the credentials used to log in to a certain website (for example, the user’s hashed email address). Maximum: 128 characters.

It works in the same way as the username property. For more information, see User Authentication.

Session

sc (string, optional)

Controls the session duration. Values of start and end are used.

Note

The Coveo visit duration is 30 minutes by default, the same as a user visit in UA events. Therefore, Coveo ignores this parameter and always uses a 30-minute session.

uip (string, optional)

Represents the IP address of the user.

When specified, Coveo uses this IP address. Otherwise, it uses the IP address from the request, the same as UA events. In the UA report, an IP address from the Collect endpoint or a UA event is hashed in the same way (results into the same non-reversible hash value).

The following dimensions are determined with the IP address: City, Country, and Region. For more information about IP addresses, see Analytics Data.

ua (string, optional)

Represents the user agent of the browser. Maximum: 1024 characters.

It works in the same way as userAgent in UA events.

geoid (string, optional)

Provides the geographical location of the user. The geographical ID should be a two-letter country code or a criteria ID representing a city or region.

Examples: geoid=US, geoid=21137

Note

Coveo ignores this parameter and relies on the uip to perform geolocalization.

Traffic sources

dr (string, optional)

Specifies the document referral source which brought traffic to a website. Maximum: 2048 bytes.

It’s also used to compute the traffic source and works in the same way as originLevel3 in UA events.

Example: "dr=http%3A%2F%2Fexample.com"

Note

The URL must comply with W3 specifications.

cn (string, optional)

Specifies the campaign name. Maximum: 100 bytes.

Note

Coveo doesn’t use this parameter and ignores it.

cs (string, optional)

Specifies the campaign source. Maximum: 100 bytes.

Note

Coveo doesn’t use this parameter and ignores it.

cm (string, optional)

Specifies the campaign medium. Maximum: 100 bytes.

Note

Coveo doesn’t use this parameter and ignores it.

ck (string, optional)

Specifies the campaign keyword. Maximum: 500 bytes.

Note

Coveo doesn’t use this parameter and ignores it.

cc (string, optional)

Specifies the campaign content. Maximum: 500 bytes.

Note

Coveo doesn’t use this parameter and ignores it.

ci (string, optional)

Specifies the campaign ID. Maximum: 100 bytes.

Note

Coveo doesn’t use this parameter and ignores it.

gclid (string, optional)

Specifies the Google Ads ID.

Note

Coveo doesn’t use this parameter and ignores it.

dclid (string, optional)

Specifies the Google Display Ads ID.

Note

Coveo doesn’t use this parameter and ignores it.

System info

sr (string, optional)

Specifies the screen resolution. Maximum: 20 bytes.

It must use the following format: <INTEGER>x<INTEGER>. Both integers have a positive value (for example, 1280x1024). The x isn’t case-sensitive and a space is allowed before and after.

vp (string, optional)

Specifies the viewport size of the browser or device. Maximum: 20 bytes.

Note

Coveo doesn’t use this parameter and ignores it.

de (string, optional)

Specifies the character set used to encode the page or the document. Maximum: 20 bytes.

sd (string, optional)

Specifies the screen color depth. Maximum: 20 bytes.

ul (string, optional)

Specifies the locale setting of the user’s browser. Maximum: 20 bytes. Automatically sent using Coveo’s libraries and is specified with ISO-639 standards (for example, en-us).

Notes

  • The user locale specifies the default settings determined by the user’s chosen formatting standards. These settings format variables such as date, time, or currency.

  • In the Google Analytics Measurement Protocol , ul is known as the user language.

je (string, optional)

Specifies if Java is enabled.

Note

Coveo doesn’t use this parameter and ignores it.

fl (string, optional)

Specifies the flash version. Maximum: 20 bytes.

Note

Coveo doesn’t use this parameter and ignores it.

Hit

A hit refers to a single interaction that sends data to a tracking server. This interaction could be a page view, a click event, or a search event, among others. Each hit contains various parameters like t, pa, and il1nm to specify the type and details of the interaction

t (string, required)

This must be one of the following: pageview, screenview, event, transaction, item, social, or timing. The Collect event is converted to a UA event based on this value.

The original event from the Collect endpoint is then stored as a UA event as custom_datas, under the c_original_event_data attribute name. UA dimensions can be then used to access those parameters over UA reports.

Either a click or a search event is logged depending on the parameter values:

Event t pa pal or il1nm

click

"event"

"click"

pal starts with "coveo:searchid:"

click

"event"

"quickview"

pal starts with "coveo:searchid:"

search

"event"

"impression"

il1nm starts with "coveo:searchid:"

Click event example:

{
  "t": "event",
  "pa": "click",
  "pal": "coveo:searchid:12345"
}

Search event example:

{
  "t": "event",
  "pa": "impression",
  "il1nm": "coveo:searchid:67890"
}
Notes

  • A pageview hit works in the same way as a UA view event with a product action.

  • All other hits are equivalent to a UA custom event and are converted accordingly.

ni (string, optional)

Specifies if a hit is non-interactive.

Note

Coveo doesn’t use this parameter and ignores it.

Content information

pid (string, required)

Identifies a page or a web page in the case of a web application.

When a web page loads, a new pid is generated and is used by all events occurring over this web page. The page ID allows all events occurring concurrently over different pages to be linked together with proper context.

Note

The pid must be a valid UUID.

dl (string, required)

Sends the document location URL of the page on which the content resides. Maximum: 2048 bytes.

You can use the dh and dp parameters to override the host name, path, and query portions of the document location accordingly. Based on the event type, the document URL is converted to either a view, search, or click event.

Note

The URL must comply with W3 specifications.

dh (string, optional)

Specifies the document host name from which the content is hosted. Maximum: 2048 bytes. If converted to a UA view event and the dl is empty, then the location becomes the concatenation of the dh and dp parameters.

If the host doesn’t include the protocol (for example, http), then it will be https:// + dh + dp.

dp (string, optional)

Represents the document path portion of the page URL.

It should begin with /. For pageview hits, either dl, or both dh and dp must be specified for the hit to be valid.

Maximum: 2048 bytes.

dt (string, optional)

Represents the document title. Maximum: 1500 bytes.

If converted to a UA click event, it becomes documentTitle.

cd (string, required)

Required for mobile properties for screenview hits. Maximum: 2048 bytes.

Note

This parameter is optional on web properties since it defaults to the unique URL of the page by either using the dl parameter as is, or by assembling it from the dh and dp.

cg<groupIndex> (string, required)

Represents the content group. Maximum: 100 bytes. It can have up to five content groupings, each of which has an associated index between 1 and 5, inclusive.

Notes

  • Each content grouping can have up to 100 content groups. The value of a content group is hierarchical text delimited by /. All leading and trailing slashes are removed and any repeated slashes are reduced to a single slash. For example, /a//b/ is converted to a/b.

  • The first two content groupings will be assumed to override the searchHub and tab values.

linkid (string, required)

Represents the ID of a clicked DOM element. It’s used to disambiguate multiple links to the same URL in analytics reports when enhanced link attribution is enabled.

Apps

an (string, required)

Specifies the application name. Maximum: 100 bytes.

Note

This parameter is optional for hits sent to web properties.

aid (string, required)

Represents the application identifier. Maximum: 150 bytes.

av (string, optional)

Specifies the application version. Maximum: 100 bytes.

aiid (string, optional)

Specifies the application installer ID. Maximum: 150 bytes.

Events

ec (string, required)

Specifies the event category. Maximum: 150 bytes.

ea (string, required)

Specifies the event action. Maximum: 500 bytes.

If converted to a UA click event, it becomes a click actionCause.

el (string, optional)

Specifies the event label. Maximum: 500 bytes.

ev (integer, optional)

Specifies the event value.

Note

Values must be non-negative.

Ecommerce

ta (string, optional)

Specifies the affiliation or a store name. Maximum: 500 bytes.

tr (Currency, Optional)

Specifies the total revenue associated with the transaction. This value should include shipping or tax costs.

ts (currency, optional)

Specifies the total shipping cost of the transaction.

tt (currency, optional)

Specifies the total tax of the transaction.

in (string, optional)

Specifies the item name. Maximum: 500 bytes.

ip (currency, optional)

Specifies the price for a single item or unit.

iq (integer, optional)

Specifies the number of items purchased.

ic (string, optional)

Specifies the SKU or item code. Maximum: 500 bytes.

iv (string, optional)

Specifies the item category. Maximum: 500 bytes.

Product

pa (string, optional)

Represents the role of the products included in a hit.

Note

If a product action isn’t specified, all product definitions included in the hit are ignored. The action must be one of the following: detail, click, add, remove, checkout, checkout_option, purchase, or refund.

ti (string, optional)

Represents the transaction ID.

This is an additional parameter that can be sent when pa is set to purchase or refund.

ta (string, optional)

Represents the store or the affiliation where the transaction occurred.

This is an additional parameter that can be sent when pa is set to purchase or refund.

tr (currency, optional)

Represents the total value of the transaction, including shipping and taxes.

This is an additional parameter that can be sent when pa is set to purchase or refund. If not sent, this value is automatically calculated using the product quantity and price fields of all products within the same hit.

tt (currency, optional)

Represents the total tax associated with the transaction.

This is an additional parameter that can be sent when pa is set to purchase or refund.

ts (currency, optional)

Represents the total shipping cost associated with the transaction.

This is an additional parameter that can be sent when pa is set to purchase or refund.

tcc (string, optional)

Represents the coupon redeemed with the transaction.

This is an additional parameter that can be sent when pa is set to purchase or refund.

pal (string, optional)

Represents the list or collection in which a product action occurred.

This is an additional parameter that can be sent when the product action is set to detail or click.

Note

Coveo only supports this parameter when the event is related to a UA click event. In that case, it references a UA search ID prefixed with coveo:search.

cos (integer, optional)

Represents the checkout step.

This is an additional parameter that can be sent when the product action is set to checkout.

col (string, optional)

Represents any additional information about a checkout step.

This is an additional parameter that can be sent when the product action is set to checkout.

promoa (string, optional)

Specifies the role of the promotions included in a hit.

If a promotion action isn’t specified, the default promotion action, view, is assumed. To measure a user click on a promotion, set this action to promo_click.

cu (string, optional)

Indicates the local currency for all transaction currency values. Maximum: 50 bytes.

Notes

  • The currency code isn’t case-sensitive. It’s based on ISO-4217, so it’s usually a 3-letter code (for example, euro = EUR).

  • The code is optional when there’s nothing over the event referencing the currency value (for example, price), but it’s mandatory over any event involving currency values (for example, adding a product to cart with a specified price (prNpr)).

Product index

Product indexes must start with 1 and increase in increments of 1. Events that involve multiple products (1 to N) are split into 1 to N UA events (for example, click events), one for each product. However, each of these events contains the original Collect event with all products as part of the custom_datas (under the c_original_event_data attribute).

pr<productIndex>id (string, required)

Represents the product ID of a product stored in the index.

The product index must be a positive integer between 1 and 200, inclusive.

pr<productIndex>nm (string, required)

Represents the product name.

The product index must be a positive integer between 1 and 200, inclusive.

pr<productIndex>br (string, optional)

Represents the brand associated with the product.

The product index must be a positive integer between 1 and 200, inclusive.

pr<productIndex>ca (string, required)

Represents the product category.

The product index must be a positive integer between 1 and 200, inclusive. It can be hierarchical and you can use / as a delimiter to specify up to five levels of hierarchy.

Note

The product category is the product catalog classification, which may be different than the app or web categories used to display the product from the web or from the application.

pr<productIndex>va (string, optional)

Represents the product variant SKU.

The product index must be a positive integer between 1 and 200, inclusive.

pr<productIndex>group (string, optional)

Represents a group of similar product IDs.

The product index must be a positive integer between 1 and 200, inclusive.

Note

This is useful if you want only one item per group to be recommended by ML algorithms.

pr<productIndex>pr (currency, required)

Represents the product price.

The product index must be a positive integer between 1 and 200, inclusive. The value cannot be blank, therefore use 0 when a product has no price.

pr<productIndex>qt (integer, optional)

Represents the product quantity.

The product index must be a positive integer between 1 and 200, inclusive.

pr<productIndex>cc (string, optional)

Represents the coupon code associated with the product. Maximum: 500 bytes.

pr<productIndex>ps (integer, optional)

Represents the product’s position in a list or a collection.

pr<productIndex>cd<dimensionIndex> (string, optional)

Represents a product-level custom dimension where the dimension index is a positive integer between 1 and 200, inclusive. Maximum: 150 bytes.

pr<productIndex>cm<metricIndex> (integer, optional)

Represents a product-level custom metric where the metric index is a positive integer between 1 and 200, inclusive.

il<listIndex>pi<productIndex>nm (string, optional)

Represents the product impression list name.

The impression list index and the product index must be both positive integers between 1 and 200, inclusive

Notes

  • Coveo only supports this parameter when the event is related to a UA search event. In this case, it references the UA search ID prefixed with coveo:search:.

  • An impression list index less than 1 is ignored.

il<listIndex>pi<productIndex>id (string, optional)

Represents the product ID or SKU.

il<listIndex>pi<productIndex>br (string, optional)

Represents the product impression brand.

il<listIndex>pi<productIndex>ca (string, optional)

Represents the product impression category.

il<listIndex>pi<productIndex>va (string, optional)

Represents the product impression variant.

The impression list index and the product index must be both positive integers between 1 and 200, inclusive.

il<listIndex>pi<productIndex>ps (integer, optional)

Represents the product impression position in a list or collection.

The impression list index and the product index must be both positive integers between 1 and 200, inclusive.

il<listIndex>pi<productIndex>pr (currency, optional)

Represents the product impression price.

il<listIndex>pi<productIndex>cd<dimensionIndex> (string, optional)

Represents the product-level custom dimension where the dimension index is a positive integer between 1 and 200, inclusive.

The impression list index and the product index must be both positive integers between 1 and 200, inclusive.

il<listIndex>pi<productIndex>cm<metricIndex> (integer, optional)

Represents the product-level custom metric where the metric index is a positive integer between 1 and 200.

The impression list index and the product index must be both positive integers between 1 and 200, inclusive.

promo<promoIndex>id (string, optional)

Represents the promotion ID.

The promotion index must be a positive integer between 1 and 200.

promo<promoIndex>nm (integer, optional)

Represents the promotion name.

The promotion index must be a positive integer between 1 and 200.

promo<promoIndex>cr (string, optional)

Represents the creative associated with the promotion.

The promotion index must be a positive integer between 1 and 200.

promo<promoIndex>ps (string, optional)

Represents the position of the creative.

The promotion index must be a positive integer between 1 and 200.

Social interactions

sn (string, required)

Specifies the social interaction action. Maximum: 50 bytes.

sa (string, required)

Specifies the social interaction action. Maximum: 50 bytes.

st (string, required)

Specifies the target of a social interaction. Maximum: 50 bytes.

Timing

utc (string, required)

Specifies the user timing category. Maximum of length 150 bytes.

utv (string, required)

Specifies the user timing variable. Maximum of length 500 bytes.

utt (integer, required)

Specifies the user timing value in milliseconds.

utl (string, optional)

Specifies the user timing label. Maximum: 500 bytes.

plt (integer, optional)

Specifies the time it took for a page to load. The value is in milliseconds.

dns (integer, optional)

Specifies the time it took to perform a DNS lookup. The value is in milliseconds.

pdt (integer, optional)

Specifies the time it took for the page to be downloaded. The value is in milliseconds.

rrt (integer, optional)

Specifies the time it took for any redirects to happen. The value is in milliseconds.

tcp (integer, optional)

Specifies the time it took for a TCP connection to be made. The value is in milliseconds.

srt (integer, optional)

Specifies the time it took for the server to respond after connecting. The value is in milliseconds.

dit (integer, optional)

Specifies the time it took for the Document.readyState to be interactive. The value is in milliseconds.

clt (integer, optional)

Specifies the time it took for the DOMContentLoaded event to load. The value is in milliseconds.

Exceptions

exd (string, optional)

Specifies the description of an exception. Maximum: 150 bytes.

exf (boolean, optional)

Whether the exception is fatal.

cd<dimensionIndex> (string, optional)

Represents each custom dimension with an associated index. Maximum of length 150 bytes.

The dimension index must be a positive integer between 1 and 200, inclusive.

cm<metricIndex> (number, optional)

Represents a custom metric with an associated index.

The metric index must be a positive integer between 1 and 200, inclusive.

Proprietary or custom

custom (string, optional)

Passes any list of custom parameters into the form of a JSON document.

1. The Collect endpoint is a custom implementation and extension of the Google Measurement Protocol.