// Code generated by sidekick. DO NOT EDIT.
//
// Copyright 2026 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.

#if RecommendationService || UserEventService
  import Foundation
  import GoogleCloudWkt

  /// UserEvent captures all metadata information Discovery Engine API needs to
  /// know about how end users interact with your website.
  public struct UserEvent: Codable, Equatable, GoogleCloudWkt._AnyPackable,
    Sendable
  {
    /// 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
    /// * `add-feedback`: Add a user feedback.
    ///
    /// 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.
    ///
    /// Custom conversion value:
    ///
    /// * `conversion`: Customer defined conversion event.
    public var eventType: Swift.String = Swift.String()

    /// Optional. Conversion type.
    ///
    /// Required if
    /// [UserEvent.event_type][google.cloud.discoveryengine.v1.UserEvent.event_type]
    /// is `conversion`. This is a customer-defined conversion name in lowercase
    /// letters or numbers separated by "-", such as "watch", "good-visit" etc.
    ///
    /// Do not set the field if
    /// [UserEvent.event_type][google.cloud.discoveryengine.v1.UserEvent.event_type]
    /// is not `conversion`. This mixes the custom conversion event with predefined
    /// events like `search`, `view-item` etc.
    ///
    /// [google.cloud.discoveryengine.v1.UserEvent.event_type]: <doc:UserEvent/eventType>
    public var conversionType: Swift.String = Swift.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.
    public var userPseudoId: Swift.String = Swift.String()

    /// The [Engine][google.cloud.discoveryengine.v1.Engine] resource name, in the
    /// form of
    /// `projects/{project}/locations/{location}/collections/{collection_id}/engines/{engine_id}`.
    ///
    /// Optional. Only required for
    /// [Engine][google.cloud.discoveryengine.v1.Engine] produced user events. For
    /// example, user events from blended search.
    ///
    /// [google.cloud.discoveryengine.v1.Engine]: <doc:Engine>
    public var engine: Swift.String = Swift.String()

    /// The [DataStore][google.cloud.discoveryengine.v1.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
    /// [UserEvent.engine][google.cloud.discoveryengine.v1.UserEvent.engine] or
    /// [UserEvent.documents][google.cloud.discoveryengine.v1.UserEvent.documents].
    /// If data store is set in the parent of write/import/collect user event
    /// requests, this field can be omitted.
    ///
    /// [google.cloud.discoveryengine.v1.DataStore]: <doc:DataStore>
    /// [google.cloud.discoveryengine.v1.UserEvent.documents]: <doc:UserEvent/documents>
    /// [google.cloud.discoveryengine.v1.UserEvent.engine]: <doc:UserEvent/engine>
    public var dataStore: Swift.String = Swift.String()

    /// Only required for
    /// [UserEventService.ImportUserEvents][google.cloud.discoveryengine.v1.UserEventService.ImportUserEvents]
    /// method. Timestamp of when the user event happened.
    ///
    /// [google.cloud.discoveryengine.v1.UserEventService.ImportUserEvents]: <doc:UserEventService/importUserEvents(request:)>
    public var eventTime: GoogleCloudWkt.Timestamp? = nil

    /// Information about the end user.
    public var userInfo: UserInfo? = nil

    /// Should set to true if the request is made directly from the end user, in
    /// which case the
    /// [UserEvent.user_info.user_agent][google.cloud.discoveryengine.v1.UserInfo.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
    /// [UserEventService.CollectUserEvent][google.cloud.discoveryengine.v1.UserEventService.CollectUserEvent].
    ///
    /// [google.cloud.discoveryengine.v1.UserEventService.CollectUserEvent]: <doc:UserEventService/collectUserEvent(request:)>
    /// [google.cloud.discoveryengine.v1.UserInfo.user_agent]: <doc:UserInfo/userAgent>
    public var directUserRequest: Swift.Bool = Swift.Bool()

    /// 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
    /// [UserEvent.user_pseudo_id][google.cloud.discoveryengine.v1.UserEvent.user_pseudo_id]
    /// as prefix.
    ///
    /// [google.cloud.discoveryengine.v1.UserEvent.user_pseudo_id]: <doc:UserEvent/userPseudoId>
    public var sessionId: Swift.String = Swift.String()

    /// Page metadata such as categories and other critical information for certain
    /// event types such as `view-category-page`.
    public var pageInfo: PageInfo? = nil

    /// Token to attribute an API response to user action(s) to trigger the event.
    ///
    /// Highly recommended for user events that are the result of
    /// [RecommendationService.Recommend][google.cloud.discoveryengine.v1.RecommendationService.Recommend].
    /// This field enables accurate attribution of recommendation model
    /// performance.
    ///
    /// The value must be one of:
    ///
    /// * [RecommendResponse.attribution_token][google.cloud.discoveryengine.v1.RecommendResponse.attribution_token] for events that are the result of
    /// [RecommendationService.Recommend][google.cloud.discoveryengine.v1.RecommendationService.Recommend].
    /// * [SearchResponse.attribution_token][google.cloud.discoveryengine.v1.SearchResponse.attribution_token] for events that are the result of
    /// [SearchService.Search][google.cloud.discoveryengine.v1.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
    /// [RecommendResponse.attribution_token][google.cloud.discoveryengine.v1.RecommendResponse.attribution_token]
    /// as a URL parameter to product K's page. When recording events on product
    /// K's page, log the
    /// [RecommendResponse.attribution_token][google.cloud.discoveryengine.v1.RecommendResponse.attribution_token]
    /// to this field.
    ///
    /// [google.cloud.discoveryengine.v1.RecommendResponse.attribution_token]: <doc:RecommendResponse/attributionToken>
    /// [google.cloud.discoveryengine.v1.RecommendationService.Recommend]: <doc:RecommendationService/recommend(request:)>
    /// [google.cloud.discoveryengine.v1.SearchResponse.attribution_token]: <doc:SearchResponse/attributionToken>
    /// [google.cloud.discoveryengine.v1.SearchService.Search]: <doc:SearchService/search(request:)>
    public var attributionToken: Swift.String = Swift.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
    /// [SearchRequest][google.cloud.discoveryengine.v1.SearchRequest] may contain
    /// a filter expression in
    /// [SearchRequest.filter][google.cloud.discoveryengine.v1.SearchRequest.filter]
    /// conforming to https://google.aip.dev/160#filtering.
    ///
    /// Similarly, for `view-item-list` events that are generated from a
    /// [RecommendRequest][google.cloud.discoveryengine.v1.RecommendRequest], this
    /// field may be populated directly from
    /// [RecommendRequest.filter][google.cloud.discoveryengine.v1.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.
    ///
    /// [google.cloud.discoveryengine.v1.RecommendRequest]: <doc:RecommendRequest>
    /// [google.cloud.discoveryengine.v1.RecommendRequest.filter]: <doc:RecommendRequest/filter>
    /// [google.cloud.discoveryengine.v1.SearchRequest]: <doc:SearchRequest>
    /// [google.cloud.discoveryengine.v1.SearchRequest.filter]: <doc:SearchRequest/filter>
    public var filter: Swift.String = Swift.String()

    /// List of [Document][google.cloud.discoveryengine.v1.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
    /// [UserEvent.documents][google.cloud.discoveryengine.v1.UserEvent.documents]
    /// is desired.
    ///
    /// [google.cloud.discoveryengine.v1.Document]: <doc:Document>
    /// [google.cloud.discoveryengine.v1.UserEvent.documents]: <doc:UserEvent/documents>
    public var documents: [DocumentInfo] = []

    /// Panel metadata associated with this user event.
    public var panel: PanelInfo? = nil

    /// [SearchService.Search][google.cloud.discoveryengine.v1.SearchService.Search]
    /// details related to the event.
    ///
    /// This field should be set for `search` event.
    ///
    /// [google.cloud.discoveryengine.v1.SearchService.Search]: <doc:SearchService/search(request:)>
    public var searchInfo: SearchInfo? = nil

    /// [CompletionService.CompleteQuery][google.cloud.discoveryengine.v1.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.
    ///
    /// [google.cloud.discoveryengine.v1.CompletionService.CompleteQuery]: <doc:CompletionService/completeQuery(request:)>
    public var completionInfo: CompletionInfo? = nil

    /// The transaction metadata (if any) associated with this user event.
    public var transactionInfo: TransactionInfo? = nil

    /// 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.
    public var tagIds: [Swift.String] = []

    /// The promotion IDs if this is an event associated with promotions.
    /// Currently, this field is restricted to at most one ID.
    public var promotionIds: [Swift.String] = []

    /// 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.
    public var attributes: [Swift.String: CustomAttribute] = [:]

    /// Media-specific info.
    public var mediaInfo: MediaInfo? = nil

    /// Optional. List of panels associated with this event.
    /// Used for page-level impression data.
    public var panels: [PanelInfo] = []

    /// Initialize a new instance of `UserEvent`.
    public init() {}

    /// Use `config` to return a new instance of this object, with some fields updated.
    ///
    /// Commonly used to initialize the value, for example:
    ///
    /// ```
    /// let value = UserEvent().with { $0.eventType = ... }
    /// ```
    public func with(_ config: (inout Self) throws -> Swift.Void) rethrows -> Self {
      var copy = self
      try config(&copy)
      return copy
    }

    public static var _anyTypeUrl: Swift.String {
      return "type.googleapis.com/google.cloud.discoveryengine.v1.UserEvent"
    }
    public init(fromAny any: GoogleCloudWkt.`Any`) throws {
      self = try GoogleCloudWkt._slowAnyDeserialize(Self.self, from: any)
    }
    public func _pack() throws -> GoogleCloudWkt.Struct {
      return try GoogleCloudWkt._slowAnySerialize(message: self)
    }
  }
#endif
