This page describes user events for search and recommendations apps, including user event types, requirements, and examples for user event types.
The following app types support user events:
- Media apps: Media search and recommendation apps. For more information, see About media documents and data stores.
- Generic apps: Vertical-agnostic search and recommendation apps. For more information on the kind of data that comprises generic apps, see About apps and data stores.
The following table lists the app types for which user events are required. Google recommends that you upload user events for all app types — the more user events the better the search and recommendation quality.
App type | User events required? |
---|---|
Media recommendations | Yes |
Media search | No, but very strongly recommended |
Generic recommendations | No, but strongly recommended |
Generic search | No, but strongly recommended |
For help with recording user events, see Record real-time user events.
Depending on the type of search or recommendations app that you're working with, select one of the following to see details of its relevant user events:
User event types
You can record the following types of user events as end users browse your site:
User event name | User action |
---|---|
view-category-page |
Views a category page, such as Home > TV > Dramas, Home > Movies > Action. |
view-item |
Views details of a document. |
view-home-page |
Views home page. |
search |
Searches the data store. |
For detailed information about the UserEvent
object, see the
UserEvent
API reference.
User event type examples and schemas
This section provides the data formats for each event type supported by generic apps.
Examples for JavaScript Pixel are provided. For BigQuery, the full table schema for each type is provided.
For all user events types, userId
is optional.
Note that:
- The
tagIds
field is needed only if you are running an A/B experiment. - The
attributionToken
field is optional; it is used to measure performance.search
andview-item
events that are generated from recommendations clicks should have an attribution token in order to link the events back to the recommendations that generated them.
For more details about the user event object, see the
UserEvent
API reference documentation.
view-category-page
The following shows the view-category-page
user event format.
Minimum required view-category-page object
The following examples show only the required fields of the view-category-page
user event format.
While there is usually only one category associated with a page, the
pageCategories
field also supports a category hierarchy, which you can provide
as a list.
JavaScript Pixel
var user_event = { "eventType": "view-category-page", "userPseudoId": "user-pseudo-id", "eventTime": "2020-01-01T03:33:33.000001Z", "pageInfo": { "pageCategory": "category1 > category2" } };
BigQuery
This is the complete JSON schema for this user event type. Specify this schema when creating tables for this user event type in BigQuery.
Modes for required fields are set to REQUIRED
or REPEATED
. Modes for
optional fields are set to NULLABLE
.
Note that eventTime
is required for importing events with
BigQuery. eventTime
is a string with a Timestamp format.
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "userPseudoId", "type": "STRING", "mode": "REQUIRED" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "userInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "userId", "type": "STRING", "mode": "NULLABLE" }, { "name": "userAgent", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "pageInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "pageviewId", "type": "STRING", "mode": "NULLABLE" }, { "name": "pageCategory", "type": "STRING", "mode": "NULLABLE" }, { "name": "uri", "type": "STRING", "mode": "NULLABLE" }, { "name": "referrerUri", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "attributionToken", "type": "STRING", "mode": "NULLABLE" }, { "name": "documents", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "id", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "tagIds", "type": "STRING", "mode": "REPEATED" }, { "name": "attributes", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "example_text_attribute", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "text", "type": "STRING", "mode": "REPEATED" } ] }, { "name": "example_number_attribute", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "numbers", "type": "NUMERIC", "mode": "REPEATED" } ] } ] } ]
view-item
The following shows the view-item
user event data format.
Minimum required view-item object
The following examples show only the required fields of the view-item
user event format.
In most cases, documents
contains details for the associated document.
JavaScript Pixel
var user_event = { "eventType": "view-item", "userPseudoId": "user-pseudo-id", "eventTime": "2020-01-01T03:33:33.000001Z", "documents": [{ "id": "document-id" }] };
BigQuery
This is the complete JSON schema for this user event type. Specify this schema when creating tables for this user event type in BigQuery.
Modes for required fields are set to REQUIRED
or REPEATED
. Modes for
optional fields are set to NULLABLE
.
Note that eventTime
is required for importing events with
BigQuery. eventTime
is a string with a Timestamp format.
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "userPseudoId", "type": "STRING", "mode": "REQUIRED" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "userInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "userId", "type": "STRING", "mode": "NULLABLE" }, { "name": "userAgent", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "pageInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "pageviewId", "type": "STRING", "mode": "NULLABLE" }, { "name": "uri", "type": "STRING", "mode": "NULLABLE" }, { "name": "referrerUri", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "attributionToken", "type": "STRING", "mode": "NULLABLE" }, { "name": "documents", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "id", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "tagIds", "type": "STRING", "mode": "REPEATED" }, { "name": "attributes", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "example_text_attribute", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "text", "type": "STRING", "mode": "REPEATED" } ] }, { "name": "example_number_attribute", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "numbers", "type": "NUMERIC", "mode": "REPEATED" } ] } ] } ]
view-home-page
The following shows the view-home-page
user event format.
Minimum required view-home-page object
The following examples show only the required fields of the view-home-page
user event format.
JavaScript Pixel
var user_event = { "eventType": "view-home-page", "userPseudoId": "user-pseudo-id", "eventTime": "2020-01-01T03:33:33.000001Z", };
BigQuery
This is the complete JSON schema for this user event type. Specify this schema when creating tables for this user event type in BigQuery.
Modes for required fields are set to REQUIRED
or REPEATED
. Modes for
optional fields are set to NULLABLE
.
Note that eventTime
is required for importing events with
BigQuery. eventTime
is a string with a Timestamp format.
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "userPseudoId", "type": "STRING", "mode": "REQUIRED" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "userInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "userId", "type": "STRING", "mode": "NULLABLE" }, { "name": "userAgent", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "pageInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "pageviewId", "type": "STRING", "mode": "NULLABLE" }, { "name": "uri", "type": "STRING", "mode": "NULLABLE" }, { "name": "referrerUri", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "attributionToken", "type": "STRING", "mode": "NULLABLE" }, { "name": "documents", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "id", "type": "STRING", "mode": "NULLABLE" }, { "name": "quantity", "type": "INT64", "mode": "NULLABLE" } ] }, { "name": "tagIds", "type": "STRING", "mode": "REPEATED" }, { "name": "attributes", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "example_text_attribute", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "text", "type": "STRING", "mode": "REPEATED" } ] }, { "name": "example_number_attribute", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "numbers", "type": "NUMERIC", "mode": "REPEATED" } ] } ] } ]
search
The following shows the search
user event format.
Minimum required search object
The following examples show only the required fields of the search
user event
format.
At least one of searchQuery
or pageCategory
field is required:
Provide
searchQuery
for search events where the user entered a text query.Provide
pageCategory
when the user navigated to items of interest by browsing, that is, by clicking categories instead of by entering a text query.
documents
should include the list of document IDs shown to the end user in
the search results page.
JavaScript Pixel
var user_event = { eventType: "search", userPseudoId: "user-pseudo-id", eventTime: "2020-01-01T03:33:33.000001Z", searchInfo: { searchQuery: "search-query", }, pageInfo: { pageCategory: "category1 > category2", }, attributionToken: "attribution-token", documents: [ { id: "document-id1", }, { id: "document-id2", }, ] };
BigQuery
This is the complete JSON schema for this user event type. Specify this schema when creating tables for this user event type in BigQuery.
Modes for required fields are set to REQUIRED
or REPEATED
. Modes for
optional fields are set to NULLABLE
.
Note that eventTime
is required for importing events with
BigQuery. eventTime
is a string with a Timestamp format.
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "userPseudoId", "type": "STRING", "mode": "REQUIRED" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "searchInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "searchQuery", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "pageInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "pageCategory", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "attributionToken", "type": "STRING", "mode": "NULLABLE" }, { "name": "documents", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "id", "type": "STRING", "mode": "NULLABLE" } ] } ]
About user information
userPseudoId
represents the unique user identifier and is required when you
record a user event.
The user information (UserInfo
) included when you record a user
event contains the userPseudoId
value and, if available, the userId
value.
userId
is optional and can be used as a unique, persistent identifier for a
user across devices whenever a user logs in to your site. When you record the
userId
for a user,
your search and recommendation apps
can generate more personalized results for one user across multiple devices,
such as both a mobile device and a web browser.
About the timestamp
When you record a user event, be sure to include an accurate timestamp of when
the event occurred. Accurate timestamps ensure that your events are stored in
the correct order. Timestamps are recorded automatically for events collected
using the JavaScript Pixel. When you import events, you must provide the
timestamp in the eventTime
field in the format specified by RFC
3339.
What's next
- Learn how to record user events.