User events

This page describes the user event object, including listing potential user event types, and provides sample data for all user event types.

For help with recording user events, see Recording user events.

User event types

There are several user event types that you can record as users browse your retail site:

User event name User action
add-to-cart Adds product to cart
add-to-list Adds product to list
category-page-view Views special pages, such as sale or promotion pages
checkout-start Starts checkout process
detail-page-view Views product detail page
home-page-view Views homepage
page-visit Views generic page not included in other page view events
purchase-complete Completes checkout
refund Returns or is refunded for a purchased product
remove-from-cart Removes product from cart
remove-from-list Removes product from list
search Searches the catalog
shopping-cart-page-view Views shopping cart

For detailed information about the UserEvent object, see UserEvent.

Event type priority

For the highest quality recommendations, we recommend that that you record user events for all event types. The following table describes the priority of the different user event types. You must log the highest priority user events to achieve quality data models.

Not all events are required. Refer to the supported user event types of each type of model.

Priority User Events
Required for initial live experiment

add-to-cart

detail-page-view

home-page-view

purchase-complete
Important for improving model quality over time

checkout-start

category-page-view

remove-from-cart

search

shopping-cart-page-view
Nice to have

add-to-list

page-visit

refund

remove-from-list

User event type examples and schemas

This section provides the data formats for each event type supported by Recommendations AI.

Examples for JavaScript Pixel and Tag Manager are provided. For BigQuery, the full table schema for each type is provided.

For all user events types, user-id is optional. The catalog item information fields (currencyCode, originalPrice, displayPrice, and stockState) are optional; if they are provided, they override the value in the catalog. The experimentIds field is needed only if you are running an A/B experiment.

The recommendation-token field is optional; it is used to measure recommendation performance. Learn more.

For more details about the User Event object, see User Events.

Add to cart

The following shows the add-to-cart user event format.

Minimum required add-to-cart object

The following examples show only the required fields of the add-to-cart user event format.

JavaScript Pixel

var user_event = {
  "eventType": "add-to-cart",
  "userInfo": {
    "visitorId": "visitor-id"
  },
  "productEventDetail": {
    "productDetails": [{
      "id": "product-id",
      "quantity": product-quantity
    }]
  }
}

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'add-to-cart',
        'userInfo': {
           'visitorId': 'visitor-id'
          // You can also define the visitor id directly on
          // the Tag Manager tag.
        },
        'productEventDetail': {
          'productDetails': [{
            'id': 'product-id',
            'quantity': product-quantity
          }]
        }
      }
    }];
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
},
{
    "name": "productEventDetail",
    "type": "RECORD",
    "mode": "REQUIRED",
    "fields": [
        {
            "name": "productDetails",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
                {
                    "name": "id",
                    "type": "STRING",
                    "mode": "REQUIRED"
                },
                {
                    "name": "currencyCode",
                    "type": "STRING",
                    "mode": "NULLABLE"
                },
                {
                    "name": "displayPrice",
                    "type": "FLOAT",
                    "mode": "NULLABLE"
                },
                {
                    "name": "originalPrice",
                    "type": "FLOAT",
                    "mode": "NULLABLE"
                },
                {
                    "name": "quantity",
                    "type": "INTEGER",
                    "mode": "REQUIRED"
                }
            ]
        },
        {
            "name": "cartId",
            "type": "STRING",
            "mode": "NULLABLE"
        }
    ]
},
{
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
},
{
    "name": "userInfo",
    "type": "RECORD",
    "mode": "REQUIRED",
    "fields": [
        {
            "name": "visitorId",
            "type": "STRING",
            "mode": "REQUIRED"
        },
        {
            "name": "userId",
            "type": "STRING",
            "mode": "NULLABLE"
        }
    ]
},
{
    "name": "eventDetail",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
        {
            "name": "recommendationToken",
            "type": "STRING",
            "mode": "NULLABLE"
        },
        {
            "name": "experimentIds",
            "type": "STRING",
            "mode": "REPEATED"
        }
    ]
}
]

Add to list

The following shows the add-to-list user event format.

Minimum required add-to-list object

The following examples show only the required fields of the add-to-list user event format.

JavaScript Pixel

var user_event = {
   "eventType": "add-to-list",
   "userInfo": {
     "visitorId": "visitor-id"
   },
   "productEventDetail": {
     "productDetails": [{
       "id": "product-id",
       "quantity": product-quantity
     }],
     "listId" : "list-id"
   }
}

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'add-to-list',
        'userInfo': {
           'visitorId': 'visitor-id'
          // You can also define the visitor id directly on
          // the Tag Manager tag.
        },
        'productEventDetail': {
          'productDetails': [{
            'id': 'product-id',
            'quantity': product-quantity
          }],
          'listId' : list-id
        }
    }];
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "experimentIds",
        "type": "STRING"
      }
    ],
    "mode": "NULLABLE",
    "name": "eventDetail",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "userId",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "visitorId",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "userInfo",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "REQUIRED",
        "name": "listId",
        "type": "STRING"
      },
      {
        "fields": [
          {
            "mode": "NULLABLE",
            "name": "displayPrice",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "currencyCode",
            "type": "STRING"
          },
          {
            "mode": "REQUIRED",
            "name": "quantity",
            "type": "INTEGER"
          },
          {
            "mode": "NULLABLE",
            "name": "originalPrice",
            "type": "FLOAT"
          },
          {
            "mode": "REQUIRED",
            "name": "id",
            "type": "INTEGER"
          }
        ],
        "mode": "REPEATED",
        "name": "productDetails",
        "type": "RECORD"
      }
    ],
    "mode": "REQUIRED",
    "name": "productEventDetail",
    "type": "RECORD"
  },
  {
    "mode": "REQUIRED",
    "name": "eventType",
    "type": "STRING"
  }
]

Category page view

The following shows the category-page-view user event format.

Minimum required category-page-view object

The following examples show only the required fields of the category-page-view 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": "category-page-view",
    "userInfo": {
      "visitorId": "visitor-id"
    },
    "productEventDetail": {
      "pageCategories": [{
        "categories": ["category1", "category2"]
      }]
    }
}

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'category-page-view',
        'userInfo': {
           "visitorId": "visitor-id"
          // You can also define the user id and visitor id directly on
          // the Tag Manager tag.
        },
        'productEventDetail': {
          'pageCategories': [{
            'categories': ['category1', 'category2']
          }]
        }
      }
    });
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "experimentIds",
        "type": "STRING"
      }
    ],
    "mode": "NULLABLE",
    "name": "eventDetail",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "userId",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "visitorId",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "userInfo",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "fields": [
          {
            "mode": "REPEATED",
            "name": "categories",
            "type": "STRING"
          }
        ],
        "mode": "REPEATED",
        "name": "pageCategories",
        "type": "RECORD"
      }
    ],
    "mode": "REQUIRED",
    "name": "productEventDetail",
    "type": "RECORD"
  },
  {
    "mode": "REQUIRED",
    "name": "eventType",
    "type": "STRING"
  }
]

Checkout start

The following shows the checkout-start user event format.

Minimum required checkout-start object

The following examples show only the required fields of the checkout-start user event format. You must include a productDetail object for each product being purchased.

JavaScript Pixel

var user_event = {
   "eventType": "checkout-start",
   "userInfo": {
     "visitorId": "visitor-id"
   },
   "productEventDetail": {
      "productDetails": [{
        "id": "product-id",
        "quantity": product-quantity
      },
      {
        "id": "product-id",
        "quantity": product-quantity
      }]
  }
}

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'checkout-start',
        'userInfo': {
           'visitorId': 'visitor-id'
          // You can also define the visitor id directly on
          // the Tag Manager tag.
        },
        'productEventDetail': {
           'productDetails': [{
             'id': 'product-id',
             'quantity': product-quantity
           },
           {
            'id': 'product-id',
            'quantity': product-quantity
           }],
         }
      }
    });
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "experimentIds",
        "type": "STRING"
      }
    ],
    "mode": "NULLABLE",
    "name": "eventDetail",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "userId",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "visitorId",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "userInfo",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "fields": [
          {
            "fields": [
              {
                "mode": "NULLABLE",
                "name": "cost",
                "type": "FLOAT"
              },
              {
                "mode": "NULLABLE",
                "name": "manufacturing",
                "type": "FLOAT"
              }
            ],
            "mode": "NULLABLE",
            "name": "costs",
            "type": "RECORD"
          },
          {
            "fields": [
              {
                "mode": "NULLABLE",
                "name": "local",
                "type": "FLOAT"
              },
              {
                "mode": "NULLABLE",
                "name": "state",
                "type": "FLOAT"
              }
            ],
            "mode": "NULLABLE",
            "name": "taxes",
            "type": "RECORD"
          },
          {
            "mode": "NULLABLE",
            "name": "currencyCode",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "revenue",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "id",
            "type": "INTEGER"
          }
        ],
        "mode": "NULLABLE",
        "name": "purchaseTransaction",
        "type": "RECORD"
      },
      {
        "fields": [
          {
            "mode": "REQUIRED",
            "name": "quantity",
            "type": "INTEGER"
          },
          {
            "mode": "NULLABLE",
            "name": "currencyCode",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "displayPrice",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "originalPrice",
            "type": "FLOAT"
          },
          {
            "mode": "REQUIRED",
            "name": "id",
            "type": "INTEGER"
          }
        ],
        "mode": "REPEATED",
        "name": "productDetails",
        "type": "RECORD"
      },
      {
        "mode": "NULLABLE",
        "name": "cartId",
        "type": "INTEGER"
      }
    ],
    "mode": "REQUIRED",
    "name": "productEventDetail",
    "type": "RECORD"
  },
  {
    "mode": "REQUIRED",
    "name": "eventType",
    "type": "STRING"
  }
]

Detail page view

The following shows the detail-page-view user event data format.

Minimum required detail-page-view object

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

In most cases, productDetails contains details for the associated product, unless a bundle of items are being sold together.

JavaScript Pixel

var user_event = {
  "eventType": "detail-page-view",
  "userInfo": {
    "visitorId": "visitor-id"
  },
  "productEventDetail": {
    "productDetails": [{
      "id": "product-id",
    }]
  }
}

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'detail-page-view',
        'userInfo': {
           'visitorId': 'visitor-id'
          // You can also define the visitor id directly on
          // the Tag Manager tag.
        },
        'productEventDetail': {
          'productDetails': [{
            'id': 'product-id',
          }]
        }
      }
    });
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "experimentIds",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "recommendationToken",
        "type": "STRING"
      }
    ],
    "mode": "NULLABLE",
    "name": "eventDetail",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "userId",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "visitorId",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "userInfo",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "fields": [
          {
            "mode": "REQUIRED",
            "name": "id",
            "type": "INTEGER"
          }
        ],
        "mode": "REPEATED",
        "name": "productDetails",
        "type": "RECORD"
      }
    ],
    "mode": "REQUIRED",
    "name": "productEventDetail",
    "type": "RECORD"
  },
  {
    "mode": "REQUIRED",
    "name": "eventType",
    "type": "STRING"
  }
]

Home page view

The following shows the home-page-view user event format.

Minimum required home-page-view object

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

JavaScript Pixel

var user_event = {
  "eventType": "home-page-view",
  "userInfo": {
    "visitorId": "visitor-id"
  },
}

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'home-page-view',
        'userInfo': {
           'visitorId': 'visitor-id'
          // You can also define the visitor id directly on
          // the Tag Manager tag.
        },
      }
    });
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "experimentIds",
        "type": "STRING"
      }
    ],
    "mode": "NULLABLE",
    "name": "eventDetail",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "userId",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "visitorId",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "userInfo",
    "type": "RECORD"
  },
  {
    "mode": "REQUIRED",
    "name": "eventType",
    "type": "STRING"
  }
]

Page Visit

The following shows the page-visit user event data format.

Minimum required page-visit object

The following examples show only the required fields of the page-visit user event format.

JavaScript Pixel

var user_event = {
  "eventType": "page-visit",
  "userInfo": {
    "visitorId": "visitor-id"
  },
}

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'page-visit',
        'userInfo': {
           'visitorId': 'visitor-id'
          // You can also define the visitor id directly on
          // the Tag Manager tag.
        },
      }
    });
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "experimentIds",
        "type": "STRING"
      }
    ],
    "mode": "NULLABLE",
    "name": "eventDetail",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "userId",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "visitorId",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "userInfo",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "fields": [
          {
            "mode": "NULLABLE",
            "name": "id",
            "type": "INTEGER"
          }
        ],
        "mode": "REPEATED",
        "name": "productDetails",
        "type": "RECORD"
      }
    ],
    "mode": "NULLABLE",
    "name": "productEventDetail",
    "type": "RECORD"
  },
  {
    "mode": "REQUIRED",
    "name": "eventType",
    "type": "STRING"
  }
]

Purchase complete

The following shows the purchase-complete user event data format.

Minimum required purchase-complete object

The following examples show only the required fields of the purchase-complete user event format.

JavaScript Pixel

var user_event = {
  "eventType": "purchase-complete",
  "userInfo": {
    "visitorId": "visitor-id"
  },
  "productEventDetail": {
    "productDetails": [{
      "id": "product-id",
      "quantity": product-quantity
      }],
    "purchaseTransaction": {
        "revenue": purchase-revenue,
        "currencyCode": "currency-code"
     }
  },
  "eventTime": "2020-01-01T03:33:33.000001Z"
}

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'purchase-complete',
        'userInfo': {
           'visitorId': 'visitor-id'
          // You can also define the visitor id directly on
          // the Tag Manager tag.
        },
        'productEventDetail': {
          'productDetails': [{
            'id': 'product-id',
            'quantity': product-quantity
          }],
           'purchaseTransaction': {
             'revenue':  purchase-revenue,
             'currencyCode': 'currency-code'
           }
        },
        'eventTime': '2020-01-01T03:33:33.000001Z'
      }
    });
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "experimentIds",
        "type": "STRING"
      }
    ],
    "mode": "NULLABLE",
    "name": "eventDetail",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "userId",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "visitorId",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "userInfo",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "fields": [
          {
            "fields": [
              {
                "mode": "NULLABLE",
                "name": "cost",
                "type": "FLOAT"
              },
              {
                "mode": "NULLABLE",
                "name": "manufacturing",
                "type": "FLOAT"
              }
            ],
            "mode": "NULLABLE",
            "name": "costs",
            "type": "RECORD"
          },
          {
            "fields": [
              {
                "mode": "NULLABLE",
                "name": "local",
                "type": "FLOAT"
              },
              {
                "mode": "NULLABLE",
                "name": "state",
                "type": "FLOAT"
              }
            ],
            "mode": "NULLABLE",
            "name": "taxes",
            "type": "RECORD"
          },
          {
            "mode": "REQUIRED",
            "name": "currencyCode",
            "type": "STRING"
          },
          {
            "mode": "REQUIRED",
            "name": "revenue",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "id",
            "type": "INTEGER"
          }
        ],
        "mode": "REQUIRED",
        "name": "purchaseTransaction",
        "type": "RECORD"
      },
      {
        "fields": [
          {
            "mode": "REQUIRED",
            "name": "quantity",
            "type": "INTEGER"
          },
          {
            "mode": "NULLABLE",
            "name": "displayPrice",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "originalPrice",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "currencyCode",
            "type": "STRING"
          },
          {
            "mode": "REQUIRED",
            "name": "id",
            "type": "INTEGER"
          }
        ],
        "mode": "REPEATED",
        "name": "productDetails",
        "type": "RECORD"
      },
      {
        "mode": "NULLABLE",
        "name": "cartId",
        "type": "INTEGER"
      }
    ],
    "mode": "REQUIRED",
    "name": "productEventDetail",
    "type": "RECORD"
  },
  {
    "mode": "REQUIRED",
    "name": "eventType",
    "type": "STRING"
  }
]

Refund

The following shows the refund user event data format.

Minimum required refund object

The following examples show only the required fields of the refund user event format.

JavaScript Pixel

var user_event = {
  "eventType": "refund",
  "userInfo": {
    "visitorId": "visitor-id"
  },
  "productEventDetail": {
    "productDetails": [{
      "id": "product-id",
      "quantity": product-quantity
    }]
  }
}

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'refund',
        'userInfo': {
           'visitorId': 'visitor-id'
          // You can also define the visitor id directly on
          // the Tag Manager tag.
        },
        'productEventDetail': {
          'productDetails': [{
            'id': 'product-id',
            'quantity': product-quantity
          }]
        }
      }
    });
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "experimentIds",
        "type": "STRING"
      }
    ],
    "mode": "NULLABLE",
    "name": "eventDetail",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "userId",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "visitorId",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "userInfo",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "fields": [
          {
            "mode": "REQUIRED",
            "name": "quantity",
            "type": "INTEGER"
          },
          {
            "mode": "NULLABLE",
            "name": "displayPrice",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "originalPrice",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "currencyCode",
            "type": "STRING"
          },
          {
            "mode": "REQUIRED",
            "name": "id",
            "type": "INTEGER"
          }
        ],
        "mode": "REPEATED",
        "name": "productDetails",
        "type": "RECORD"
      }
    ],
    "mode": "REQUIRED",
    "name": "productEventDetail",
    "type": "RECORD"
  },
  {
    "mode": "REQUIRED",
    "name": "eventType",
    "type": "STRING"
  }
]

Remove from cart

The following shows the remove-from-cart user event data format.

Minimum required remove-from-cart object

The following examples show only the required fields of the remove-from-cart user event format.

JavaScript Pixel

var user_event = {
  "eventType": "remove-from-cart",
  "userInfo": {
    "visitorId": "visitor-id"
  },
  "productEventDetail": {
    "productDetails": [{
      "id": "product-id",
      "quantity": product-quantity
    }]
  }
}

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'remove-from-cart',
        'userInfo': {
           'visitorId': 'visitor-id'
          // You can also define the visitor id directly on
          // the Tag Manager tag.
        },
        'productEventDetail': {
          'productDetails': [{
            'id': 'product-id',
            'quantity': product-quantity
          }]
        }
    });
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "experimentIds",
        "type": "STRING"
      }
    ],
    "mode": "NULLABLE",
    "name": "eventDetail",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "userId",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "visitorId",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "userInfo",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "fields": [
          {
            "mode": "REQUIRED",
            "name": "quantity",
            "type": "INTEGER"
          },
          {
            "mode": "NULLABLE",
            "name": "displayPrice",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "originalPrice",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "currencyCode",
            "type": "STRING"
          },
          {
            "mode": "REQUIRED",
            "name": "id",
            "type": "INTEGER"
          }
        ],
        "mode": "REPEATED",
        "name": "productDetails",
        "type": "RECORD"
      },
      {
        "mode": "NULLABLE",
        "name": "cartId",
        "type": "INTEGER"
      }
    ],
    "mode": "REQUIRED",
    "name": "productEventDetail",
    "type": "RECORD"
  },
  {
    "mode": "REQUIRED",
    "name": "eventType",
    "type": "STRING"
  }
]

Remove from list

The following shows the remove-from-list user event data format.

Minimum required remove-from-list object

The following examples show only the required fields of the remove-from-list user event format.

The listId field is required. The productDetails section is required, and must include the id field. The quantity field is optional.

JavaScript Pixel

var user_event = {
  "eventType": "remove-from-list",
  "userInfo": {
    "visitorId": "visitor-id"
  },
  "productEventDetail": {
    "productDetails": [{
      "id": "product-id",
    }],
    "listId" : "list-id"
  }
}

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'remove-from-list',
        'userInfo': {
           'visitorId': 'visitor-id'
          // You can also define the visitor id directly on
          // the Tag Manager tag.
        },
        'productEventDetail': {
          'productDetails': [{
            'id': 'product-id',
          }],
          'listId' : 'list-id'
        }
      }
    });
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "experimentIds",
        "type": "STRING"
      }
    ],
    "mode": "NULLABLE",
    "name": "eventDetail",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "userId",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "visitorId",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "userInfo",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "REQUIRED",
        "name": "listId",
        "type": "STRING"
      },
      {
        "fields": [
          {
            "mode": "NULLABLE",
            "name": "quantity",
            "type": "INTEGER"
          },
          {
            "mode": "NULLABLE",
            "name": "displayPrice",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "originalPrice",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "currencyCode",
            "type": "STRING"
          },
          {
            "mode": "REQUIRED",
            "name": "id",
            "type": "INTEGER"
          }
        ],
        "mode": "REPEATED",
        "name": "productDetails",
        "type": "RECORD"
      }
    ],
    "mode": "REQUIRED",
    "name": "productEventDetail",
    "type": "RECORD"
  },
  {
    "mode": "REQUIRED",
    "name": "eventType",
    "type": "STRING"
  }
]

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.

The searchQuery field is required.

JavaScript Pixel

var user_event = {
    "eventType": "search",
    "userInfo": {
      "visitorId": "visitor-id"
      },
    "productEventDetail": {
      "searchQuery": "search-query"
    }
  }

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'search',
        'userInfo': {
           'visitorId': 'visitor-id'
          // You can also define the visitor id directly on
          // the Tag Manager tag.
        },
        'productEventDetail': {
          'searchQuery': 'search-query'
        }
      }
    });
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "experimentIds",
        "type": "STRING"
      }
    ],
    "mode": "NULLABLE",
    "name": "eventDetail",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "userId",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "visitorId",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "userInfo",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "REQUIRED",
        "name": "searchQuery",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "productEventDetail",
    "type": "RECORD"
  },
  {
    "mode": "REQUIRED",
    "name": "eventType",
    "type": "STRING"
  }
]

Shopping cart page view

The following shows the shopping-cart-page-view user event data format.

Minimum required shopping-cart-page-view object

The following examples show only the required fields of the shopping-cart-page-view user event format.

Provide the productDetails object unless the shopping cart is empty.

JavaScript Pixel

var user_event = {
  "eventType": "shopping-cart-page-view",
  "userInfo": {
    "visitorId": "visitor-id"
  },
  "productEventDetail": {
    "cartId" : "cart-id",
    "productDetails": [{
      "id": "product-id",
    },
    {
      "id": "product-id",
    }]
  }
}

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'automl': {
        'eventType': 'shopping-cart-page-view',
        'userInfo': {
           'visitorId': 'visitor-id'
          // You can also define the visitor id directly on
          // the Tag Manager tag.
        },
        'productEventDetail': {
          'cartId' : 'cart-id',
          'productDetails': [{
            'id': 'product-id',
          },
          {
            'id': 'product-id',
          }]
        }
      }
    });
</script>

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": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "experimentIds",
        "type": "STRING"
      }
    ],
    "mode": "NULLABLE",
    "name": "eventDetail",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "userId",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "visitorId",
        "type": "STRING"
      }
    ],
    "mode": "REQUIRED",
    "name": "userInfo",
    "type": "RECORD"
  },
  {
    "fields": [
      {
        "fields": [
          {
            "mode": "NULLABLE",
            "name": "quantity",
            "type": "INTEGER"
          },
          {
            "mode": "NULLABLE",
            "name": "currencyCode",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "displayPrice",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "originalPrice",
            "type": "FLOAT"
          },
          {
            "mode": "NULLABLE",
            "name": "currencyCode",
            "type": "STRING"
          },
          {
            "mode": "REQUIRED",
            "name": "id",
            "type": "INTEGER"
          }
        ],
        "mode": "REPEATED",
        "name": "productDetails",
        "type": "RECORD"
      },
      {
        "mode": "REQUIRED",
        "name": "cartId",
        "type": "INTEGER"
      }
    ],
    "mode": "REQUIRED",
    "name": "productEventDetail",
    "type": "RECORD"
  },
  {
    "mode": "REQUIRED",
    "name": "eventType",
    "type": "STRING"
  }
]

Custom attributes

EventAttributes

You can include additional custom attributes and features for catalog items or user events. This can result in improved, more specific recommendations for your users. To add custom attributes, use the eventAttributes field of the eventDetail object when you record a user event.

You can provide custom category values by using the categoricalFeatures field, or custom numerical values by using the numericalFeatures field.

For example, the following shows the eventDetail section from a request to record a user event:

"eventDetail":
{
  "eventAttributes":
    {"categoricalFeatures":
      {
        "colors": {"value": ["blue", "red"]},
        "sizes":  {"value": ["XS", "S", "M"] }
      },
      "numericalFeatures":
      {
        "lengths_cm": {"value":[2.3, 15.4] },
        "heights_cm": {"value":[8.1, 6.4] }
      }
    }
}

About the user information object

The user information (UserInfo) included when you record a user event contains both a visitorId and a userId value.

visitorId represents the unique user identifier and is required when you record a user event.

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, Recommendations AI can generate recommendations based on products that the user browses across multiple devices such as mobile devices 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 Recommendations AI stores events in the correct order. Timestamps are recorded automatically for events collected using Tag Manager and 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