user_event.proto

// 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.recommendationengine.v1beta1;

import "google/api/field_behavior.proto";
import "google/cloud/recommendationengine/v1beta1/catalog.proto";
import "google/cloud/recommendationengine/v1beta1/common.proto";
import "google/protobuf/timestamp.proto";
import "google/api/annotations.proto";

option csharp_namespace = "Google.Cloud.RecommendationEngine.V1Beta1";
option go_package = "google.golang.org/genproto/googleapis/cloud/recommendationengine/v1beta1;recommendationengine";
option java_multiple_files = true;
option java_package = "com.google.cloud.recommendationengine.v1beta1";
option objc_class_prefix = "RECAI";
option php_namespace = "Google\\Cloud\\RecommendationEngine\\V1beta1";
option ruby_package = "Google::Cloud::RecommendationEngine::V1beta1";

// UserEvent captures all metadata information recommendation engine needs to
// know about how end users interact with customers' website.
message UserEvent {
  // User event source.
  enum EventSource {
    // Unspecified event source.
    EVENT_SOURCE_UNSPECIFIED = 0;

    // The event is ingested via a javascript pixel or Recommendations AI Tag
    // through automl datalayer or JS Macros.
    AUTOML = 1;

    // The event is ingested via Recommendations AI Tag through Enhanced
    // Ecommerce datalayer.
    ECOMMERCE = 2;

    // The event is ingested via Import user events API.
    BATCH_UPLOAD = 3;
  }

  // Required. User event type. Allowed values are:
  //
  // * `add-to-cart` Products being added to cart.
  // * `add-to-list` Items being added to a list (shopping list, favorites
  //   etc).
  // * `category-page-view` Special pages such as sale or promotion pages
  //   viewed.
  // * `checkout-start` User starting a checkout process.
  // * `detail-page-view` Products detail page viewed.
  // * `home-page-view` Homepage viewed.
  // * `page-visit` Generic page visits not included in the event types above.
  // * `purchase-complete` User finishing a purchase.
  // * `refund` Purchased items being refunded or returned.
  // * `remove-from-cart` Products being removed from cart.
  // * `remove-from-list` Items being removed from a list.
  // * `search` Product search.
  // * `shopping-cart-page-view` User viewing a shopping cart.
  // * `impression` List of items displayed. Used by Google Tag Manager.
  string event_type = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. User information.
  UserInfo user_info = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. User event detailed information common across different
  // recommendation types.
  EventDetail event_detail = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Retail product specific user event metadata.
  //
  // This field is required for the following event types:
  //
  // * `add-to-cart`
  // * `add-to-list`
  // * `category-page-view`
  // * `checkout-start`
  // * `detail-page-view`
  // * `purchase-complete`
  // * `refund`
  // * `remove-from-cart`
  // * `remove-from-list`
  // * `search`
  //
  // This field is optional for the following event types:
  //
  // * `page-visit`
  // * `shopping-cart-page-view` - note that 'product_event_detail' should be
  //   set for this unless the shopping cart is empty.
  //
  // This field is not allowed for the following event types:
  //
  // * `home-page-view`
  ProductEventDetail product_event_detail = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Only required for ImportUserEvents method. Timestamp of user
  // event created.
  google.protobuf.Timestamp event_time = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. This field should *not* be set when using JavaScript pixel
  // or the Recommendations AI Tag. Defaults to `EVENT_SOURCE_UNSPECIFIED`.
  EventSource event_source = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Information of end users.
message UserInfo {
  // Required. A unique identifier for tracking visitors with a length limit of
  // 128 bytes.
  //
  // 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.
  // Maximum length 128 bytes. Cannot be empty.
  string visitor_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Unique identifier for logged-in user with a length limit of 128
  // bytes. Required only for logged-in users.
  string user_id = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. IP address of the user. This could be either IPv4 (e.g. 104.133.9.80) or
  // IPv6 (e.g. 2001:0db8:85a3:0000:0000:8a2e:0370:7334). This should *not* be
  // set when using the javascript pixel or if `direct_user_request` is set.
  // Used to extract location information for personalization.
  string ip_address = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. User agent as included in the HTTP header. UTF-8 encoded string
  // with a length limit of 1 KiB.
  //
  // This should *not* be set when using the JavaScript pixel or if
  // `directUserRequest` is set.
  string user_agent = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Indicates if the request is made directly from the end user
  // in which case the user_agent and ip_address fields can be populated
  // from the HTTP request. This should *not* be set when using the javascript
  // pixel. 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).
  bool direct_user_request = 5 [(google.api.field_behavior) = OPTIONAL];
}

// User event details shared by all recommendation types.
message EventDetail {
  // Optional. Complete url (window.location.href) of the user's current page.
  // When using the JavaScript pixel, this value is filled in automatically.
  // Maximum length 5KB.
  string uri = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The referrer url of the current page. When using
  // the JavaScript pixel, this value is filled in automatically.
  string referrer_uri = 6 [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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 JavaScript pixel.
  string page_view_id = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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 Recommendation
  // Engine system, using different recommendation models).
  repeated string experiment_ids = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Recommendation token included in the recommendation prediction
  // response.
  //
  // This field enables accurate attribution of recommendation model
  // performance.
  //
  // This token enables us to accurately attribute page view or purchase back to
  // the event and the particular predict response containing this
  // clicked/purchased item. If user clicks on product K in the recommendation
  // results, pass the `PredictResponse.recommendationToken` property as a url
  // parameter to product K's page. When recording events on product K's page,
  // log the PredictResponse.recommendation_token to this field.
  //
  // Optional, but highly encouraged for user events that are the result of a
  // recommendation prediction query.
  string recommendation_token = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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.
  FeatureMap event_attributes = 5 [(google.api.field_behavior) = OPTIONAL];
}

// ProductEventDetail captures user event information specific to retail
// products.
message ProductEventDetail {
  // Required for `search` events. Other event types should not set this field.
  // The user's search query as UTF-8 encoded text with a length limit of 5 KiB.
  string search_query = 1;

  // Required for `category-page-view` events. Other event types should not set
  // this field.
  // The categories associated with a category page.
  // Category pages include special pages such as sales or promotions. For
  // instance, a special sale page may have the category hierarchy:
  // categories : ["Sales", "2017 Black Friday Deals"].
  repeated CatalogItem.CategoryHierarchy page_categories = 2;

  // The main product details related to the event.
  //
  // This field is required for the following event types:
  //
  // * `add-to-cart`
  // * `add-to-list`
  // * `checkout-start`
  // * `detail-page-view`
  // * `purchase-complete`
  // * `refund`
  // * `remove-from-cart`
  // * `remove-from-list`
  //
  // This field is optional for the following event types:
  //
  // * `page-visit`
  // * `shopping-cart-page-view` - note that 'product_details' should be set for
  //   this unless the shopping cart is empty.
  //
  // This field is not allowed for the following event types:
  //
  // * `category-page-view`
  // * `home-page-view`
  // * `search`
  repeated ProductDetail product_details = 3;

  // Required for `add-to-list` and `remove-from-list` events. The id or name of
  // the list that the item is being added to or removed from. Other event types
  // should not set this field.
  string list_id = 4;

  // Optional. 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 = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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.
  PurchaseTransaction purchase_transaction = 6 [(google.api.field_behavior) = OPTIONAL];
}

// A transaction represents the entire purchase transaction.
message PurchaseTransaction {
  // Optional. The transaction ID with a length limit of 128 bytes.
  string id = 1 [(google.api.field_behavior) = OPTIONAL];

  // 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];

  // Optional. All the taxes associated with the transaction.
  map<string, float> taxes = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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 - (sum(taxes) + sum(costs))
  // If product_cost is not set, then
  //   profit = revenue - tax - shipping - sum(CatalogItem.costs).
  //
  // If CatalogItem.cost is not specified for one of the items, CatalogItem.cost
  // based profit *cannot* be calculated for this Transaction.
  map<string, float> costs = 4 [(google.api.field_behavior) = OPTIONAL];

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

// Detailed product information associated with a user event.
message ProductDetail {
  // Required. Catalog item ID. UTF-8 encoded string with a length limit of 128
  // characters.
  string id = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Currency code for price/costs. Use three-character ISO-4217
  // code. Required only if originalPrice or displayPrice is set.
  string currency_code = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Original price of the product. If provided, this will override
  // the original price in Catalog for this product.
  float original_price = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Display price of the product (e.g. discounted price). If
  // provided, this will override the display price in Catalog for this product.
  float display_price = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Item stock state. If provided, this overrides the stock state
  // in Catalog for items in this event.
  ProductCatalogItem.StockState stock_state = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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 `add-to-cart` event. Required for `add-to-cart`, `add-to-list`,
  // `remove-from-cart`, `checkout-start`, `purchase-complete`, `refund` event
  // types.
  int32 quantity = 6 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Quantity of the products in stock when a user event happens.
  // Optional. If provided, this overrides the available quantity in Catalog for
  // this event. and can only be set if `stock_status` is set to `IN_STOCK`.
  //
  // Note that if an item is out of stock, you must set the `stock_state` field
  // to be `OUT_OF_STOCK`. Leaving this field unspecified / as zero is not
  // sufficient to mark the item out of stock.
  int32 available_quantity = 7 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Extra features associated with a product in the user event.
  FeatureMap item_attributes = 8 [(google.api.field_behavior) = OPTIONAL];
}