Agent Search - Retail is Google's Vertex AI Search for commerce (AI Commerce Search) product, which powers search, browse, and recommendation experiences for retail catalogs. It analyzes shopper behavior—such as product views, cart activity, and purchases—to improve search relevance and personalized recommendations. Retailers upload a product catalog that serves as the source of truth for product data, then stream user events to inform serving models. This integration sends server-side user events to the Retail User Events API to support these commerce experiences.
Product Type: Advertising
Integration Type: Starter Kit
Event Source Type: Web
Event Scope: Full-Funnel Events
- Sends server-side user events (page views, search, product, cart, and purchase activity) directly to the Retail User Events API.
- Maps standard e-commerce events to Google's Retail event vocabulary.
- Enriches events with visitor and user identifiers used for event association.
- Sends product identifiers and quantities, with the catalog supplying remaining product details.
- A one-time console onboarding step is required: the customer's project must accept the AI Commerce Search data-use terms before events can be sent. Until accepted, every API call fails. This step requires elevated project permissions (project Owner or the Retail Admin role), not project Editor.
- The catalog is the source of truth for product data. Product fields other than the product ID sent inside events (such as title, categories, brand, and description) are ignored and replaced with catalog values. The exception is price information, which is honored from the event. This integration therefore sends only the product ID and quantity.
- Events referencing a product ID not present in the catalog are accepted and return a success response, but are recorded as unjoined rather than rejected. Catalog-mapping problems do not surface as delivery errors and should be monitored through the joined/unjoined breakdown in the Google Cloud console.
- Console dashboards can lag by roughly an hour. The synchronous write response is the authoritative signal that an event was delivered.
- Google anonymizes the user's IP address on ingestion by zeroing the last octet.
- This is Agent Search for commerce (AI Commerce Search) using the Retail API. It is a different API from Discovery Engine, and Discovery Engine event names are rejected in this integration.
- The user ID is sent unhashed by default. Google recommends sending a hashed value, which the customer can hash upstream.
- Certain required fields are enforced by the API, and events missing these fields are rejected:
- quantity on Product Added, Product Removed, and Order Completed product details;
- revenue and currency code on Order Completed
- a search query or page categories on Products Searched.
- The Retail event vocabulary is fixed. Product Clicked, Checkout Started, Payment Info Entered, Promotion Viewed, Promotion Clicked, and wishlist events have no Retail equivalent and cannot be sent through this integration.
- Events are sent individually. The
userEvents:write endpoint accepts one event per request and does not support batching.
- In the Google Cloud console, select or create the project that holds your retail catalog. Note its
PROJECT_NUMBER for use as a Connection Parameter.
- Enable the Retail API on the project.
- Accept the AI Commerce Search data-use terms. A user with the project Owner or Retail Admin role must complete this one-time step before events can be sent.
- Create a service account and grant it permission to write Retail user events (
retail.userEvents.create). Note the service account's email for use as SERVICE_ACCOUNT_EMAIL.
- Create a JSON key for the service account and use its private key as
PRIVATE_KEY. This key signs the JWT used for authentication.
- For more information on creating service accounts, please see: https://docs.cloud.google.com/iam/docs/service-accounts-create
- From the integration library, add an Agent Search - Retail integration. Then, fill out the Connection Parameters:
| Connection Parameter | Description |
|---|
PROJECT_NUMBER | Google Cloud project number used in the API endpoint path. |
LOCATION | Catalog location. Defaults to global. |
CATALOG_ID | Catalog identifier. Defaults to default_catalog. |
SERVICE_ACCOUNT_EMAIL | Service account email used as the JWT issuer for authentication. |
PRIVATE_KEY | RSA private key used to sign the authentication JWT. |
- MetaRouter provides all of the event mappings that Agent Search - Retail integrations typically require. You may add custom events, parameters, or mappings in accordance with Google's API documentation.
- In the Pipelines tab, add your Agent Search - Retail integration.
- Select the correct integration revision.
- Click Add Integration to finalize deployment.
Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.
| Output Key | Description | Expected Input |
|---|
visitorId Required | String: Visitor identifier used for event association. | anonymousId |
userInfo.userId | String: Authenticated user identifier. | userId |
eventTime | String: Original event time; preserves timing across batching delays and retries. | timestamp |
userInfo.userAgent | String: Browser or device user agent. | context.userAgent |
userInfo.ipAddress | String: User IP address; anonymized by Google on ingestion. | context.ip |
uri | String: URL of the page where the event occurred. | context.page.url |
referrerUri | String: Referring page URL. | context.page.referrer |
| Output Key | Description | Expected Input |
|---|
eventType Required | String: Returns category-page-view when a category is present, otherwise home-page-view. | Expression – derived from properties.category |
pageCategories | String: Category associated with the page. | properties.category |
| Output Key | Description | Expected Input |
|---|
eventType Required | String: Vendor event name for search activity. | Enrichment – 'search' |
searchQuery | String: Search query entered by the user. | properties.query |
| Output Key | Description | Expected Input |
|---|
eventType Required | String: Vendor event name for category page views. | Enrichment – 'category-page-view' |
pageCategories | String: Category viewed by the user. | properties.category |
| Output Key | Description | Expected Input |
|---|
eventType Required | String: Vendor event name for product detail views. | Enrichment – 'detail-page-view' |
productDetails | Array: Product detail containing the viewed product ID. | Expression – builds product detail from properties.product_id |
| Output Key | Description | Expected Input |
|---|
eventType Required | String: Vendor event name for add-to-cart activity. | Enrichment – 'add-to-cart' |
cartId | String: Cart identifier for the event. | properties.cart_id |
productDetails Required | Array: Product detail with product ID and quantity; quantity is required by the API. | Expression – builds product detail from properties.product_id and properties.quantity |
| Output Key | Description | Expected Input |
|---|
eventType Required | String: Vendor event name for remove-from-cart activity. | Enrichment – 'remove-from-cart' |
cartId | String: Cart identifier for the event. | properties.cart_id |
productDetails Required | Array: Product detail with product ID and quantity; quantity is required by the API. | Expression – builds product detail from properties.product_id and properties.quantity |
| Output Key | Description | Expected Input |
|---|
eventType Required | String: Vendor event name for cart page views. | Enrichment – 'shopping-cart-page-view' |
cartId | String: Cart identifier for the event. | properties.cart_id |
productDetails | Array: Product details mapped from each item in the cart. | Expression – maps properties.products to product ID and quantity |
| Output Key | Description | Expected Input |
|---|
eventType Required | String: Vendor event name for completed purchases. | Enrichment – 'purchase-complete' |
purchaseTransaction.id | String: Order or transaction identifier. | properties.order_id |
purchaseTransaction.revenue Required | Number: Total order revenue; required by the API for purchases. | properties.total |
purchaseTransaction.tax | Number: Tax amount on the order. | properties.tax |
purchaseTransaction.currencyCode Required | String: Currency code; required by the API for purchases. | properties.currency |
productDetails Required | Array: Product details with product ID and quantity; quantity is required by the API. | Expression – maps properties.products to product ID and quantity |
These identifiers must be mapped to Agent Search - Retail in order for successful user matching to occur. Without these IDs, any events sent to Agent Search - Retail may not be accurately reflected in reporting.
| Attribute | Example | Sync Injector Required? |
|---|
visitorId Required | b171a9b06ce011ecafcd1b209be8601b | No |
userId Recommended | 111222 | No |
- The API validates each event as it is received. A
200 response confirms the event was accepted and is the primary signal that it was delivered. A non-200 response includes an error message describing why the event was rejected.
- An event that references a product ID not found in the catalog is still accepted with a
200 response, but is recorded as unjoined. Because these events do not appear as delivery errors, review the joined and unjoined counts to confirm events are matching catalog products.
- To review delivered events, open the Data page in the Google Cloud console and select the Events tab, which lists events written to the catalog. These metrics can take up to 24 hours to appear after an event is received.
- A high proportion of unjoined events indicates that product IDs sent in events are not matching the catalog. If this occurs, verify that the product IDs being sent exist in the catalog.
