- Resource: UserEvent
- UserInfo
- EventDetail
- ProductEventDetail
- ProductDetail
- PurchaseTransaction
- EventSource
- Methods
Resource: UserEvent
UserEvent captures all metadata information recommendation engine needs to know about how end users interact with customers' website.
JSON representation | |
---|---|
{ "eventType": string, "userInfo": { object ( |
Fields | |
---|---|
eventType |
Required. User event type. Allowed values are:
|
userInfo |
Required. User information. |
eventDetail |
Optional. User event detailed information common across different recommendation types. |
productEventDetail |
Optional. Retail product specific user event metadata. This field is required for the following event types:
This field is optional for the following event types:
This field is not allowed for the following event types:
|
eventTime |
Optional. Only required for userEvents.import method. Timestamp of user event created. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
eventSource |
Optional. This field should not be set when using JavaScript pixel or the Recommendations AI Tag. Defaults to |
UserInfo
Information of end users.
JSON representation | |
---|---|
{ "visitorId": string, "userId": string, "ipAddress": string, "userAgent": string, "directUserRequest": boolean } |
Fields | |
---|---|
visitorId |
Required. A unique identifier for tracking visitors with a length limit of 128 bytes. For example, this could be implemented with an HTTP cookie, which should be able to uniquely identify a visitor on a single device. This unique identifier should not change if the visitor logs in or out of the website. Maximum length 128 bytes. Cannot be empty. |
userId |
Optional. Unique identifier for logged-in user with a length limit of 128 bytes. Required only for logged-in users. |
ipAddress |
Optional. IP address of the user. This could be either IPv4 (e.g. 104.133.9.80) or IPv6 (e.g. 2001:0db8:85a3:0000:0000:8a2e:0370:7334). This should not be set when using the javascript pixel or if |
userAgent |
Optional. User agent as included in the HTTP header. UTF-8 encoded string with a length limit of 1 KiB. This should not be set when using the JavaScript pixel or if |
directUserRequest |
Optional. Indicates if the request is made directly from the end user in which case the userAgent and ipAddress fields can be populated from the HTTP request. This should not be set when using the javascript pixel. This flag should be set only if the API request is made directly from the end user such as a mobile app (and not if a gateway or a server is processing and pushing the user events). |
EventDetail
User event details shared by all recommendation types.
JSON representation | |
---|---|
{
"uri": string,
"referrerUri": string,
"pageViewId": string,
"experimentIds": [
string
],
"recommendationToken": string,
"eventAttributes": {
object ( |
Fields | |
---|---|
uri |
Optional. Complete url (window.location.href) of the user's current page. When using the JavaScript pixel, this value is filled in automatically. Maximum length 5KB. |
referrerUri |
Optional. The referrer url of the current page. When using the JavaScript pixel, this value is filled in automatically. |
pageViewId |
Optional. A unique id of a web page view. This should be kept the same for all user events triggered from the same pageview. For example, an item detail page view could trigger multiple events as the user is browsing the page. The |
experimentIds[] |
Optional. A list of identifiers for the independent experiment groups this user event belongs to. This is used to distinguish between user events associated with different experiment setups (e.g. using Recommendation Engine system, using different recommendation models). |
recommendationToken |
Optional. Recommendation token included in the recommendation prediction response. This field enables accurate attribution of recommendation model performance. This token enables us to accurately attribute page view or purchase back to the event and the particular predict response containing this clicked/purchased item. If user clicks on product K in the recommendation results, pass the Optional, but highly encouraged for user events that are the result of a recommendation prediction query. |
eventAttributes |
Optional. Extra user event features to include in the recommendation model. For product recommendation, an example of extra user information is traffic_channel, i.e. how user arrives at the site. Users can arrive at the site by coming to the site directly, or coming through Google search, and etc. |
ProductEventDetail
ProductEventDetail captures user event information specific to retail products.
JSON representation | |
---|---|
{ "searchQuery": string, "pageCategories": [ { object ( |
Fields | |
---|---|
searchQuery |
At least one of |
pageCategories[] |
Required for |
productDetails[] |
The main product details related to the event. This field is required for the following event types:
This field is optional for the following event types:
In a This field is not allowed for the following event types:
|
listId |
Required for |
cartId |
Optional. The id or name of the associated shopping cart. This id is used to associate multiple items added or present in the cart before purchase. This can only be set for |
purchaseTransaction |
Optional. A transaction represents the entire purchase transaction. Required for |
ProductDetail
Detailed product information associated with a user event.
JSON representation | |
---|---|
{ "id": string, "currencyCode": string, "originalPrice": number, "displayPrice": number, "stockState": enum ( |
Fields | |
---|---|
id |
Required. Catalog item ID. UTF-8 encoded string with a length limit of 128 characters. |
currencyCode |
Optional. Currency code for price/costs. Use three-character ISO-4217 code. Required only if originalPrice or displayPrice is set. |
originalPrice |
Optional. Original price of the product. If provided, this will override the original price in Catalog for this product. |
displayPrice |
Optional. Display price of the product (e.g. discounted price). If provided, this will override the display price in Catalog for this product. |
stockState |
Optional. Item stock state. If provided, this overrides the stock state in Catalog for items in this event. |
quantity |
Optional. Quantity of the product associated with the user event. For example, this field will be 2 if two products are added to the shopping cart for |
availableQuantity |
Optional. Quantity of the products in stock when a user event happens. Optional. If provided, this overrides the available quantity in Catalog for this event. and can only be set if Note that if an item is out of stock, you must set the |
itemAttributes |
Optional. Extra features associated with a product in the user event. |
PurchaseTransaction
A transaction represents the entire purchase transaction.
JSON representation | |
---|---|
{ "id": string, "revenue": number, "taxes": { string: number, ... }, "costs": { string: number, ... }, "currencyCode": string } |
Fields | |
---|---|
id |
Optional. The transaction ID with a length limit of 128 bytes. |
revenue |
Required. Total revenue or grand total associated with the transaction. This value include shipping, tax, or other adjustments to total revenue that you want to include as part of your revenue calculations. This field is not required if the event type is |
taxes |
Optional. All the taxes associated with the transaction. |
costs |
Optional. All the costs associated with the product. These can be manufacturing costs, shipping expenses not borne by the end user, or any other costs. Total product cost such that profit = revenue - (sum(taxes) + sum(costs)) If productCost is not set, then profit = revenue - tax - shipping - sum(CatalogItem.costs). If CatalogItem.cost is not specified for one of the items, CatalogItem.cost based profit cannot be calculated for this Transaction. |
currencyCode |
Required. Currency code. Use three-character ISO-4217 code. This field is not required if the event type is |
EventSource
User event source.
Enums | |
---|---|
EVENT_SOURCE_UNSPECIFIED |
Unspecified event source. |
AUTOML |
The event is ingested via a javascript pixel or Recommendations AI Tag through automl datalayer or JS Macros. |
ECOMMERCE |
The event is ingested via Recommendations AI Tag through Enhanced Ecommerce datalayer. |
BATCH_UPLOAD |
The event is ingested via Import user events API. |
Methods |
|
---|---|
|
Writes a single user event from the browser. |
|
Bulk import of User events. |
|
Gets a list of user events within a time range, with potential filtering. |
|
Deletes permanently all user events specified by the filter provided. |
|
Triggers a user event rejoin operation with latest catalog data. |
|
Writes a single user event. |