About media user events
This page describes user events for media search and recommendations apps, includinguser event types, requirements, and examples for user event types.User events are required for media apps.
For general information about media search and recommendations, seeIntroduction to media search and recommendations.
For help with recording user events, seeRecord real-time user events. To import past user events inbulk, seeImport historical user events.
Note: For information about user events for custom apps, seeAbout user events.User event types
You can record the following types of user events as end users browse or searchyour site:
| User event name | User action |
|---|---|
view-item | Views details of a document. |
view-home-page | Views home page. |
search | Searches the app. |
media-play | Clicks play on a media item. |
media-complete | Stops playing a media item, signifying the end of watching. |
For details about the user event object, see theUserEvent API reference documentation.
Event requirements for media search and recommendations
The types of user events that you need is determined by whether your app is asearch app or a recommendations app, by the objective (click-through rate,conversion rate, or watch duration), and, for recommendations apps only, by thetype of model that you've chosen. For more information aboutrecommendation model types and optimization objectives, seeAbout media apprecommendations types.
To determine which user events you need to collect, refer to the followingtable.
| Event | search | view-home-page | view-item | media-play | media-complete | ||
|---|---|---|---|---|---|---|---|
| Search use case | |||||||
| Required | Not required | Required | Required | Required | |||
| Recommended for You model type, by objective | |||||||
| CTR | Not required | Required for homepage context Not required for general context | Eitherview-item ormedia-play is required | Strongly recommended Required if history demotion is turned on | |||
| CVR | Not required | Required for homepage context Not required for general context | Eitherview-item ormedia-play is required | Required | |||
| Watch duration | Not required | Required for homepage context Not required for general context | Eitherview-item ormedia-play is required | Required | |||
| Others You May Like model type, by objective | |||||||
| CTR | Not required | Not required | Eitherview-item ormedia-play is required | Strongly recommended Required if history demotion is turned on | |||
| CVR | Not required | Not required | Eitherview-item ormedia-play is required | Required | |||
| Watch duration | Not required | Not required | Eitherview-item ormedia-play is required | Required | |||
| More Like This model type, by objective | |||||||
| CTR | Not required | Not required | Eitherview-item ormedia-play is required | Required if history demotion is turned on | |||
| CVR | Not required | Not required | Eitherview-item ormedia-play is required | Required | |||
| Watch duration | Not required | Not required | Eitherview-item ormedia-play is required | Required | |||
| Most Popular model type, by objective | |||||||
| CTR | Not required | Not required | One ofview-item ormedia-play is required | Not required | |||
| CVR | Not required | Not required | Not required | Not required | Required | ||
Requirements for media user events
Make sure your user events meet the following requirements so that yourmedia apps can generate quality results.
| Event type | Requirement | Impact |
|---|---|---|
| All events | Don't include synthetic data or duplicate events. | Synthetic or duplicate events negatively impact result quality and can prevent you from deploying your app. Duplicate events can cause incorrect metrics values. |
Include at least 100 unique user pseudo IDs for each type of event ingested. | Include these IDs so that media recommendations apps have enough data to generate quality results. | |
User pseudo IDs must be formatted exactly the same across event import or event recording and in media recommendations requests. | Using a consistent format for user pseudo IDs helps media recommendations apps correctly identify visitor patterns and provide better-quality results based on user behavior. | |
The | An event that includes a document without a | |
Documents included in the events should exist in your data store. | The unjoined events ratio should be kept as low as possible. A high ratio can negatively impact the quality of results. | |
Some user events should have the same user pseudo ID. | To construct valid behavior sequence histories, media recommendations apps must be able to see multiple events with the same user pseudo ID. For example, | |
view-item | Include exactly one document per event. | The event can't be used if no document exists. If multiple documents are included, the event is malformed and can't be used. |
search | Include the | The |
media-play | Include exactly one document per event. | If multiple documents are included, the event is malformed and can't be used. |
User event tags for A/B tests
If you do A/B testing, make sure to add tag IDs to all the user eventsthat you collect, adding one tag for each test group.
For example, add the tag"tagIds": ["original"] to the user events from yourcurrent model and add the tag"tagIds": ["google"] to the user events fromVertex AI Search for media.
User event type examples and schemas
This section provides the data formats for each event type supported bymedia recommendations.Examples for JavaScript Pixel are provided. ForBigQuery, the full table schema for each type is provided.
For all user events types,userId is optional.
For more details about the user event object, see theUserEvent API reference documentation.
view-item
The following shows theview-item user event data format.
Search optimization requirements for view-item events
To let search automatically optimize the search experience basedon overall user trends, upload the following data.
Events should be uploaded at least daily with a maximum delay of 24 hours.
| Events metric | Events volume/frequency | Description |
|---|---|---|
Volume ofview-item events | 250k view items | At least 250,000 view items arerequired to optimize the search experience based on events ingested. |
Minimum required view-item object
The following examples show only the required fields of theview-itemuser event format.
In most cases,documents contains details for the associated document.
JavaScript Pixel
varuser_event={"eventType":"view-item","userPseudoId":"USER_PSEUDO_ID","engine":"APP_ID","eventTime":"2020-01-01T03:33:33.000001Z","documents":[{"name":"DOCUMENT_NAME"}],"panels":[{"panelId":"HOME_RFY_1","documents":[{"id":"123"},{"id":"456"}],"panelPosition":1,"totalPanels":2}]};BigQuery
This is the complete JSON schema for this user event type. Specify this schemawhen creating tables for this user event type in BigQuery.
Modes for required fields are set toREQUIRED orREPEATED. Modes foroptional fields are set toNULLABLE.
Note thateventTime is required for importing events withBigQuery.eventTime is a string with a Timestamp format.
[{"name":"eventType","type":"STRING","mode":"REQUIRED"},{"name":"userPseudoId","type":"STRING","mode":"REQUIRED"},{"name":"engine","type":"STRING","mode":"NULLABLE"},{"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"}]}]}]
Complete view-item object example
The following examples include both required and optional fields for theview-item user event.
JavaScript Pixel
varuser_event={"eventType":"view-item","userPseudoId":"visitor0","engine":"APP_ID","eventTime":"2020-01-01T03:33:33.000001Z","userInfo":{"userId":"abc@example.com","userAgent":"Mozilla/5.0",},"pageInfo":{"pageViewId":"currentPageUri","uri":"http://example","referrerUri":"https://google",},"attributionToken":"abcd","documents":[{"id":"abcd",},],"tagIds":["Treatment_B"],"attributes":{"example_text_attribute":{"text":["text_1","text_2"],},"example_number_attribute":{"numbers":[3.14,42,1.2345],},},"panels":[{"panelId":"HOME_RFY_1","documents":[{"id":"123"},{"id":"456"}],"panelPosition":1,"totalPanels":2}]};
BigQuery
This is the complete JSON schema for this user event type. Specify this schemawhen creating tables for this user event type in BigQuery.
Modes for required fields are set toREQUIRED orREPEATED. Modes foroptional fields are set toNULLABLE.
Note thateventTime is required for importing events withBigQuery.eventTime is a string with a Timestamp format.
[{"name":"eventType","type":"STRING","mode":"REQUIRED"},{"name":"userPseudoId","type":"STRING","mode":"REQUIRED"},{"name":"engine","type":"STRING","mode":"NULLABLE"},{"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 theview-home-page user event format.
Minimum required view-home-page object
The following examples show only the required fields of theview-home-pageuser event format.
JavaScript Pixel
varuser_event={"eventType":"view-home-page","userPseudoId":"USER_PSEUDO_ID","engine":"APP_ID","eventTime":"2020-01-01T03:33:33.000001Z","panels":[{"panelId":"HOME_RFY_1","documents":[{"id":"123"},{"id":"456"}],"panelPosition":1,"totalPanels":2}]};BigQuery
This is the complete JSON schema for this user event type. Specify this schemawhen creating tables for this user event type in BigQuery.
Modes for required fields are set toREQUIRED orREPEATED. Modes foroptional fields are set toNULLABLE.
Note thateventTime is required for importing events withBigQuery.eventTime is a string with a Timestamp format.
[{"name":"eventType","type":"STRING","mode":"REQUIRED"},{"name":"userPseudoId","type":"STRING","mode":"REQUIRED"},{"name":"engine","type":"STRING","mode":"NULLABLE"},{"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"}]}]}]
For information about thepanels object, seeAbout panels.
Complete view-home-page object example
The following examples include both required and optional fields for theview-home-page user event.
JavaScript Pixel
varuser_event={"eventType":"view-home-page","userPseudoId":"visitor0","engine":"APP_ID","eventTime":"2020-01-01T03:33:33.000001Z","userInfo":{"userId":"abc@example.com","userAgent":"Mozilla/5.0",},"pageInfo":{"pageViewId":"currentPageUri","uri":"http://example","referrerUri":"https://google",},"attributionToken":"abcd","documents":[{"id":"abcd","quantity":2,},],"tagIds":["Treatment_B"],"attributes":{"example_text_attribute":{"text":["text_1","text_2"],},"example_number_attribute":{"numbers":[3.14,42,1.2345],},},"panels":[{"panelId":"HOME_RFY_1","documents":[{"id":"123"},{"id":"456"}],"panelPosition":1,"totalPanels":2}]};
BigQuery
This is the complete JSON schema for this user event type. Specify this schemawhen creating tables for this user event type in BigQuery.
Modes for required fields are set toREQUIRED orREPEATED. Modes foroptional fields are set toNULLABLE.
Note thateventTime is required for importing events withBigQuery.eventTime is a string with a Timestamp format.
[{"name":"eventType","type":"STRING","mode":"REQUIRED"},{"name":"userPseudoId","type":"STRING","mode":"REQUIRED"},{"name":"engine","type":"STRING","mode":"NULLABLE"},{"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 thesearch user event format.
Search optimization requirements for search events
To let search automatically optimize the search experience based on overall user trends, upload the following data.
Events should be uploaded at least daily with a maximum delay of 24 hours.
| Events metric | Events volume/frequency | Description |
|---|---|---|
Volume ofsearch events | 100k searches | At least 100,000 searches arerequired to optimize the search experience based on events ingested. |
Minimum required search object
The following examples show only the required fields of thesearch user eventformat.
searchQuery for search events where the user entered a text query.TheattributionToken is returned with the search query results.
documents should include the list of document IDs shown to the end user inthe search results page.
JavaScript Pixel
varuser_event={"eventType":"search","userPseudoId":"USER_PSEUDO_ID","engine":"APP_ID","eventTime":"2020-01-01T03:33:33.000001Z","searchInfo":{"searchQuery":"SEARCH_QUERY",},"attributionToken":"ATTRIBUTION_TOKEN","documents":[{"name":"DOCUMENT_NAME_1",},{"name":"DOCUMENT_NAME_2",},]};BigQuery
This is the complete JSON schema for this user event type. Specify this schemawhen creating tables for this user event type in BigQuery.
Modes for required fields are set toREQUIRED orREPEATED. Modes foroptional fields are set toNULLABLE.
Note thateventTime is required for importing events withBigQuery.eventTime is a string with a Timestamp format.
[{"name":"eventType","type":"STRING","mode":"REQUIRED"},{"name":"userPseudoId","type":"STRING","mode":"REQUIRED"},{"name":"engine","type":"STRING","mode":"NULLABLE"},{"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"}]}]
media-play
The following shows themedia-play user event format.
Minimum required media-play object
The following examples show only the required fields of themedia-play userevent format.
JavaScript Pixel
varuser_event={"eventType":"media-play","userPseudoId":"USER_PSEUDO_ID","engine":"APP_ID","eventTime":"2020-01-01T03:33:33.000001Z","documents":[{"name":"DOCUMENT_NAME_1"}]};BigQuery
This is the complete JSON schema for this user event type. Specify this schemawhen creating tables for this user event type in BigQuery.
Modes for required fields are set toREQUIRED orREPEATED. Modes foroptional fields are set toNULLABLE.
Note thateventTime is required for importing events withBigQuery.eventTime is a string with a Timestamp format.
[{"name":"eventType","type":"STRING","mode":"REQUIRED"},{"name":"userPseudoId","type":"STRING","mode":"REQUIRED"},{"name":"engine","type":"STRING","mode":"NULLABLE"},{"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"}]}]}]
Complete media-play object example
The following examples include both required and optional fields for themedia-play user event.
JavaScript Pixel
varuser_event={"eventType":"media-play","userPseudoId":"visitor0","engine":"APP_ID","eventTime":"2020-01-01T03:33:33.000001Z","userInfo":{"userId":"abc@example.com","userAgent":"Mozilla/5.0",},"pageInfo":{"pageViewId":"currentPageUri","uri":"http://example","referrerUri":"https://google",},"attributionToken":"abcd","documents":[{"id":"abcd",},],"tagIds":["Treatment_B"],"attributes":{"example_text_attribute":{"text":["text_1","text_2"],},"example_number_attribute":{"numbers":[3.14,42,1.2345],},},};
BigQuery
This is the complete JSON schema for this user event type. Specify this schemawhen creating tables for this user event type in BigQuery.
Modes for required fields are set toREQUIRED orREPEATED. Modes foroptional fields are set toNULLABLE.
Note thateventTime is required for importing events withBigQuery.eventTime is a string with a Timestamp format.
[{"name":"eventType","type":"STRING","mode":"REQUIRED"},{"name":"userPseudoId","type":"STRING","mode":"REQUIRED"},{"name":"engine","type":"STRING","mode":"NULLABLE"},{"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"}]}]}]
media-complete
The following shows themedia-complete user event format.
Minimum required media-complete object
The following examples show only the required fields of themedia-completeuser event format.
JavaScript Pixel
varuser_event={"eventType":"media-complete","userPseudoId":"USER_PSEUDO_ID","engine":"APP_ID","eventTime":"2020-01-01T03:33:33.000001Z","documents":[{"name":"DOCUMENT_NAME_1"}],"mediaInfo":{"mediaProgressDuration":"65s","mediaProgressPercentage":0.2}};BigQuery
This is the complete JSON schema for this user event type. Specify this schemawhen creating tables for this user event type in BigQuery.
Modes for required fields are set toREQUIRED orREPEATED. Modes foroptional fields are set toNULLABLE.
Note thateventTime is required for importing events withBigQuery.eventTime is a string with a Timestamp format.
[{"name":"eventType","type":"STRING","mode":"REQUIRED"},{"name":"userPseudoId","type":"STRING","mode":"REQUIRED"},{"name":"engine","type":"STRING","mode":"NULLABLE"},{"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"}]}]},{"name":"mediaInfo","type":"RECORD","mode":"NULLABLE","fields":[{"name":"mediaProgressDuration","type":"STRING","mode":"NULLABLE"},{"name":"mediaProgressPercentage","type":"NUMERIC","mode":"NULLABLE"}]}]
Complete media-complete object example
The following examples include both required and optional fields for themedia-complete user event.
JavaScript Pixel
varuser_event={"eventType":"media-complete","userPseudoId":"visitor0","engine":"APP_ID","eventTime":"2020-01-01T03:33:33.000001Z","userInfo":{"userId":"abc@example.com","userAgent":"Mozilla/5.0",},"pageInfo":{"pageViewId":"currentPageUri","uri":"http://example","referrerUri":"https://google",},"attributionToken":"abcd","documents":[{"id":"abcd",},],"tagIds":["Treatment_B"],"attributes":{"example_text_attribute":{"text":["text_1","text_2"],},"example_number_attribute":{"numbers":[3.14,42,1.2345],},},"mediaInfo":{"mediaProgressDuration":"65s","mediaProgressPercentage":0.2,},};
BigQuery
This is the complete JSON schema for this user event type. Specify this schemawhen creating tables for this user event type in BigQuery.
Modes for required fields are set toREQUIRED orREPEATED. Modes foroptional fields are set toNULLABLE.
Note thateventTime is required for importing events withBigQuery.eventTime is a string with a Timestamp format.
[{"name":"eventType","type":"STRING","mode":"REQUIRED"},{"name":"userPseudoId","type":"STRING","mode":"REQUIRED"},{"name":"engine","type":"STRING","mode":"NULLABLE"},{"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"}]}]},{"name":"mediaInfo","type":"RECORD","mode":"NULLABLE","fields":[{"name":"mediaProgressDuration","type":"STRING","mode":"NULLABLE"},{"name":"mediaProgressPercentage","type":"NUMERIC","mode":"NULLABLE"}]}]
Custom attributes
You can include additional custom attributes and features for user events. Thiscan result in improved, more specific results for your users.To add custom attributes, useattributes when yourecord a user event.
If you provide custom attributes for ingested user events, it's important toalso include them in the user events that you associate with recommendation andsearch requests. The formatting of custom attributes must be consistent betweenimported events and events provided with requests. This lets media apps usethose custom attributes to improve quality.
You can provide custom text values by using thetext field or customnumerical values by using thenumbers field.
For example, the following shows theattributes section from a requestto record a user event:
attributes: { user_age: {text: ["teen", "young adult"]}, user_location: {text: ["CA"]}, user_zip: {numbers: [90210]} }About user information
userPseudoId represents the unique user identifier and is required when yourecord a user event.
The user information (UserInfo) included when you record a userevent contains theuserPseudoId value and, if available, theuserId value.userId is optional and can be used as a unique, persistent identifier for auser across devices whenever a user logs in to your site. When you record theuserId for a user,media search and recommendations appscan 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 whenthe event occurred. Accurate timestamps make sure that your events are stored inthe correct order. Timestamps are recorded automatically for events collectedusing the JavaScript Pixel. When you import events, you must provide thetimestamp in theeventTime field in the format specified byRFC3339.
About panels
On a homepage, you'll typically have one or more panels, such asa "trending now" panel and a "recommended for you" panel. On detailpages, you might also have panels, such as "others you may like".
Panel information for user events
Panel information is needed for recommendation user events of typeview-home-page andview-item. Panel information is required for home pagesand detail pages that display content recommended by Google.
If you are conducting A/B testing for a panel, then you must record user eventswith panel information for all content in the test, regardless of source. Forhome pages and detail pages without Google-generated panel content, it isrecommended, but not required, to provide panel information in theview-home-page andview-item events. These requirements are summarized inthe following table:
Source of user event (view-home-page andview-item) | PanelInfo required |
|---|---|
| Includes content recommended by Google | Yes |
| Includes content NOT recommended by Google and used in A/B testing | Yes |
| Includes content NOT recommended by Google and NOT used in A/B testing | No |
Panel information (PanelInfo) is a set of fields that describes variouselements of the panel:
The ID number for the panel
The display name
The position of the panel on the page (e.g., first panel (
1) on thepage, or the third panel (3) on the page)The total number of panels on the page
The list of documents (
DocumentInfo) presented in each panel
For detailed information about thePanelInfo objects, seePanelInfo.
panel and apanels field. Thefield that you need to populate for view-home-page user events is thepanelsfield, which takes an array ofPanelInfo objects.Pre-loading panels versus lazy-loading panels
There are two common methods for displaying recommendations on web pages ormobile pages.The method that you use determines the number and content of theview-home-pageuser events that you record.
Pre-loading: With pre-loading all the recommendation itemsare generated the user arrives at the page. In this case,when the user loads the homepage, you record one
view-home-page(orview-item) user event with all panels and documents.Lazy loading: With lazy loading, panel content is notgenerated when the user arrives on the page, but instead content isdynamically loaded when the user scrolls down to panels or right to see morerecommendations. In this case, when a user loads the homepage, your record aninitial
view-home-page(orview-item) user event and then continue torecord more events when the user scrolls to generate more recommended content.In the subsequent events, you only need to include in thepanelsarray theincrement of documents being displayed.
Example scenario
A media company's home page displays two panels of recommendations:
A trending-now panel that is powered by theMost Popularmodel.
A personalized recommendation panel that is being A/B tested. Some users seea panel of suggestions powered by theRecommended for Youmodel (group-A), and other users see recommendations from the company'sproprietary model (group-B).
When a user assigned to group-B views this home page, the user event inJavaScript Pixel format looks like this:
varuser_event={"eventType":"view-home-page","userPseudoId":"4003345673.123451357","eventTime":"2025-07-01T03:33:33.000001Z","userInfo":{"userId":"jane.doe@example.com",},"tagIds":["group-B"],"panels":[{"panelId":"panel-1","displayId":"Trending Now","documents":[{"id":"254722"},{"id":"2951"},...{"id":"1201"}],"panelPosition":1,"totalPanels":2},{"panelId":"panel-2","displayId":"Recommended for You","documents":[{"id":"79132"},{"id":"109487"},...{"id":"164179"}],"panelPosition":2,"totalPanels":2}]};
What's next
- Learn how torecord user events.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.