# frozen_string_literal: true
# Copyright 2023 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
#
# https://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.
# Auto-generated by gapic-generator-ruby. DO NOT EDIT!
module Google
module Cloud
module DiscoveryEngine
module V1beta
# UserEvent captures all metadata information Discovery Engine API needs to
# know about how end users interact with your website.
# @!attribute [rw] event_type
# @return [::String]
# Required. User event type. Allowed values are:
#
# Generic values:
#
# * `search`: Search for Documents.
# * `view-item`: Detailed page view of a Document.
# * `view-item-list`: View of a panel or ordered list of Documents.
# * `view-home-page`: View of the home page.
# * `view-category-page`: View of a category page, e.g. Home > Men > Jeans
#
# Retail-related values:
#
# * `add-to-cart`: Add an item(s) to cart, e.g. in Retail online shopping
# * `purchase`: Purchase an item(s)
#
# Media-related values:
#
# * `media-play`: Start/resume watching a video, playing a song, etc.
# * `media-complete`: Finished or stopped midway through a video, song, etc.
# @!attribute [rw] user_pseudo_id
# @return [::String]
# 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 `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.
# @!attribute [rw] engine
# @return [::String]
# The {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine} resource name, in
# the form of
# `projects/{project}/locations/{location}/collections/{collection_id}/engines/{engine_id}`.
#
# Optional. Only required for
# {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine} produced user events.
# For example, user events from blended search.
# @!attribute [rw] data_store
# @return [::String]
# The {::Google::Cloud::DiscoveryEngine::V1beta::DataStore DataStore} resource
# full name, of the form
# `projects/{project}/locations/{location}/collections/{collection_id}/dataStores/{data_store_id}`.
#
# Optional. Only required for user events whose data store can't by
# determined by
# {::Google::Cloud::DiscoveryEngine::V1beta::UserEvent#engine UserEvent.engine} or
# {::Google::Cloud::DiscoveryEngine::V1beta::UserEvent#documents UserEvent.documents}.
# If data store is set in the parent of write/import/collect user event
# requests, this field can be omitted.
# @!attribute [rw] event_time
# @return [::Google::Protobuf::Timestamp]
# Only required for
# {::Google::Cloud::DiscoveryEngine::V1beta::UserEventService::Client#import_user_events UserEventService.ImportUserEvents}
# method. Timestamp of when the user event happened.
# @!attribute [rw] user_info
# @return [::Google::Cloud::DiscoveryEngine::V1beta::UserInfo]
# Information about the end user.
# @!attribute [rw] direct_user_request
# @return [::Boolean]
# Should set to true if the request is made directly from the end user, in
# which case the
# {::Google::Cloud::DiscoveryEngine::V1beta::UserInfo#user_agent UserEvent.user_info.user_agent}
# can be populated from the HTTP request.
#
# 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
# {::Google::Cloud::DiscoveryEngine::V1beta::UserEventService::Client#collect_user_event UserEventService.CollectUserEvent}.
# @!attribute [rw] session_id
# @return [::String]
# 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 session_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
# {::Google::Cloud::DiscoveryEngine::V1beta::UserEvent#user_pseudo_id UserEvent.user_pseudo_id}
# as prefix.
# @!attribute [rw] page_info
# @return [::Google::Cloud::DiscoveryEngine::V1beta::PageInfo]
# Page metadata such as categories and other critical information for certain
# event types such as `view-category-page`.
# @!attribute [rw] attribution_token
# @return [::String]
# Token to attribute an API response to user action(s) to trigger the event.
#
# Highly recommended for user events that are the result of
# {::Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client#recommend RecommendationService.Recommend}.
# This field enables accurate attribution of recommendation model
# performance.
#
# The value must be one of:
#
# * {::Google::Cloud::DiscoveryEngine::V1beta::RecommendResponse#attribution_token RecommendResponse.attribution_token} for events that are the result of
# {::Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client#recommend RecommendationService.Recommend}.
# * {::Google::Cloud::DiscoveryEngine::V1beta::SearchResponse#attribution_token SearchResponse.attribution_token} for events that are the result of
# {::Google::Cloud::DiscoveryEngine::V1beta::SearchService::Client#search SearchService.Search}.
#
# 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
# {::Google::Cloud::DiscoveryEngine::V1beta::RecommendResponse#attribution_token RecommendResponse.attribution_token}
# as a URL parameter to product K's page. When recording events on product
# K's page, log the
# {::Google::Cloud::DiscoveryEngine::V1beta::RecommendResponse#attribution_token RecommendResponse.attribution_token}
# to this field.
# @!attribute [rw] filter
# @return [::String]
# 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 `search` events, the associated
# {::Google::Cloud::DiscoveryEngine::V1beta::SearchRequest SearchRequest} may
# contain a filter expression in
# {::Google::Cloud::DiscoveryEngine::V1beta::SearchRequest#filter SearchRequest.filter}
# conforming to https://google.aip.dev/160#filtering.
#
# Similarly, for `view-item-list` events that are generated from a
# {::Google::Cloud::DiscoveryEngine::V1beta::RecommendRequest RecommendRequest},
# this field may be populated directly from
# {::Google::Cloud::DiscoveryEngine::V1beta::RecommendRequest#filter RecommendRequest.filter}
# conforming to https://google.aip.dev/160#filtering.
#
# The value must be a UTF-8 encoded string with a length limit of 1,000
# characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
# @!attribute [rw] documents
# @return [::Array<::Google::Cloud::DiscoveryEngine::V1beta::DocumentInfo>]
# List of {::Google::Cloud::DiscoveryEngine::V1beta::Document Document}s
# associated with this user event.
#
# This field is optional except for the following event types:
#
# * `view-item`
# * `add-to-cart`
# * `purchase`
# * `media-play`
# * `media-complete`
#
# In a `search` event, this field represents the documents 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
# {::Google::Cloud::DiscoveryEngine::V1beta::UserEvent#documents UserEvent.documents}
# is desired.
# @!attribute [rw] panel
# @return [::Google::Cloud::DiscoveryEngine::V1beta::PanelInfo]
# Panel metadata associated with this user event.
# @!attribute [rw] search_info
# @return [::Google::Cloud::DiscoveryEngine::V1beta::SearchInfo]
# {::Google::Cloud::DiscoveryEngine::V1beta::SearchService::Client#search SearchService.Search}
# details related to the event.
#
# This field should be set for `search` event.
# @!attribute [rw] completion_info
# @return [::Google::Cloud::DiscoveryEngine::V1beta::CompletionInfo]
# {::Google::Cloud::DiscoveryEngine::V1beta::CompletionService::Client#complete_query CompletionService.CompleteQuery}
# 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.
# @!attribute [rw] transaction_info
# @return [::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo]
# The transaction metadata (if any) associated with this user event.
# @!attribute [rw] tag_ids
# @return [::Array<::String>]
# 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.
# @!attribute [rw] promotion_ids
# @return [::Array<::String>]
# The promotion IDs if this is an event associated with promotions.
# Currently, this field is restricted to at most one ID.
# @!attribute [rw] attributes
# @return [::Google::Protobuf::Map{::String => ::Google::Cloud::DiscoveryEngine::V1beta::CustomAttribute}]
# 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
# `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.
# @!attribute [rw] media_info
# @return [::Google::Cloud::DiscoveryEngine::V1beta::MediaInfo]
# Media-specific info.
class UserEvent
include ::Google::Protobuf::MessageExts
extend ::Google::Protobuf::MessageExts::ClassMethods
# @!attribute [rw] key
# @return [::String]
# @!attribute [rw] value
# @return [::Google::Cloud::DiscoveryEngine::V1beta::CustomAttribute]
class AttributesEntry
include ::Google::Protobuf::MessageExts
extend ::Google::Protobuf::MessageExts::ClassMethods
end
end
# Detailed page information.
# @!attribute [rw] pageview_id
# @return [::String]
# 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 `pageview_id` 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.
# @!attribute [rw] page_category
# @return [::String]
# 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, 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:
# `"pageCategory" : "Sales > 2017 Black Friday Deals"`.
#
# Required for `view-category-page` events. Other event types should not set
# this field. Otherwise, an `INVALID_ARGUMENT` error is returned.
# @!attribute [rw] uri
# @return [::String]
# 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.
# @!attribute [rw] referrer_uri
# @return [::String]
# 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.
class PageInfo
include ::Google::Protobuf::MessageExts
extend ::Google::Protobuf::MessageExts::ClassMethods
end
# Detailed search information.
# @!attribute [rw] search_query
# @return [::String]
# The user's search query.
#
# See
# {::Google::Cloud::DiscoveryEngine::V1beta::SearchRequest#query 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
# {::Google::Cloud::DiscoveryEngine::V1beta::SearchInfo#search_query search_query}
# or
# {::Google::Cloud::DiscoveryEngine::V1beta::PageInfo#page_category PageInfo.page_category}
# is required for `search` events. Other event types should not set this
# field. Otherwise, an `INVALID_ARGUMENT` error is returned.
# @!attribute [rw] order_by
# @return [::String]
# The order in which products are returned, if applicable.
#
# See
# {::Google::Cloud::DiscoveryEngine::V1beta::SearchRequest#order_by 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.
# @!attribute [rw] offset
# @return [::Integer]
# An integer that specifies the current offset for pagination (the 0-indexed
# starting location, amongst the products deemed by the API as relevant).
#
# See
# {::Google::Cloud::DiscoveryEngine::V1beta::SearchRequest#offset 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.
class SearchInfo
include ::Google::Protobuf::MessageExts
extend ::Google::Protobuf::MessageExts::ClassMethods
end
# Detailed completion information including completion attribution token and
# clicked completion info.
# @!attribute [rw] selected_suggestion
# @return [::String]
# End user selected
# {::Google::Cloud::DiscoveryEngine::V1beta::CompleteQueryResponse::QuerySuggestion#suggestion CompleteQueryResponse.QuerySuggestion.suggestion}.
# @!attribute [rw] selected_position
# @return [::Integer]
# End user selected
# {::Google::Cloud::DiscoveryEngine::V1beta::CompleteQueryResponse::QuerySuggestion#suggestion CompleteQueryResponse.QuerySuggestion.suggestion}
# position, starting from 0.
class CompletionInfo
include ::Google::Protobuf::MessageExts
extend ::Google::Protobuf::MessageExts::ClassMethods
end
# A transaction represents the entire purchase transaction.
# @!attribute [rw] value
# @return [::Float]
# 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.
# @!attribute [rw] currency
# @return [::String]
# Required. Currency code. Use three-character ISO-4217 code.
# @!attribute [rw] transaction_id
# @return [::String]
# The transaction ID with a length limit of 128 characters.
# @!attribute [rw] tax
# @return [::Float]
# All the taxes associated with the transaction.
# @!attribute [rw] cost
# @return [::Float]
# 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 =
# {::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo#value value} -
# {::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo#tax tax} -
# {::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo#cost cost}
# @!attribute [rw] discount_value
# @return [::Float]
# The total discount(s) value applied to this transaction.
# This figure should be excluded from
# {::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo#value TransactionInfo.value}
#
# For example, if a user paid
# {::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo#value TransactionInfo.value}
# amount, then nominal (pre-discount) value of the transaction is the sum of
# {::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo#value TransactionInfo.value}
# and
# {::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo#discount_value TransactionInfo.discount_value}
#
# This means that profit is calculated the same way, regardless of the
# discount value, and that
# {::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo#discount_value TransactionInfo.discount_value}
# can be larger than
# {::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo#value TransactionInfo.value}:
#
# * Profit =
# {::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo#value value} -
# {::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo#tax tax} -
# {::Google::Cloud::DiscoveryEngine::V1beta::TransactionInfo#cost cost}
class TransactionInfo
include ::Google::Protobuf::MessageExts
extend ::Google::Protobuf::MessageExts::ClassMethods
end
# Detailed document information associated with a user event.
# @!attribute [rw] id
# @return [::String]
# The {::Google::Cloud::DiscoveryEngine::V1beta::Document Document} resource ID.
# @!attribute [rw] name
# @return [::String]
# The {::Google::Cloud::DiscoveryEngine::V1beta::Document Document} resource
# full name, of the form:
# `projects/{project_id}/locations/{location}/collections/{collection_id}/dataStores/{data_store_id}/branches/{branch_id}/documents/{document_id}`
# @!attribute [rw] uri
# @return [::String]
# The {::Google::Cloud::DiscoveryEngine::V1beta::Document Document} URI - only
# allowed for website data stores.
# @!attribute [rw] quantity
# @return [::Integer]
# Quantity of the Document associated with the user event. Defaults to 1.
#
# For example, this field is 2 if two quantities of the same Document
# are involved in a `add-to-cart` event.
#
# Required for events of the following event types:
#
# * `add-to-cart`
# * `purchase`
# @!attribute [rw] promotion_ids
# @return [::Array<::String>]
# The promotion IDs associated with this Document.
# Currently, this field is restricted to at most one ID.
class DocumentInfo
include ::Google::Protobuf::MessageExts
extend ::Google::Protobuf::MessageExts::ClassMethods
end
# Detailed panel information associated with a user event.
# @!attribute [rw] panel_id
# @return [::String]
# Required. The panel ID.
# @!attribute [rw] display_name
# @return [::String]
# The display name of the panel.
# @!attribute [rw] panel_position
# @return [::Integer]
# The ordered position of the panel, if shown to the user with other panels.
# If set, then
# {::Google::Cloud::DiscoveryEngine::V1beta::PanelInfo#total_panels total_panels}
# must also be set.
# @!attribute [rw] total_panels
# @return [::Integer]
# The total number of panels, including this one, shown to the user.
# Must be set if
# {::Google::Cloud::DiscoveryEngine::V1beta::PanelInfo#panel_position panel_position}
# is set.
class PanelInfo
include ::Google::Protobuf::MessageExts
extend ::Google::Protobuf::MessageExts::ClassMethods
end
# Media-specific user event information.
# @!attribute [rw] media_progress_duration
# @return [::Google::Protobuf::Duration]
# The media progress time in seconds, if applicable.
# For example, if the end user has finished 90 seconds of a playback video,
# then
# {::Google::Protobuf::Duration#seconds MediaInfo.media_progress_duration.seconds}
# should be set to 90.
# @!attribute [rw] media_progress_percentage
# @return [::Float]
# Media progress should be computed using only the
# {::Google::Cloud::DiscoveryEngine::V1beta::MediaInfo#media_progress_duration media_progress_duration}
# relative to the media total length.
#
# This value must be between `[0, 1.0]` inclusive.
#
# If this is not a playback or the progress cannot be computed (e.g. ongoing
# livestream), this field should be unset.
class MediaInfo
include ::Google::Protobuf::MessageExts
extend ::Google::Protobuf::MessageExts::ClassMethods
end
end
end
end
end