Log Collect events
Log Collect events
This is for:
DeveloperWhat’s the Collect endpoint?
The Coveo Collect endpoint offers a new generic way to collect and track events instead of using the older /search
, /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 site 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. 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.
Leading practice
We recommend using the Coveo UA 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 two main benefits over the older UA Write API endpoints:
-
It supports multiple objects per action or event.
-
It lets you track events even before you implement Coveo search components on a site 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.
A user accesses an SPA ecommerce website to find some shoes.
The user searches for "red running shoes" and several results are returned.
All search events are handled by the /search
endpoint.
After the click, the user is redirected to a page which provides detailed product information.
Here a product detail view event should be logged.
This event is logged to the /collect
endpoint using the detail
product action (pa) value.
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 Add to Cart, which logs a cart event to the /collect
endpoint with the add
product action.
Finally, the user completes the purchase.
This logs a purchase event to the /collect
endpoint with the purchase
product action.
Usage
To use the Collect endpoint, make a POST request with the user interaction data in JSON format.
The following example sends a payload with the event type t
set to event
and the product action pa
set to purchase
indicating this is a commerce purchase event:
POST https://platform.cloud.coveo.com/rest/ua/v15/analytics/collect HTTP/1.1
Authorization: Bearer ********-****-****-************
Payload:
{
"t": "event",
"pid": "5e294462-8b86-4147-8c75-18ff54e49594",
"dr": "https://sports.barca.group/pdp/SP03927_00010",
"dl": "https://sports.barca.group/cart",
"tm": 1707899915025,
"z": "abfd898b-d8bb-42da-ac9e-1003410ca466",
"sr": "1728x1117",
"sd": "30-bit",
"ul": "en-US",
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
"dt": "Cart | Barca Sports",
"de": "UTF-8",
"pr1nm": "Gray Bottle",
"pr1id": "SP03927_00010",
"pr1br": "Coast Guard and Co",
"pr1group": "SP03927",
"pr1pr": 20,
"pr1ca": "Accessories/Surf Accessories/Water Bottles",
"pr1va": "SP03927_00010_XS",
"pr1qt": 1,
"pa": "purchase",
"ti": "a1dccc66-a543-4c48-b270-c09dc26a8bd4-1707899915024",
"tr": "21.00",
"ts": "1.49",
"tt": "1.00",
"searchHub": "Checkout",
"tab": "default",
"cid": "a1dccc66-a543-4c48-b270-c09dc26a8bd4",
"uid": "anonymous",
"cu": "USD",
"dp": "/cart",
"trackingId": "sports"
}
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 |
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
|
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 |
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)
The |
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 UA library and greater. |
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.
{
...
"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 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 (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 |
Traffic sources
dr
(string, optional)
Specifies the document referral source which brought traffic to a site. 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
|
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 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: screenview
, event
, transaction
, item
, social
, or timing
.
The Collect event is converted to a UA event based on this value.
The page view event has been deprecated and is no longer necessary to send. Unless you are creating custom reports using this event, we recommend that you stop sending it, as doing so will simplify your implementation. |
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 |
|
|
|
click |
|
|
|
search |
|
|
|
Click event example:
{
"t": "event",
"pa": "click",
"pal": "coveo:search:12345"
}
Search event example:
{
"t": "event",
"pa": "impression",
"il1nm": "coveo:search:67890"
}
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 |
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 /
.
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.
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
|
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: |
ti
(string, optional)
Represents the transaction ID.
This is an additional parameter that can be sent when pa
is set to purchase
.
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
.
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
.
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
.
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
.
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
.
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 |
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
|
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)
The unique identifier of the product.
The value and casing must match exactly with the following:
-
The value set in the event’s
id
field. -
The value of the product identifier field configured in the catalog.
NoteThe catalog’s product identifier field must be mapped to the
permanentid
field, so thepr1id
value must also match the value of thepermanentid
field.
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. When logging events, the Coveo Platform expects the The format expected when uploading When logging events, the Coveo Platform only requires the last level of the hierarchy to be sent. For example, if you have a category defined in the index as |
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 can’t 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
|
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.