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 | |
Important for improving model quality over time | |
Nice to have |
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"
}
]
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.
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
- Learn how to record user events.