About media user events

This page describes user events for media search and recommendations apps, including user event types, requirements, and examples for user event types. User events are required for media apps.

For general information about media search and recommendations, see [Introduction to media search and recommendations][about-media].

For help with recording user events, see [Record real-time user events][record-events]. To import past user events in bulk, see [Import historical user events][import-user-events].

User event types

You can record the following types of user events as end users browse or search your site:

For details about the user event object, see the [UserEvent API reference documentation][user-event].

Event requirements for media search and recommendations

The types of user events that you need is determined by whether your app is a search app or a recommendations app, by the objective (click-through rate, conversion rate, or watch duration), and, for recommendations apps only, by the type of model that you've chosen. For more information about recommendation model types and optimization objectives, see [About media app recommendations types][rec-type-reqs].

To determine which user events you need to collect, refer to the following table.

Requirements for media user events

Make sure your user events meet the following requirements so that your media apps can generate quality results.

User event tags for A/B tests

If you do A/B testing, make sure to add tag IDs to all the user events that you collect, adding one tag for each test group.

For example, add the tag "tagIds": ["original"] to the user events from your current model and add the tag "tagIds": ["google"] to the user events from Agent Search for media.

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.

For more details about the user event object, see the [UserEvent API reference documentation][user-event].

view-item

The following shows the view-item user event data format.

Search optimization requirements for view-item 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.

Minimum required view-item object

The following examples show only the required fields of the view-item user event format.

The documents object contains the document's ID (id) and its resource name (name).

• When you ingest or record user events at a data-store level, you can provide the document's ID (id) or resource name (name).
• When you ingest or record events at a location level, you must supply the document's resource name (name) because it indicates a document's full path and refers to the data store where the document resides. You can provide the document's ID as an optional, additional information.

var user_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
     }
  ]
};

[
  {
    "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",