Generative AI Google Brain

search-vais-building-blocks-record-user-events

3 min read

Recording Real-Time User Events in Vertex AI Search Datastores

Source notebook

Repo path: search/vais-building-blocks/record_user_events.ipynb · Open on GitHub · intermediate

Records real-time search and view-item user events for a Vertex AI Search website datastore.

Summary

This notebook teaches how to send real-time user events to a Vertex AI Search website datastore using REST calls. It defines helpers to issue a search request, extract attribution tokens and impressions, write search and view-item events, run a synthetic user flow, and purge the recorded events for cleanup.

Key code patterns

Authenticated REST session

from google.auth import default
from google.auth.transport.requests import AuthorizedSession
 
creds, _ = default()
authed_session = AuthorizedSession(creds)

Uses Application Default Credentials with an authorized HTTP session for Discovery Engine REST calls.

Search a datastore

response = authed_session.post(
    f"https://discoveryengine.googleapis.com/{VAIS_BRANCH}/projects/{project_id}/locations/{location}/collections/default_collection/dataStores/{datastore_id}/servingConfigs/default_search:search",
    headers={"Content-Type": "application/json"},
    json={"query": searchQuery, "pageSize": pageSize},
)

Runs a Vertex AI Search query against the default serving config and returns results plus an attribution token.

Write search event

json={
    "eventType": "search",
    "userPseudoId": user_pseudo_id,
    "searchInfo": {"searchQuery": search_query},
    "documents": impressions,
    "attributionToken": attribution_token,
}

Reports the query, shown impressions, user pseudo ID, and attribution token to userEvents.write.

Write view-item event

json={
    "attributionToken": attribution_token,
    "eventType": "view-item",
    "userPseudoId": user_pseudo_id,
    "documents": [{"uri": viewed_uri}],
}

Connects a clicked document URI back to the search interaction using the attribution token.

Extract impressions

impressions = [
    {"uri": result["document"]["derivedStructData"]["link"]}
    for result in search_resp.json()["results"]
]

Builds the documents list from returned website result links before reporting the search event.

Purge test events

response = authed_session.post(
    f"https://discoveryengine.googleapis.com/{VAIS_BRANCH}/projects/{project_id}/locations/{location}/collections/default_collection/dataStores/{datastore_id}/userEvents:purge",
    headers={"Content-Type": "application/json"},
    json={"filter": purge_filter},
)

Removes recorded notebook events with a filter such as userPseudoId for cleanup.

Models & APIs used

  • APIs / services: Vertex AI Search, Discovery Engine API, Service Usage API
  • SDKs / libraries: google-auth

When to use this

Use this pattern when you need to explicitly report real-time search and click behavior to Vertex AI Search for ranking and analytics signals.

Gotchas & caveats

  • Requires an existing advanced website search datastore.
  • The datastore location is set at creation and must match requests; the notebook uses global with options global, us, and eu.
  • The notebook uses VAIS_BRANCH v1 because the feature is available in GA.
  • Running outside Colab requires Google Cloud authentication such as Application Default Credentials.
  • The notebook recommends Owner role, or at least serviceusage.serviceUsageAdmin, iam.serviceAccountAdmin, and discoveryengine.admin.
  • Discovery Engine API must be enabled for the project.
  • If results are post-processed outside VAIS, the final explicit impressions list should be provided instead of blindly using the VAIS response order.
  • For non-website datastores, documents may need to be identified with fields such as document id instead of URI.

Best practices

  • Report both search events and view-item events with the same attribution token.
  • Include the impressions shown to the user in the search event.
  • Use userPseudoId to associate events with a user without requiring a named account.
  • Use JavaScript Pixel as the recommended alternative when the customer can control the page source.
  • Purge synthetic notebook events after testing.
  • Use the correct datastore location in all Discovery Engine requests.

Graph View

Backlinks