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.
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.
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 |
Reference
General
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.
|
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 For example, when a user visits the same website twice with the same browser, they’re assigned the same If not specified, the UA visitor cookie behavior is considered instead and the |
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 |
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.
|
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.
|
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 |
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.
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 |
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: |
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 |
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.
|
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.
|
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.