@google-cloud/discoveryengine 0.1.0

package/build/protos/google/cloud/discoveryengine/v1beta/recommendation_service.proto

@@ -0,0 +1,182 @@
+// Copyright 2022 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.discoveryengine.v1beta;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/cloud/discoveryengine/v1beta/document.proto";
+import "google/cloud/discoveryengine/v1beta/user_event.proto";
+import "google/protobuf/struct.proto";
+
+option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Beta";
+option go_package = "google.golang.org/genproto/googleapis/cloud/discoveryengine/v1beta;discoveryengine";
+option java_multiple_files = true;
+option java_outer_classname = "RecommendationServiceProto";
+option java_package = "com.google.cloud.discoveryengine.v1beta";
+option objc_class_prefix = "DISCOVERYENGINE";
+option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1beta";
+option ruby_package = "Google::Cloud::DiscoveryEngine::V1beta";
+
+// Service for making recommendations.
+service RecommendationService {
+  option (google.api.default_host) = "discoveryengine.googleapis.com";
+  option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/cloud-platform";
+
+  // Makes a recommendation, which requires a contextual user event.
+  rpc Recommend(RecommendRequest) returns (RecommendResponse) {
+    option (google.api.http) = {
+      post: "/v1beta/{serving_config=projects/*/locations/*/dataStores/*/servingConfigs/*}:recommend"
+      body: "*"
+    };
+  }
+}
+
+// Request message for Recommend method.
+message RecommendRequest {
+  // Required. Full resource name of the format:
+  // projects/*/locations/global/dataStores/*/servingConfigs/*
+  //
+  // Before you can request recommendations from your model, you must create at
+  // least one serving config  for it.
+  string serving_config = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/ServingConfig"
+    }
+  ];
+
+  // Required. Context about the user, what they are looking at and what action
+  // they took to trigger the Recommend request. Note that this user event
+  // detail won't be ingested to userEvent logs. Thus, a separate userEvent
+  // write request is required for event logging.
+  //
+  // Don't set
+  // [UserEvent.user_pseudo_id][google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id]
+  // or
+  // [UserEvent.user_info.user_id][google.cloud.discoveryengine.v1beta.UserInfo.user_id]
+  // to the same fixed ID for different users. If you are trying to receive
+  // non-personalized recommendations (not recommended; this can negatively
+  // impact model performance), instead set
+  // [UserEvent.user_pseudo_id][google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id]
+  // to a random unique ID and leave
+  // [UserEvent.user_info.user_id][google.cloud.discoveryengine.v1beta.UserInfo.user_id]
+  // unset.
+  UserEvent user_event = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Maximum number of results to return. Set this property
+  // to the number of recommendation results needed. If zero, the service will
+  // choose a reasonable default. The maximum allowed value is 100. Values
+  // above 100 will be coerced to 100.
+  int32 page_size = 3;
+
+  // Filter for restricting recommendation results with a length limit of 5,000
+  // characters. Currently, only filter expressions on the `filter_tags`
+  // attribute is supported.
+  //
+  //
+  // Examples:
+  //
+  //  * (filter_tags: ANY("Red", "Blue") OR filter_tags: ANY("Hot", "Cold"))
+  //  * (filter_tags: ANY("Red", "Blue")) AND NOT (filter_tags: ANY("Green"))
+  //
+  // If your filter blocks all results, the API will return generic
+  // (unfiltered) popular Documents. If you only want results strictly matching
+  // the filters, set `strictFiltering` to True in
+  // [RecommendRequest.params][google.cloud.discoveryengine.v1beta.RecommendRequest.params]
+  // to receive empty results instead.
+  //
+  // Note that the API will never return Documents with storageStatus of
+  // "EXPIRED" or "DELETED" regardless of filter choices.
+  string filter = 4;
+
+  // Use validate only mode for this recommendation query. If set to true, a
+  // fake model will be used that returns arbitrary Document IDs.
+  // Note that the validate only mode should only be used for testing the API,
+  // or if the model is not ready.
+  bool validate_only = 5;
+
+  // Additional domain specific parameters for the recommendations.
+  //
+  // Allowed values:
+  //
+  // * `returnDocument`: Boolean. If set to true, the associated Document
+  //    object will be returned in
+  //    [RecommendResponse.results.document][RecommendationResult.document].
+  // * `returnScore`: Boolean. If set to true, the recommendation 'score'
+  //    corresponding to each returned Document will be set in
+  //    [RecommendResponse.results.metadata][RecommendationResult.metadata]. The
+  //    given 'score' indicates the probability of a Document conversion given
+  //    the user's context and history.
+  // * `strictFiltering`: Boolean. True by default. If set to false, the service
+  //    will return generic (unfiltered) popular Documents instead of empty if
+  //    your filter blocks all recommendation results.
+  // * `diversityLevel`: String. Default empty. If set to be non-empty, then
+  //    it needs to be one of:
+  //    *  'no-diversity'
+  //    *  'low-diversity'
+  //    *  'medium-diversity'
+  //    *  'high-diversity'
+  //    *  'auto-diversity'
+  //    This gives request-level control and adjusts recommendation results
+  //    based on Document category.
+  map<string, google.protobuf.Value> params = 6;
+}
+
+// Response message for Recommend method.
+message RecommendResponse {
+  // RecommendationResult represents a generic recommendation result with
+  // associated metadata.
+  message RecommendationResult {
+    // Resource ID of the recommended Document.
+    string id = 1;
+
+    // Set if `returnDocument` is set to true in
+    // [RecommendRequest.params][google.cloud.discoveryengine.v1beta.RecommendRequest.params].
+    Document document = 2;
+
+    // Additional Document metadata / annotations.
+    //
+    // Possible values:
+    //
+    // * `score`: Recommendation score in double value. Is set if
+    //   `returnScore` is set to true in
+    //   [RecommendRequest.params][google.cloud.discoveryengine.v1beta.RecommendRequest.params].
+    map<string, google.protobuf.Value> metadata = 3;
+  }
+
+  // A list of recommended Documents. The order represents the ranking (from the
+  // most relevant Document to the least).
+  repeated RecommendationResult results = 1;
+
+  // A unique attribution token. This should be included in the
+  // [UserEvent][google.cloud.discoveryengine.v1beta.UserEvent] logs resulting
+  // from this recommendation, which enables accurate attribution of
+  // recommendation model performance.
+  string attribution_token = 2;
+
+  // IDs of documents in the request that were missing from the default Branch
+  // associated with the requested ServingConfig.
+  repeated string missing_ids = 3;
+
+  // True if
+  // [RecommendRequest.validate_only][google.cloud.discoveryengine.v1beta.RecommendRequest.validate_only]
+  // was set.
+  bool validate_only = 4;
+}

package/build/protos/google/cloud/discoveryengine/v1beta/user_event.proto

@@ -0,0 +1,453 @@
+// Copyright 2022 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.discoveryengine.v1beta;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/cloud/discoveryengine/v1beta/common.proto";
+import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
+
+option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Beta";
+option go_package = "google.golang.org/genproto/googleapis/cloud/discoveryengine/v1beta;discoveryengine";
+option java_multiple_files = true;
+option java_outer_classname = "UserEventProto";
+option java_package = "com.google.cloud.discoveryengine.v1beta";
+option objc_class_prefix = "DISCOVERYENGINE";
+option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1beta";
+option ruby_package = "Google::Cloud::DiscoveryEngine::V1beta";
+
+// UserEvent captures all metadata information DiscoveryEngine API needs to know
+// about how end users interact with customers' website.
+message UserEvent {
+  // 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.
+  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.
+  //
+  // 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.
+  string user_pseudo_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Only required for
+  // [UserEventService.ImportUserEvents][google.cloud.discoveryengine.v1beta.UserEventService.ImportUserEvents]
+  // method. Timestamp of when the user event happened.
+  google.protobuf.Timestamp event_time = 3;
+
+  // Information about the end user.
+  UserInfo user_info = 4;
+
+  // 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.v1beta.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.v1beta.UserEventService.CollectUserEvent].
+  bool direct_user_request = 5;
+
+  // 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 sesion_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.v1beta.UserEvent.user_pseudo_id]
+  // as prefix.
+  string session_id = 6;
+
+  // Page metadata such as categories and other critical information for certain
+  // event types such as `view-category-page`.
+  PageInfo page_info = 7;
+
+  // Token to attribute an API response to user action(s) to trigger the event.
+  //
+  // Highly recommended for user events that are the result of
+  // [PredictionService.Predict][]. This field enables accurate attribution of
+  // recommendation model performance.
+  //
+  // The value must be one of:
+  //
+  // * [PredictResponse.attribution_token][] for events that are the result of
+  // [PredictionService.Predict][].
+  // * [SearchResponse.attribution_token][google.cloud.discoveryengine.v1beta.SearchResponse.attribution_token] for events that are the result of
+  // [SearchService.Search][].
+  // * [CompleteQueryResponse.attribution_token][] for events that are the
+  // result of [SearchService.CompleteQuery][].
+  //
+  // 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 [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][] to this field.
+  string attribution_token = 8;
+
+  // 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
+  // [SearchService.SearchRequest][] may contain a filter expression in
+  // [SearchService.SearchRequest.filter][] conforming to
+  // https://google.aip.dev/160#filtering.
+  //
+  // Similarly, for `view-item-list` events that are generated from a
+  // [PredictionService.PredictRequest][], this field may be populated directly
+  // from [PredictionService.PredictRequest.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.
+  string filter = 9;
+
+  // List of Documents 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.v1beta.UserEvent.documents]
+  // is desired.
+  repeated DocumentInfo documents = 10;
+
+  // Panel metadata associated with this user event.
+  PanelInfo panel = 11;
+
+  // Search API details related to the event.
+  //
+  // This field should be set for `search` event.
+  SearchInfo search_info = 12;
+
+  // CompleteQuery API 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.
+  CompletionInfo completion_info = 13;
+
+  // The transaction metadata (if any) associated with this user event.
+  TransactionInfo transaction_info = 14;
+
+  // 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 on the customer end.
+  repeated string tag_ids = 15;
+
+  // The promotion IDs if this is an event associated with promotions.
+  // Currently, this field is restricted to at most one ID.
+  repeated string promotion_ids = 16;
+
+  // 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 DiscoveryEngine 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.
+  map<string, CustomAttribute> attributes = 17;
+
+  // Media-specific info.
+  MediaInfo media_info = 18;
+}
+
+// Detailed page information.
+message PageInfo {
+  // 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 pageview_id = 1;
+
+  // 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, 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:
+  // "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.
+  string page_category = 2;
+
+  // 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 = 3;
+
+  // 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.
+  string referrer_uri = 4;
+}
+
+// Detailed search information.
+message SearchInfo {
+  // The user's search query.
+  //
+  // See
+  // [SearchRequest.query][google.cloud.discoveryengine.v1beta.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
+  // [search_query][google.cloud.discoveryengine.v1beta.SearchInfo.search_query]
+  // or [page_categories][] is required for `search` events. Other event types
+  // should not set this field. Otherwise, an INVALID_ARGUMENT error is
+  // returned.
+  string search_query = 1;
+
+  // The order in which products are returned, if applicable.
+  //
+  // See
+  // [SearchRequest.order_by][google.cloud.discoveryengine.v1beta.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.
+  string order_by = 2;
+
+  // An integer that specifies the current offset for pagination (the 0-indexed
+  // starting location, amongst the products deemed by the API as relevant).
+  //
+  // See
+  // [SearchRequest.offset][google.cloud.discoveryengine.v1beta.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.
+  optional int32 offset = 3;
+}
+
+// Detailed completion information including completion attribution token and
+// clicked completion info.
+message CompletionInfo {
+  // End user selected [CompleteQueryResponse.CompletionResult.suggestion][].
+  string selected_suggestion = 1;
+
+  // End user selected [CompleteQueryResponse.CompletionResult.suggestion][]
+  // position, starting from 0.
+  int32 selected_position = 2;
+}
+
+// A transaction represents the entire purchase transaction.
+message TransactionInfo {
+  // 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.
+  optional float value = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. Currency code. Use three-character ISO-4217 code.
+  string currency = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // The transaction ID with a length limit of 128 characters.
+  string transaction_id = 3;
+
+  // All the taxes associated with the transaction.
+  optional float tax = 4;
+
+  // 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 =
+  // [value][google.cloud.discoveryengine.v1beta.TransactionInfo.value] -
+  // [tax][google.cloud.discoveryengine.v1beta.TransactionInfo.tax] -
+  // [cost][google.cloud.discoveryengine.v1beta.TransactionInfo.cost]
+  optional float cost = 5;
+
+  // The total discount(s) value applied to this transaction.
+  // This figure should be excluded from
+  // [TransactionInfo.value][google.cloud.discoveryengine.v1beta.TransactionInfo.value]
+  //
+  // For example, if a user paid
+  // [TransactionInfo.value][google.cloud.discoveryengine.v1beta.TransactionInfo.value]
+  // amount, then nominal (pre-discount) value of the transaction is the sum of
+  // [TransactionInfo.value][google.cloud.discoveryengine.v1beta.TransactionInfo.value]
+  // and
+  // [TransactionInfo.discount_value][google.cloud.discoveryengine.v1beta.TransactionInfo.discount_value]
+  //
+  // This means that profit is calculated the same way, regardless of the
+  // discount value, and that
+  // [TransactionInfo.discount_value][google.cloud.discoveryengine.v1beta.TransactionInfo.discount_value]
+  // can be larger than
+  // [TransactionInfo.value][google.cloud.discoveryengine.v1beta.TransactionInfo.value]:
+  //
+  // * Profit =
+  // [value][google.cloud.discoveryengine.v1beta.TransactionInfo.value] -
+  // [tax][google.cloud.discoveryengine.v1beta.TransactionInfo.tax] -
+  // [cost][google.cloud.discoveryengine.v1beta.TransactionInfo.cost]
+  optional float discount_value = 6;
+}
+
+// Detailed document information associated with a user event.
+message DocumentInfo {
+  // A required descriptor of the associated Document.
+  //
+  // * If [id][google.cloud.discoveryengine.v1beta.DocumentInfo.id] is
+  // specified, then the default values for <location>, <data_store_id>, and
+  // <branch_id> are used when annotating with the stored Document.
+  //
+  // * If [name][google.cloud.discoveryengine.v1beta.DocumentInfo.name] is
+  // specified, then the provided values (default values allowed) for
+  // <location>, <data_store_id>, and <branch_id> are used when annotating with
+  // the stored Document.
+  oneof document_descriptor {
+    // Required. The Document resource ID.
+    string id = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // Required. The Document resource full name, of the form:
+    // projects/<project_id>/locations/<location>/dataStores/<data_store_id>/branches/<branch_id>/documents/<document_id>
+    string name = 2 [
+      (google.api.field_behavior) = REQUIRED,
+      (google.api.resource_reference) = {
+        type: "discoveryengine.googleapis.com/Document"
+      }
+    ];
+  }
+
+  // Quantity of the Document associated with the user event. Defaults to 1.
+  //
+  // For example, this field will be 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`
+  optional int32 quantity = 3;
+
+  // The promotion IDs associated with this Document.
+  // Currently, this field is restricted to at most one ID.
+  repeated string promotion_ids = 4;
+}
+
+// Detailed panel information associated with a user event.
+message PanelInfo {
+  // Required. The panel ID.
+  string panel_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // The display name of the panel.
+  string display_name = 3;
+
+  // The ordered position of the panel, if shown to the user with other panels.
+  // If set, then
+  // [total_panels][google.cloud.discoveryengine.v1beta.PanelInfo.total_panels]
+  // must also be set.
+  optional int32 panel_position = 4;
+
+  // The total number of panels, including this one, shown to the user.
+  // Must be set if
+  // [panel_position][google.cloud.discoveryengine.v1beta.PanelInfo.panel_position]
+  // is set.
+  optional int32 total_panels = 5;
+}
+
+// Media-specific user event information.
+message MediaInfo {
+  // The media progress time in seconds, if applicable.
+  // For example, if the end user has finished 90 seconds of a playback video,
+  // then [MediaInfo.media_progress_duration.seconds][Duration.seconds] should
+  // be set to 90.
+  google.protobuf.Duration media_progress_duration = 1;
+
+  // Media progress should be computed using only the 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.
+  optional float media_progress_percentage = 2;
+}