About user events

This page describes the user event object, including listing potential user event types, and provides sample data for all user event types.

AI Commerce Search uses real-time user events to generate recommendations and search results. When you upload data, both recommendations and search are able to use that data, so you don't need to upload the same events twice if you use both services.

How search attribution works

How attribution works

User event types overview

There are several user event types that you can record as users browse your retail site:

User event name User action Google Analytics 4 event_name
home-page-view Views homepage. view_homepage
search (Search and browse) Searches the catalog. view_item_list + [searchQuery OR pageCategories + filter]
category-page-view (Recommendations only) Views special pages, such as sale or promotion pages. view_item_list + pageCategories
detail-page-view Views product detail page. view_item
add-to-cart Adds product to cart. add_to_cart
shopping-cart-page-view Views shopping cart. view_cart
purchase-complete Completes checkout. purchase

Out of these event types, AI Commerce Search specifically uses these four for popularity signaling:

  • SEARCH
  • DETAIL_PAGE_VIEW
  • ADD_TO_CART
  • PURCHASE_COMPLETE

For an extensive list of GA4 event fields, see Google Analytics 4 user event fields.

For detailed information about the UserEvent object, see UserEvent.

User event requirements

The following tables list requirements and best practices for user event types that recommendations and search use. Check that your user events fulfill these requirements so that AI Commerce Search can generate quality results.

This section lists:

If you use recommendations models, also see Model type data requirements, which lists additional requirements depending on the recommendation model type and optimization objective you plan to use.

You can view data quality metrics for search on the Data quality page in the AI Commerce Search in Gemini Enterprise for Customer Experience console. These metrics show the percentages of products and user events that fulfill recommended standards of data quality. For information about how to view search data quality, see Unlock search performance tiers.

General user event requirements

Make sure your user events meet the following requirements so that the AI Commerce Search can generate quality results. These apply to both recommendations and search.

Event type Requirement Impact
All events

Don't include synthetic data or duplicate events.

Synthetic or duplicate events negatively impact model quality and often prevent successful model training. Duplicate events can cause incorrect metrics values.

Include at least 100 unique visitor IDs for each type of event ingested.

This verifies that AI Commerce Search has enough data to generate quality results.

Visitor IDs must be formatted exactly the same across event import or event recording and in API requests.

Using a consistent format for visitor IDs helps correctly identify visitor patterns and provide better-quality results based on user behavior.

Products included in the events should exist in your catalog of products.

The unjoined events ratio should be kept as low as possible. A high ratio can negatively impact the quality of recommendation or search results.

Unjoined event data is not used to train models. However, unjoined events can be joined later, after the associated products have been ingested. For more information, see Rejoin user events.

Some user events should have the same visitor ID.

To construct valid behavior sequence histories, AI Commerce Search must be able to see multiple events with the same visitor ID.

For example, visitor123 has viewed five product detail pages, added three products to their cart, then bought two of the original five products. If these events all provide the same consistently formatted visitor ID, AI Commerce Search can consider that behavior sequence in its models.

detail-page-view

Include exactly one product per event.

The event can't be used if no product exists. If multiple products are included, the event is malformed and can't be used.

add-to-cart

Include exactly one product per event.

If multiple products are included, the event is malformed and can't be used.

purchase-complete

Include purchase_transaction.revenue.