// 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.v2alpha;

import "google/api/annotations.proto";
import "google/api/field_behavior.proto";
import "google/cloud/retail/v2alpha/common.proto";
import "google/cloud/retail/v2alpha/product.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";

option csharp_namespace = "Google.Cloud.Retail.V2Alpha";
option go_package = "google.golang.org/genproto/googleapis/cloud/retail/v2alpha;retail";
option java_multiple_files = true;
option java_outer_classname = "UserEventProto";
option java_package = "com.google.cloud.retail.v2alpha";
option objc_class_prefix = "RETAIL";
option php_namespace = "Google\\Cloud\\Retail\\V2alpha";
option ruby_package = "Google::Cloud::Retail::V2alpha";

// UserEvent captures all metadata information recommendation engine 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`
  // * `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 a 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.v2alpha.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 Recommendations AI,
  // using different recommendation models).
  repeated string experiment_ids = 4;

  // Highly recommended for user events that are the result of
  // [PredictionService.Predict][google.cloud.retail.v2alpha.PredictionService.Predict].
  // This field enables accurate attribution of recommendation model
  // performance.
  //
  // The value must be a valid
  // [PredictResponse.attribute_token][] for user events that are the result of
  // [PredictionService.Predict][google.cloud.retail.v2alpha.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.attribute_token][] as a url
  // parameter to product K's page. When recording events on product K's page,
  // log the [PredictResponse.attribute_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.v2alpha.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.
  //
  // 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`, `remove-from-cart`,
  // `checkout-start`, `purchase-complete`, or `shopping-cart-page-view` events.
  string cart_id = 8;

  // A transaction represents the entire purchase transaction.
  //
  // Required for `purchase-complete` events. Optional for `checkout-start`
  // 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. This `pageViewId` will be
  // automatically generated if using the client side event reporting with
  // JavaScript pixel and Google Tag Manager.
  string page_view_id = 15;
}

// Detailed product information associated with a user event.
message ProductDetail {
  // Required. [Product][google.cloud.retail.v2alpha.Product] information.
  // Only [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 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. This field
  // is not required if the event type is `refund`.
  float revenue = 2 [(google.api.field_behavior) = REQUIRED];

  // All the taxes associated with the transaction.
  float tax = 3;

  // All the costs associated with the product. These can be
  // manufacturing costs, shipping expenses not borne by the end user, or any
  // other costs.
  //
  // Total product cost such that
  //   profit = revenue - tax + [Product][pricing][cost]
  // If product_cost is not set, then
  //   profit = revenue - tax - [Product][pricing][cost].
  //
  // If [Product][pricing][cost] is not specified for one of the products,
  // [Product][pricing][cost] based profit *cannot* be calculated for this
  // Transaction.
  float cost = 4;

  // Required. Currency code. Use three-character ISO-4217 code. This field
  // is not required if the event type is `refund`.
  string currency_code = 5 [(google.api.field_behavior) = REQUIRED];
}
