REST Resource: projects.locations.catalogs.eventStores.userEvents

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 (UserInfo)
  },
  "eventDetail": {
    object (EventDetail)
  },
  "productEventDetail": {
    object (ProductEventDetail)
  },
  "eventTime": string,
  "eventSource": enum (EventSource)
}
Fields
eventType

string

Required. User event type. Allowed values are:

  • add-to-cart Products being added to cart.
  • add-to-list Items being added to a list (shopping list, favorites etc).
  • category-page-view Special pages such as sale or promotion pages viewed.
  • checkout-start User starting a checkout process.
  • detail-page-view Products detail page viewed.
  • home-page-view Homepage viewed.
  • page-visit Generic page visits not included in the event types above.
  • purchase-complete User finishing a purchase.
  • refund Purchased items being refunded or returned.
  • remove-from-cart Products being removed from cart.
  • remove-from-list Items being removed from a list.
  • search Product search.
  • shopping-cart-page-view User viewing a shopping cart.
  • impression List of items displayed. Used by Google Tag Manager.
userInfo

object (UserInfo)

Required. User information.

eventDetail

object (EventDetail)

Optional. User event detailed information common across different recommendation types.

productEventDetail

object (ProductEventDetail)

Optional. Retail product specific user event metadata.

This field is required for the following event types:

  • add-to-cart
  • add-to-list
  • category-page-view
  • checkout-start
  • detail-page-view
  • purchase-complete
  • refund
  • remove-from-cart
  • remove-from-list
  • search

This field is optional for the following event types:

  • page-visit
  • shopping-cart-page-view - note that 'productEventDetail' should be set for this unless the shopping cart is empty.

This field is not allowed for the following event types:

  • home-page-view
eventTime

string (Timestamp format)

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: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

eventSource

enum (EventSource)

Optional. This field should not be set when using JavaScript pixel or the Recommendations AI Tag. Defaults to EVENT_SOURCE_UNSPECIFIED.

UserInfo

Information of end users.

JSON representation
{
  "visitorId": string,
  "userId": string,
  "ipAddress": string,
  "userAgent": string,
  "directUserRequest": boolean
}
Fields
visitorId

string

Required. A unique identifier for tracking visitors with a length limit of 128 bytes.

For example, this could be implemented with a http cookie, which should be able to uniquely identify a visitor on a single device. This unique identifier should not change if the visitor log in/out of the website. Maximum length 128 bytes. Cannot be empty.

userId

string

Optional. Unique identifier for logged-in user with a length limit of 128 bytes. Required only for logged-in users.

ipAddress

string

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 directUserRequest is set. Used to extract location information for personalization.

userAgent

string

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

directUserRequest

boolean

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 (FeatureMap)
  }
}
Fields
uri

string

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

string

Optional. The referrer url of the current page. When using the JavaScript pixel, this value is filled in automatically.

pageViewId

string

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 pageViewId property should be kept the same for all these events so that they can be grouped together properly. This pageViewId will be automatically generated if using the JavaScript pixel.

experimentIds[]

string

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

string

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 PredictResponse.recommendationToken property as a url parameter to product K's page. When recording events on product K's page, log the PredictResponse.recommendation_token to this field.

Optional, but highly encouraged for user events that are the result of a recommendation prediction query.

eventAttributes

object (FeatureMap)

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 (CategoryHierarchy)
    }
  ],
  "productDetails": [
    {
      object (ProductDetail)
    }
  ],
  "listId": string,
  "cartId": string,
  "purchaseTransaction": {
    object (PurchaseTransaction)
  }
}
Fields
searchQuery

string

Required for search events. Other event types should not set this field. The user's search query as UTF-8 encoded text with a length limit of 5 KiB.

pageCategories[]

object (CategoryHierarchy)

Required for category-page-view events. Other event types should not set this field. The categories associated with a category page. Category pages include special pages such as sales or promotions. For instance, a special sale page may have the category hierarchy: categories : ["Sales", "2017 Black Friday Deals"].

productDetails[]

object (ProductDetail)

The main product details related to the event.

This field is required for the following event types:

  • add-to-cart
  • add-to-list
  • checkout-start
  • detail-page-view
  • purchase-complete
  • refund
  • remove-from-cart
  • remove-from-list

This field is optional for the following event types:

  • page-visit
  • shopping-cart-page-view - note that 'productDetails' should be set for this unless the shopping cart is empty.
  • search (highly encouraged)

In a search event, this field represents the products returned to the end user on the current page (the end user may have not finished broswing the whole page yet). When a new page is returned to the end user, after pagination/filtering/ordering even for the same query, a new SEARCH event with different productDetails is desired. The end user may have not finished broswing the whole page yet.

This field is not allowed for the following event types:

  • category-page-view
  • home-page-view
listId

string

Required for add-to-list and remove-from-list events. The id or name of the list that the item is being added to or removed from. Other event types should not set this field.

cartId

string

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 add-to-cart, remove-from-cart, checkout-start, purchase-complete, or shopping-cart-page-view events.

purchaseTransaction

object (PurchaseTransaction)

Optional. A transaction represents the entire purchase transaction. Required for purchase-complete events. Optional for checkout-start events. Other event types should not set this field.

ProductDetail

Detailed product information associated with a user event.

JSON representation
{
  "id": string,
  "currencyCode": string,
  "originalPrice": number,
  "displayPrice": number,
  "stockState": enum (StockState),
  "quantity": integer,
  "availableQuantity": integer,
  "itemAttributes": {
    object (FeatureMap)
  }
}
Fields
id

string

Required. Catalog item ID. UTF-8 encoded string with a length limit of 128 characters.

currencyCode

string

Optional. Currency code for price/costs. Use three-character ISO-4217 code. Required only if originalPrice or displayPrice is set.

originalPrice

number

Optional. Original price of the product. If provided, this will override the original price in Catalog for this product.

displayPrice

number

Optional. Display price of the product (e.g. discounted price). If provided, this will override the display price in Catalog for this product.

stockState

enum (StockState)

Optional. Item stock state. If provided, this overrides the stock state in Catalog for items in this event.

quantity

integer

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 add-to-cart event. Required for add-to-cart, add-to-list, remove-from-cart, checkout-start, purchase-complete, refund event types.

availableQuantity

integer

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 stockStatus is set to IN_STOCK.

Note that if an item is out of stock, you must set the stockState field to be OUT_OF_STOCK. Leaving this field unspecified / as zero is not sufficient to mark the item out of stock.

itemAttributes

object (FeatureMap)

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

string

Optional. The transaction ID with a length limit of 128 bytes.

revenue

number

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

taxes

map (key: string, value: number)

Optional. All the taxes associated with the transaction.

costs

map (key: string, value: number)

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

string

Required. Currency code. Use three-character ISO-4217 code. This field is not required if the event type is refund.

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

collect

Writes a single user event from the browser.

import

Bulk import of User events.

list

Gets a list of user events within a time range, with potential filtering.

purge

Deletes permanently all user events specified by the filter provided.

rejoin

Triggers a user event rejoin operation with latest catalog data.

write

Writes a single user event.