228 lines
9.5 KiB
Protocol Buffer
228 lines
9.5 KiB
Protocol Buffer
// Copyright 2020 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/annotations.proto";
|
|
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 = "google.golang.org/genproto/googleapis/cloud/retail/v2;retail";
|
|
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.
|
|
// * `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.
|
|
//
|
|
// The field must be a UTF-8 encoded string with a length limit of 128
|
|
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
|
|
string visitor_id = 2 [(google.api.field_behavior) = REQUIRED];
|
|
|
|
// 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].
|
|
//
|
|
// 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 required 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 broswing 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 broswing the whole page yet.
|
|
repeated ProductDetail product_details = 6;
|
|
|
|
// Extra user event features to include in the recommendation model.
|
|
//
|
|
// The key must be a UTF-8 encoded string with a length limit of 5,000
|
|
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
|
|
//
|
|
// For product recommendation, an example of extra user information is
|
|
// traffic_channel, i.e. how user arrives at the site. Users can arrive
|
|
// at the site by coming to the site directly, or coming through Google
|
|
// search, and etc.
|
|
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.
|
|
//
|
|
// The value must be a UTF-8 encoded string with a length limit of 5,000
|
|
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
|
|
//
|
|
// Required for `search` events. Other event types should not set this field.
|
|
// Otherwise, an INVALID_ARGUMENT error is returned.
|
|
string search_query = 10;
|
|
|
|
// 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, 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:
|
|
// "pageCategories" : ["Sales > 2017 Black Friday Deals"].
|
|
//
|
|
// Required for `category-page-view` 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;
|
|
}
|
|
|
|
// Detailed product information associated with a user event.
|
|
message ProductDetail {
|
|
// Required. [Product][google.cloud.retail.v2.Product] information.
|
|
//
|
|
// Only [Product.id][google.cloud.retail.v2.Product.id] field is used when
|
|
// ingesting an event, all other product fields are ignored as we will look
|
|
// them up from the catalog.
|
|
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;
|
|
}
|
|
|
|
// 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];
|
|
}
|