Log Collect Events

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 of a user’s interactions with a Coveo-powered website or application, without requiring any event states to be retained on the client side. Currently, its main use is in commerce, but it will eventually support other types of Coveo implementations (e.g., service, website, and workplace).

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.

When Should I Use the Collect Endpoint?

The Collect endpoint can deterministically link non-linear events within their own specific contexts. Currently, the Collect endpoint only supports the commerce use case. As a developer, you should use it whenever you need to associate user interactions that happen in or out of a Coveo-powered commerce website or application. It 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 allows you to 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 instance, 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 on 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 of the 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.

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"
}

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 tracking or web property ID for all hit types. The tid is the org query parameter in a Coveo-powered search interface. For more information, see Log Usage Analytics Events.

Example: tid=UA-XXXX-Y

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.

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

Coveo doesn’t use this parameter and ignores it.

ds (String, Optional)

Indicates the data source of the hit.

Example: ds=web

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.

  • 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. When specified, the originLevel1 field of the corresponding event is populated with identical data.

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 is not used in reporting.

context_website (String, Optional)

Tracks analytics across multiple different subsites. If you own multiple eCommerce storefronts, use this field to differentiate them.

This parameter must be set for all events that are passed to ensure that they’re properly linked together over the same website. Otherwise, the series of events which maps the user’s journey will be broken, causing analytics processes such as revenue attribution to be less accurate.

User

cid (String, Required)

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

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.

uid (String, Optional)

Represents the user ID and identifies a user through the credentials used to log in to a certain website (e.g., the user’s hashed email address).

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.

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

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 length of 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

The URL must comply with W3 specifications.

cn (String, Optional)

Specifies the campaign name. Maximum length of 100 bytes.

Coveo doesn’t use this parameter and ignores it.

cs (String, Optional)

Specifies the campaign source. Maximum length of 100 bytes.

Coveo doesn’t use this parameter and ignores it.

cm (String, Optional)

Specifies the campaign medium. Maximum length of 100 bytes.

Coveo doesn’t use this parameter and ignores it.

ck (String, Optional)

Specifies the campaign keyword. Maximum length of 500 bytes.

Coveo doesn’t use this parameter and ignores it.

cc (String, Optional)

Specifies the campaign content. Maximum length of 500 bytes.

Coveo doesn’t use this parameter and ignores it.

ci (String, Optional)

Specifies the campaign ID. Maximum length of 100 bytes.

Coveo doesn’t use this parameter and ignores it.

gclid (String, Optional)

Specifies the Google Ads ID.

Coveo doesn’t use this parameter and ignores it.

dclid (String, Optional)

Specifies the Google Display Ads ID.

Coveo doesn’t use this parameter and ignores it.

System Info

sr (String, Optional)

Specifies the screen resolution. Maximum length of 20 bytes.

It must use the following format: <INTEGER>x<INTEGER>. Both integers have a positive value (e.g., 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 length of 20 bytes.

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 length of 20 bytes.

sd (String, Optional)

Specifies the screen color depth. Maximum length of 20 bytes.

ul (String, Optional)

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

See contentLocale for additional details.

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

contentLocale (String, Optional)

Specifies the locale setting of the viewed content or page. Maximum length of 20 bytes. Specified with ISO-639 standards (e.g., en-us).

For example, your browser might be set to one locale (e.g., fr-ca), but you’re viewing a site with a different locale setting (e.g., en-us). Therefore, the browser’s locale is the ul and the site’s locale is the contentLocale.

je (String, Optional)

Specifies if Java is enabled.

Coveo doesn’t use this parameter and ignores it.

fl (String, Optional)

Specifies the flash version. Maximum length of 20 bytes.

Coveo doesn’t use this parameter and ignores it.

Hit

t (String, Required)

Required for all hit types.

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.

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

  • An event hit works in the same way as a UA click event if the product action is a click or a quickview. If the pa has a Coveo search ID, then the event is converted into a UA click event. If the pa = impression and the il1nm has a Coveo search ID, then the event is converted into UA search event.

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

ni (String, Optional)

Specifies if a hit is non-interactive.

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.

The pid must be a valid UUID.

dl (String, Optional)

Sends the document location URL of the page on which the content resides. Maximum length of 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.

The URL must comply with W3 specifications.

dh (String, Optional)

Specifies the document host name from which the content is hosted. Maximum length of 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 (e.g., 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 length of 2048 bytes.

dt (String, Optional)

Represents the document title. Maximum length of 1500 bytes.

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

cd (String, Required)

Required for mobile properties for screenview hits. Maximum length of 2048 bytes.

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 length of 100 bytes. It can have up to five content groupings, each of which has an associated index between 1 and 5, inclusive.

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 is removed and any repeated slashes are reduced to a single slash. For example, /a//b/ is converted to a/b.

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 length of 100 bytes.

This parameter is optional for hits sent to web properties.

aid (String, Required)

Represents the application identifier. Maximum length of 150 bytes.

av (String, Optional)

Specifies the application version. Maximum length of 100 bytes.

aiid (String, Optional)

Specifies the application installer ID. Maximum length of 150 bytes.

Events

ec (String, Required)

Specifies the event category. Maximum length of 150 bytes.

ea (String, Required)

Specifies the event action. Maximum length of 500 bytes.

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

el (String, Optional)

Specifies the event label. Maximum length of 500 bytes.

ev (Integer, Optional)

Specifies the event value.

Values must be non-negative.

E-Commerce

ta (String, Optional)

Specifies the affiliation or a store name. Maximum length of 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 length of 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 length of 500 bytes.

iv (String, Optional)

Specifies the item category. Maximum length of 500 bytes.

Product

pr1id (String, Required)

Represents the product ID.

pr1nm (String, Required)

Represents the product name.

pr1br (String, Optional)

Represents the brand associated with the product.

pr1ca (String, Required)

Represents the product category.

It can be hierarchical and you can use / as a delimiter to specify up to five levels of hierarchy.

The product category is from the product catalog classification, which may be different than the app or web category (e.g., URL path) used to access the product from the web or from the application.

pr1va (String, Required)

Represents the product variant.

pr1pr (Currency, Required)

Represents the product unit price.

pr1qt (Integer, Optional)

Represents the product quantity.

pa (String, Optional)

Represents the role of the products included in a hit.

If a product action is not 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.

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.

il<index>nm (String, Optional)

Represents the product impression list name.

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

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

pr1id (String, Required)

Represents the product ID or SKU.

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

pr1br (String, Required)

Represents the brand associated with the product.

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

pr1ca (String, Required)

Represents the product category.

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

pr1va (String, Optional)

Represents the product variant SKU.

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’s position in a list or collection.

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

pr1pr (Currency, Required)

Represents the product price.

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

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.

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 length of 50 bytes.

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

  • The code is optional when there’s nothing over the event referencing the currency value (e.g., price), but it’s mandatory over any event involving currency values (e.g., 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 (e.g., 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>cc (String, Optional)

Represents the coupon code associated with the product. Maximum length of 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 length of 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.

Social Interactions

sn (String, Required)

Specifies the social interaction action. Maximum length of 50 bytes.

sa (String, Required)

Specifies the social interaction action. Maximum length of 50 bytes.

st (String, Required)

Specifies the target of a social interaction. Maximum length of 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 length of 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 length of 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.
What's Next for Me?