- Resource: UserEvent
- UserInfo
- PageInfo
- DocumentInfo
- PanelInfo
- SearchInfo
- CompletionInfo
- TransactionInfo
- MediaInfo
- Methods
Resource: UserEvent
UserEvent captures all metadata information Discovery Engine API needs to know about how end users interact with customers' website.
JSON representation |
---|
{ "eventType": string, "userPseudoId": string, "eventTime": string, "userInfo": { object ( |
Fields | |
---|---|
eventType |
Required. User event type. Allowed values are: Generic values:
Retail-related values:
Media-related values:
|
userPseudoId |
Required. A unique identifier for tracking visitors. For example, this could be implemented with an HTTP cookie, which should be able to uniquely identify a visitor on a single device. This unique identifier should not change if the visitor log in/out of the website. Do not set the field to the same fixed ID for different users. This mixes the event history of those users together, which results in degraded model quality. The field must be a UTF-8 encoded string with a length limit of 128 characters. Otherwise, an The field should not contain PII or user-data. We recommend to use Google Analytics Client ID for this field. |
eventTime |
Only required for A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
userInfo |
Information about the end user. |
directUserRequest |
Should set to true if the request is made directly from the end user, in which case the This flag should be set only if the API request is made directly from the end user such as a mobile app (and not if a gateway or a server is processing and pushing the user events). This should not be set when using the JavaScript tag in |
sessionId |
A unique identifier for tracking a visitor session with a length limit of 128 bytes. A session is an aggregation of an end user behavior in a time span. A general guideline to populate the sessionId:
|
pageInfo |
Page metadata such as categories and other critical information for certain event types such as |
attributionToken |
Token to attribute an API response to user action(s) to trigger the event. Highly recommended for user events that are the result of The value must be one of:
This token enables us to accurately attribute page view or conversion completion back to the event and the particular predict response containing this clicked/purchased product. If user clicks on product K in the recommendation results, pass |
filter |
The filter syntax consists of an expression language for constructing a predicate from one or more fields of the documents being filtered. One example is for Similarly, for The value must be a UTF-8 encoded string with a length limit of 1,000 characters. Otherwise, an |
documents[] |
List of This field is optional except for the following event types:
In a |
panel |
Panel metadata associated with this user event. |
searchInfo |
This field should be set for |
completionInfo |
This field should be set for |
transactionInfo |
The transaction metadata (if any) associated with this user event. |
tagIds[] |
A list of identifiers for the independent experiment groups this user event belongs to. This is used to distinguish between user events associated with different experiment setups on the customer end. |
promotionIds[] |
The promotion IDs if this is an event associated with promotions. Currently, this field is restricted to at most one ID. |
attributes |
Extra user event features to include in the recommendation model. These attributes must NOT contain data that needs to be parsed or processed further, e.g. JSON or other encodings. If you provide custom attributes for ingested user events, also include them in the user events that you associate with prediction requests. Custom attribute formatting must be consistent between imported events and events provided with prediction requests. This lets the Discovery Engine API use those custom attributes when training models and serving predictions, which helps improve recommendation quality. This field needs to pass all below criteria, otherwise an
For product recommendations, an example of extra user information is |
attributes.text[] |
The textual values of this custom attribute. For example, Empty string is not allowed. Otherwise, an Exactly one of |
attributes.numbers[] |
The numerical values of this custom attribute. For example, Exactly one of |
mediaInfo |
Media-specific info. |
UserInfo
Information of an end user.
JSON representation |
---|
{ "userId": string, "userAgent": string } |
Fields | |
---|---|
userId |
Highly recommended for logged-in users. Unique identifier for logged-in user, such as a user name. Don't set for anonymous users. Always use a hashed value for this ID. Don't set the field to the same fixed ID for different users. This mixes the event history of those users together, which results in degraded model quality. The field must be a UTF-8 encoded string with a length limit of 128 characters. Otherwise, an |
userAgent |
User agent as included in the HTTP header. The field must be a UTF-8 encoded string with a length limit of 1,000 characters. Otherwise, an This should not be set when using the client side event reporting with GTM or JavaScript tag in |
PageInfo
Detailed page information.
JSON representation |
---|
{ "pageviewId": string, "pageCategory": string, "uri": string, "referrerUri": string } |
Fields | |
---|---|
pageviewId |
A unique ID of a web page view. This should be kept the same for all user events triggered from the same pageview. For example, an item detail page view could trigger multiple events as the user is browsing the page. The When using the client side event reporting with JavaScript pixel and Google Tag Manager, this value is filled in automatically. |
pageCategory |
The most specific category associated with a category page. To represent full path of category, use '>' sign to separate different hierarchies. If '>' is part of the category name, please replace it with other character(s). Category pages include special pages such as sales or promotions. For instance, a special sale page may have the category hierarchy: Required for |
uri |
Complete URL (window.location.href) of the user's current page. When using the client side event reporting with JavaScript pixel and Google Tag Manager, this value is filled in automatically. Maximum length 5,000 characters. |
referrerUri |
The referrer URL of the current page. When using the client side event reporting with JavaScript pixel and Google Tag Manager, this value is filled in automatically. However, some browser privacy restrictions may cause this field to be empty. |
DocumentInfo
Detailed document information associated with a user event.
JSON representation |
---|
{ "promotionIds": [ string ], // Union field |
Fields | |
---|---|
promotionIds[] |
The promotion IDs associated with this Document. Currently, this field is restricted to at most one ID. |
Union field
|
|
id |
The |
name |
The |
uri |
The |
quantity |
Quantity of the Document associated with the user event. Defaults to 1. For example, this field will be 2 if two quantities of the same Document are involved in a Required for events of the following event types:
|
PanelInfo
Detailed panel information associated with a user event.
JSON representation |
---|
{ "panelId": string, "displayName": string, "panelPosition": integer, "totalPanels": integer } |
Fields | |
---|---|
panelId |
Required. The panel ID. |
displayName |
The display name of the panel. |
panelPosition |
The ordered position of the panel, if shown to the user with other panels. If set, then |
totalPanels |
The total number of panels, including this one, shown to the user. Must be set if |
SearchInfo
Detailed search information.
JSON representation |
---|
{ "searchQuery": string, "orderBy": string, "offset": integer } |
Fields | |
---|---|
searchQuery |
The user's search query. See The value must be a UTF-8 encoded string with a length limit of 5,000 characters. Otherwise, an At least one of |
orderBy |
The order in which products are returned, if applicable. See The value must be a UTF-8 encoded string with a length limit of 1,000 characters. Otherwise, an This can only be set for |
offset |
An integer that specifies the current offset for pagination (the 0-indexed starting location, amongst the products deemed by the API as relevant). See If this field is negative, an This can only be set for |
CompletionInfo
Detailed completion information including completion attribution token and clicked completion info.
JSON representation |
---|
{ "selectedSuggestion": string, "selectedPosition": integer } |
Fields | |
---|---|
selectedSuggestion |
End user selected |
selectedPosition |
End user selected |
TransactionInfo
A transaction represents the entire purchase transaction.
JSON representation |
---|
{ "currency": string, "transactionId": string, "value": number, "tax": number, "cost": number, "discountValue": number } |
Fields | |
---|---|
currency |
Required. Currency code. Use three-character ISO-4217 code. |
transactionId |
The transaction ID with a length limit of 128 characters. |
value |
Required. Total non-zero value associated with the transaction. This value may include shipping, tax, or other adjustments to the total value that you want to include. |
tax |
All the taxes associated with the transaction. |
cost |
All the costs associated with the products. These can be manufacturing costs, shipping expenses not borne by the end user, or any other costs, such that: |
discountValue |
The total discount(s) value applied to this transaction. This figure should be excluded from For example, if a user paid This means that profit is calculated the same way, regardless of the discount value, and that |
MediaInfo
Media-specific user event information.
JSON representation |
---|
{ "mediaProgressDuration": string, "mediaProgressPercentage": number } |
Fields | |
---|---|
mediaProgressDuration |
The media progress time in seconds, if applicable. For example, if the end user has finished 90 seconds of a playback video, then A duration in seconds with up to nine fractional digits, ending with ' |
mediaProgressPercentage |
Media progress should be computed using only the This value must be between If this is not a playback or the progress cannot be computed (e.g. ongoing livestream), this field should be unset. |
Methods |
|
---|---|
|
Writes a single user event from the browser. |
|
Bulk import of User events. |
|
Writes a single user event. |