-
Notifications
You must be signed in to change notification settings - Fork 2.3k
/
user_event.proto
350 lines (315 loc) · 14.9 KB
/
user_event.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";
package google.cloud.retail.v2;
import "google/api/field_behavior.proto";
import "google/cloud/retail/v2/common.proto";
import "google/cloud/retail/v2/product.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
option csharp_namespace = "Google.Cloud.Retail.V2";
option go_package = "cloud.google.com/go/retail/apiv2/retailpb;retailpb";
option java_multiple_files = true;
option java_outer_classname = "UserEventProto";
option java_package = "com.google.cloud.retail.v2";
option objc_class_prefix = "RETAIL";
option php_namespace = "Google\\Cloud\\Retail\\V2";
option ruby_package = "Google::Cloud::Retail::V2";
// UserEvent captures all metadata information Retail API needs to know about
// how end users interact with customers' website.
message UserEvent {
// Required. User event type. Allowed values are:
//
// * `add-to-cart`: Products being added to cart.
// * `category-page-view`: Special pages such as sale or promotion pages
// viewed.
// * `detail-page-view`: Products detail page viewed.
// * `home-page-view`: Homepage viewed.
// * `promotion-offered`: Promotion is offered to a user.
// * `promotion-not-offered`: Promotion is not offered to a user.
// * `purchase-complete`: User finishing a purchase.
// * `search`: Product search.
// * `shopping-cart-page-view`: User viewing a shopping cart.
string event_type = 1 [(google.api.field_behavior) = REQUIRED];
// 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.
//
// 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 INVALID_ARGUMENT error is returned.
//
// The field should not contain PII or user-data. We recommend to use Google
// Analytics [Client
// ID](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#clientId)
// for this field.
string visitor_id = 2 [(google.api.field_behavior) = REQUIRED];
// 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 sesion_id:
// 1. If user has no activity for 30 min, a new session_id should be assigned.
// 2. The session_id should be unique across users, suggest use uuid or add
// visitor_id as prefix.
string session_id = 21;
// Only required for
// [UserEventService.ImportUserEvents][google.cloud.retail.v2.UserEventService.ImportUserEvents]
// method. Timestamp of when the user event happened.
google.protobuf.Timestamp event_time = 3;
// 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 (e.g. using Retail API, using different
// recommendation models).
repeated string experiment_ids = 4;
// Highly recommended for user events that are the result of
// [PredictionService.Predict][google.cloud.retail.v2.PredictionService.Predict].
// This field enables accurate attribution of recommendation model
// performance.
//
// The value must be a valid
// [PredictResponse.attribution_token][google.cloud.retail.v2.PredictResponse.attribution_token]
// for user events that are the result of
// [PredictionService.Predict][google.cloud.retail.v2.PredictionService.Predict].
// The value must be a valid
// [SearchResponse.attribution_token][google.cloud.retail.v2.SearchResponse.attribution_token]
// for user events that are the result of
// [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
//
// This token enables us to accurately attribute page view or purchase 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
// [PredictResponse.attribution_token][google.cloud.retail.v2.PredictResponse.attribution_token]
// as a URL parameter to product K's page. When recording events on product
// K's page, log the
// [PredictResponse.attribution_token][google.cloud.retail.v2.PredictResponse.attribution_token]
// to this field.
string attribution_token = 5;
// The main product details related to the event.
//
// This field is optional except for the following event types:
//
// * `add-to-cart`
// * `detail-page-view`
// * `purchase-complete`
//
// In a `search` event, this field represents the products returned to the end
// user on the current page (the end user may have not finished browsing the
// whole page yet). When a new page is returned to the end user, after
// pagination/filtering/ordering even for the same query, a new `search` event
// with different
// [product_details][google.cloud.retail.v2.UserEvent.product_details] is
// desired. The end user may have not finished browsing the whole page yet.
repeated ProductDetail product_details = 6;
// The main auto-completion details related to the event.
//
// This field should be set for `search` event when autocomplete function is
// enabled and the user clicks a suggestion for search.
CompletionDetail completion_detail = 22;
// Extra user event features to include in the recommendation model.
//
// 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 Retail 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 INVALID_ARGUMENT
// error is returned:
//
// * The key must be a UTF-8 encoded string with a length limit of 5,000
// characters.
// * For text attributes, at most 400 values are allowed. Empty values are not
// allowed. Each value must be a UTF-8 encoded string with a length limit of
// 256 characters.
// * For number attributes, at most 400 values are allowed.
//
// For product recommendations, an example of extra user information is
// traffic_channel, which is how a user arrives at the site. Users can arrive
// at the site by coming to the site directly, coming through Google
// search, or in other ways.
map<string, CustomAttribute> attributes = 7;
// The ID or name of the associated shopping cart. This ID is used
// to associate multiple items added or present in the cart before purchase.
//
// This can only be set for `add-to-cart`, `purchase-complete`, or
// `shopping-cart-page-view` events.
string cart_id = 8;
// A transaction represents the entire purchase transaction.
//
// Required for `purchase-complete` events. Other event types should not set
// this field. Otherwise, an INVALID_ARGUMENT error is returned.
PurchaseTransaction purchase_transaction = 9;
// The user's search query.
//
// See [SearchRequest.query][google.cloud.retail.v2.SearchRequest.query] for
// definition.
//
// The value must be a UTF-8 encoded string with a length limit of 5,000
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
//
// At least one of
// [search_query][google.cloud.retail.v2.UserEvent.search_query] or
// [page_categories][google.cloud.retail.v2.UserEvent.page_categories] is
// required for `search` events. Other event types should not set this field.
// Otherwise, an INVALID_ARGUMENT error is returned.
string search_query = 10;
// The filter syntax consists of an expression language for constructing a
// predicate from one or more fields of the products being filtered.
//
// See [SearchRequest.filter][google.cloud.retail.v2.SearchRequest.filter] for
// definition and syntax.
//
// The value must be a UTF-8 encoded string with a length limit of 1,000
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
string filter = 16;
// The order in which products are returned.
//
// See [SearchRequest.order_by][google.cloud.retail.v2.SearchRequest.order_by]
// for definition and syntax.
//
// The value must be a UTF-8 encoded string with a length limit of 1,000
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
//
// This can only be set for `search` events. Other event types should not set
// this field. Otherwise, an INVALID_ARGUMENT error is returned.
string order_by = 17;
// An integer that specifies the current offset for pagination (the 0-indexed
// starting location, amongst the products deemed by the API as relevant).
//
// See [SearchRequest.offset][google.cloud.retail.v2.SearchRequest.offset] for
// definition.
//
// If this field is negative, an INVALID_ARGUMENT is returned.
//
// This can only be set for `search` events. Other event types should not set
// this field. Otherwise, an INVALID_ARGUMENT error is returned.
int32 offset = 18;
// The categories associated with a category page.
//
// To represent full path of category, use '>' sign to separate different
// hierarchies. If '>' is part of the category name, 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:
// "pageCategories" : ["Sales > 2017 Black Friday Deals"].
//
// Required for `category-page-view` events. At least one of
// [search_query][google.cloud.retail.v2.UserEvent.search_query] or
// [page_categories][google.cloud.retail.v2.UserEvent.page_categories] is
// required for `search` events. Other event types should not set this field.
// Otherwise, an INVALID_ARGUMENT error is returned.
repeated string page_categories = 11;
// User information.
UserInfo user_info = 12;
// 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.
string uri = 13;
// 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.
string referrer_uri = 14;
// 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 `pageViewId` property should
// be kept the same for all these events so that they can be grouped together
// properly.
//
// When using the client side event reporting with JavaScript pixel and Google
// Tag Manager, this value is filled in automatically.
string page_view_id = 15;
// The entity for customers that may run multiple different entities, domains,
// sites or regions, for example, `Google US`, `Google Ads`, `Waymo`,
// `google.com`, `youtube.com`, etc.
// It is recommended to set this field to get better per-entity search,
// completion and prediction results.
string entity = 23;
}
// Detailed product information associated with a user event.
message ProductDetail {
// Required. [Product][google.cloud.retail.v2.Product] information.
//
// Required field(s):
//
// * [Product.id][google.cloud.retail.v2.Product.id]
//
// Optional override field(s):
//
// * [Product.price_info][google.cloud.retail.v2.Product.price_info]
//
// If any supported optional fields are provided, we will treat them as a full
// override when looking up product information from the catalog. Thus, it is
// important to ensure that the overriding fields are accurate and
// complete.
//
// All other product fields are ignored and instead populated via catalog
// lookup after event ingestion.
Product product = 1 [(google.api.field_behavior) = REQUIRED];
// Quantity of the product associated with the user event.
//
// For example, this field will be 2 if two products are added to the shopping
// cart for `purchase-complete` event. Required for `add-to-cart` and
// `purchase-complete` event types.
google.protobuf.Int32Value quantity = 2;
}
// Detailed completion information including completion attribution token and
// clicked completion info.
message CompletionDetail {
// Completion attribution token in
// [CompleteQueryResponse.attribution_token][google.cloud.retail.v2.CompleteQueryResponse.attribution_token].
string completion_attribution_token = 1;
// End user selected
// [CompleteQueryResponse.CompletionResult.suggestion][google.cloud.retail.v2.CompleteQueryResponse.CompletionResult.suggestion].
string selected_suggestion = 2;
// End user selected
// [CompleteQueryResponse.CompletionResult.suggestion][google.cloud.retail.v2.CompleteQueryResponse.CompletionResult.suggestion]
// position, starting from 0.
int32 selected_position = 3;
}
// A transaction represents the entire purchase transaction.
message PurchaseTransaction {
// The transaction ID with a length limit of 128 characters.
string id = 1;
// Required. Total non-zero revenue or grand total associated with the
// transaction. This value include shipping, tax, or other adjustments to
// total revenue that you want to include as part of your revenue
// calculations.
float revenue = 2 [(google.api.field_behavior) = REQUIRED];
// All the taxes associated with the transaction.
float tax = 3;
// 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:
//
// * Profit = [revenue][google.cloud.retail.v2.PurchaseTransaction.revenue] -
// [tax][google.cloud.retail.v2.PurchaseTransaction.tax] -
// [cost][google.cloud.retail.v2.PurchaseTransaction.cost]
float cost = 4;
// Required. Currency code. Use three-character ISO-4217 code.
string currency_code = 5 [(google.api.field_behavior) = REQUIRED];
}