This page describes user events for media apps, including user event types, requirements, and examples for user event types.
Recording user events is required for media recommendations apps. Media recommendations apps use real-time user events to generate recommendations. Other app types don't require user events.
The following table lists which app types to upload user events for:
App type | User events required? |
---|---|
Media recommendations | Yes |
Media search | No, but strongly recommended |
Generic recommendations | No |
Generic search | No, but strongly recommended |
For help with recording user events, see Record real-time 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 a detail page of a document. |
view-home-page | Views homepage. |
search | Searches the data store. |
media-play | Clicks play on a media item. |
media-complete | Stops playing a media item, signifying the end of watching. |
For detailed information about the UserEvent
object, see the
UserEvent
API reference.
User event requirements and best practices for media apps
The following tables list requirements and best practices for user event types that media recommendations apps use. Check that your user events fulfill these requirements so that your app can generate quality results.
Also see About media app recommendations types, which lists the types of user events needed depending on the recommendation type and optimization objective you plan to use.
Event type priority for media recommendations
The following table describes the priority of user event types for media recommendations. Some user events are required to use media recommendations. Others are recommended for improving your results, but not required.
Priority | User Events |
---|---|
Required for initial live experiment with media recommendations | |
Important for improving media recommendations result quality over time |
Media recommendations requirements
Make sure your user events meet the following requirements so that your media recommendations 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. |
This ensures 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. |
media-play |
Include exactly one document per event. |
If multiple documents are included, the event is malformed and can't be used. |
User event type examples and schemas
This section provides the data formats for each event type supported by media recommendations.
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 media 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", }, 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": "documents", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "id", "type": "STRING", "mode": "NULLABLE" } ] } ]
media-play
The following shows the media-play
user event format.
Minimum required media-play object
The following examples show only the required fields of the media-play
user
event format.
JavaScript Pixel
var user_event = { "eventType": "media-play", "userPseudoId": "user-pseudo-id", "eventTime": "2020-01-01T03:33:33.000001Z", "documents": [ { "id": "document-id1" } ] };
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" } ] } ] } ]
media-complete
The following shows the media-complete
user event format.
Minimum required media-complete object
The following examples show only the required fields of the media-complete
user event format.
JavaScript Pixel
var user_event = { "eventType": "media-complete", "userPseudoId": "user-pseudo-id", "eventTime": "2020-01-01T03:33:33.000001Z", "documents": [ { "id": "document-id1" } ], "mediaInfo": { "mediaProgressDuration": "65s", "mediaProgressPercentage": 1.2 } };
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" } ] } ] }, { "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. This
can result in improved, more specific recommendations for your users when you
use media recommendations. To add custom attributes, use attributes
when you
record a user event.
If you provide custom attributes for ingested user events, it's important to also include them in the user events that you associate with recommendation requests. The formatting of custom attributes must be consistent between imported events and events provided with recommendation requests. This lets media recommendations apps use those custom attributes to improve quality.
You can provide custom text values by using the text
field or custom
numerical values by using the numbers
field.
For example, the following shows the attributes
section from a request
to 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 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, media recommendations 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.